net.sf.basedb.util.bfs
Class MetadataWriter

java.lang.Object
  java.io.Writer
      java.io.PrintWriter
          net.sf.basedb.util.bfs.MetadataWriter

All Implemented Interfaces:

Closeable, Flushable, Appendable

public class MetadataWriter
extends PrintWriter

Writer implementation for writing BFS metadata files. The start of file marker (BFSformat) is written immediately at object construction. Use the bfsPrintSection(String, boolean, boolean) to start a new section, and bfsPrintValue(String, String...) to print a section entry. It is not recommended that any of the superclass methods (eg. PrintWriter methods} are used directly as it can create an invalid BFS metadata file.

This class can be subclassed to get specific functionality in specific use cases.

Version:

2.15

Author:

Nicklas

Last modified

$Date: 2010-08-13 10:50:27 +0200 (Fri, 13 Aug 2010) $

Field Summary

static String	BOF_MARKER
private String	currentSection
private EncoderDecoder	encoder
private String	filename
private int	lineCount
private int	sectionCount
private String	subtype
private boolean	uniqueKeys
private Set<String>	usedKeys
private Set<String>	usedSections
private int	valueCount

Fields inherited from class java.io.PrintWriter

out

Fields inherited from class java.io.Writer

lock

Constructor Summary

MetadataWriter(Writer out)
Create a new BFS metadata writer.

Method Summary

void	bfsPrintComment(String comment) Prints one or more comment lines to the metadata file.
void	bfsPrintEmptyLine(int num) Print one or more empty lines to the metadata file.
void	bfsPrintSection(String name, boolean unique, boolean uniqueKeys) Start a new section.
<T> void	bfsPrintValue(String key, Formatter<T> formatter, T... values) Prints a section entry.
void	bfsPrintValue(String key, String... values) Prints a section entry.
<T> void	bfsPrintValue(String key, T... values) Prints a section entry.
static MetadataWriter	create(File file) Utility method for creating a metadata writer to a file in the BASE file system.
static MetadataWriter	create(File file) Utility method for creating a metadata writer to a file in the native file system.
static MetadataWriter	create(OutputStream out, String filename) Utility method for creating a metadata writer when you have an output stream.
String	encodeValue(String value) Encode a value for use in a BFS file.
String	getCurrentSection() Get the name of the current section.
String	getFilename() Get the file name that this writer is printing to.
int	getLineCount() Get the number of lines that has been written to this file so far, including all comment lines, empty lines, sections headers, etc.
int	getSectionCount() Get the number of sections that has been written to this file so far.
String	getSubtype() Get the BFS subtype.
boolean	getUniqueKeys() Checks if the current section requires entry names to be unique or not.
int	getValueCount() Get the number of values that has been written to the current section so far.
protected void	internalPrintBofMarker() Prints the beginning-of-file marker.
protected void	internalPrintComment(String comment) Print a single-line comment.
protected void	internalPrintSection(String encodedName) Prints a section header assuming that the name has already been encoded.
protected void	internalPrintValue(String encodedKey, String encodedValue) Prints a section entry assuming that the key and value has already been encoded.
boolean	isUsedKey(String key) Checks if the current section already has an entry for the given key or not.
void	setFilename(String filename) Set the file name that this writer is printing to.
void	setSubtype(String subtype) Set the BFS subtype for this writer.

Methods inherited from class java.io.PrintWriter

append, append, append, checkError, clearError, close, flush, format, format, print, print, print, print, print, print, print, print, print, printf, printf, println, println, println, println, println, println, println, println, println, println, setError, write, write, write, write, write

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

BOF_MARKER

public static final String BOF_MARKER

See Also:

Constant Field Values

encoder

private final EncoderDecoder encoder

filename

private String filename

subtype

private String subtype

usedSections

private Set<String> usedSections

usedKeys

private Set<String> usedKeys

currentSection

private String currentSection

uniqueKeys

private boolean uniqueKeys

lineCount

private int lineCount

sectionCount

private int sectionCount

valueCount

private int valueCount

Constructor Detail

MetadataWriter

public MetadataWriter(Writer out)

Create a new BFS metadata writer.

Parameters:

out - The parent writer which this writer will print to

Method Detail

create

public static MetadataWriter create(OutputStream out,
                                    String filename)

Utility method for creating a metadata writer when you have an output stream.

Parameters:

out - The output stream the metadata writer should print to

filename - Optional, the name of the file the output stream is printing to

create

public static MetadataWriter create(File file)

Utility method for creating a metadata writer to a file in the BASE file system. The character set and MIME type on the file are automatically updated.

Parameters:

file - The file in the BASE file system

create

public static MetadataWriter create(File file)
                             throws IOException

Utility method for creating a metadata writer to a file in the native file system. If the file doesn't exists, it is created.

Parameters:

file - The file in the native file system

Throws:

IOException

getFilename

public String getFilename()

Get the file name that this writer is printing to.

Returns:

The file name or null if not known

setFilename

public void setFilename(String filename)

Set the file name that this writer is printing to.

getSubtype

public String getSubtype()

Get the BFS subtype.

Returns:

The unencoded subtype, or null if no subtype was specified when the object was created

setSubtype

public void setSubtype(String subtype)

Set the BFS subtype for this writer. This method must be called before any printing method is called.

Parameters:

subtype - The subtype

Throws:

IllegalStateException - If data has already been written

getCurrentSection

public String getCurrentSection()

Get the name of the current section.

Returns:

The unencoded name of the section, or null if no section has been started yet

getUniqueKeys

public boolean getUniqueKeys()

Checks if the current section requires entry names to be unique or not.

isUsedKey

public boolean isUsedKey(String key)

Checks if the current section already has an entry for the given key or not.

Parameters:

key - The key to check

Returns:

TRUE if the current section already has an entry for this key, FALSE otherwise

encodeValue

public String encodeValue(String value)

Encode a value for use in a BFS file. There is usually no need to call this method, since values are automatically encoded.

Parameters:

value - The value to encode, may be null

Returns:

The encoded value

getLineCount

public int getLineCount()

Get the number of lines that has been written to this file so far, including all comment lines, empty lines, sections headers, etc.

getSectionCount

public int getSectionCount()

Get the number of sections that has been written to this file so far.

getValueCount

public int getValueCount()

Get the number of values that has been written to the current section so far.

bfsPrintEmptyLine

public void bfsPrintEmptyLine(int num)

Print one or more empty lines to the metadata file.

Parameters:

num - The number of empty lines to print. If 0 or negative nothing is written

bfsPrintComment

public void bfsPrintComment(String comment)

Prints one or more comment lines to the metadata file. A null comment is ignored. If the comment contains line-breaks and/or carriage returns, it will be split and written to multiple lines.

Parameters:

comment - The comment string

bfsPrintSection

public void bfsPrintSection(String name,
                            boolean unique,
                            boolean uniqueKeys)

Start a new section.

Parameters:

name - The name of the section, null is not allowed

unique - TRUE if this section must be unique within the metadata file

uniqueKeys - TRUE if all keys in this section must be unique

Throws:

NullPointerException - If the section name is null

IllegalArgumentException - If the name is not unique and the writer requires unique sections

bfsPrintValue

public void bfsPrintValue(String key,
                          String... values)

Prints a section entry. A section must have been started with bfsPrintSection(String, boolean, boolean) before this method is invoked.

Parameters:

key - The entry key; null is not allowed and it may not start with '[' or '#'

values - An array of string values, each value will be encoded independently and separated with a tab

Throws:

NullPointerException - If the key is null

IllegalArgumentException - If the key starts with '[' or '#', or if the key is not unique within a section that requires unique keys

IllegalStateException - If no section has been started

bfsPrintValue

public <T> void bfsPrintValue(String key,
                              T... values)

Prints a section entry. A section must have been started with bfsPrintSection(String, boolean, boolean) before this method is invoked.

Parameters:

key - The entry key; null is not allowed and it may not start with '[' or '#'

values - An array of objects, each value will be be converted to a string by calling the toString() method

Throws:

NullPointerException - If the key is null

IllegalArgumentException - If the key starts with '[' or '#', or if the key is not unique within a section that requires unique keys

IllegalStateException - If no section has been started

bfsPrintValue

public <T> void bfsPrintValue(String key,
                              Formatter<T> formatter,
                              T... values)

Prints a section entry. A section must have been started with bfsPrintSection(String, boolean, boolean) before this method is invoked.

Parameters:

key - The entry key; null is not allowed and it may not start with '[' or '#'

formatter - A formatter that should be used to convert the values to strings, or null to simply use the toString() method

values - An array of objects, each value will be encoded independently and separated with a tab

Throws:

NullPointerException - If the key is null

IllegalArgumentException - If the key starts with '[' or '#', or if the key is not unique within a section that requires unique keys

IllegalStateException - If no section has been started

internalPrintBofMarker

protected void internalPrintBofMarker()

Prints the beginning-of-file marker. Eg. BFSformat<tab>subtype

internalPrintComment

protected void internalPrintComment(String comment)

Print a single-line comment. This method should not be called with comment string that is null or contain line-breaks. Updates the line counter.

internalPrintSection

protected void internalPrintSection(String encodedName)

Prints a section header assuming that the name has already been encoded. Updates line and section counters and resets the value counter.

internalPrintValue

protected void internalPrintValue(String encodedKey,
                                  String encodedValue)

Prints a section entry assuming that the key and value has already been encoded. Updates the line and value counters.