de.fu_berlin.ties.io
Class FieldContainer

java.lang.Object
  extended by de.fu_berlin.ties.io.FieldContainer
All Implemented Interfaces:
XMLStorable
Direct Known Subclasses:
DelimSepValues

public class FieldContainer
extends Object
implements XMLStorable

A container of FieldMaps. A container stores all field maps added to itself and keeps a set of all keys found in the field maps. This is an "append-only" container; field maps can only be added but never removed.

Instances of this class are not thread-safe and must be synchronized externally, if required.

Version:
$Revision: 1.26 $, $Date: 2006/10/21 16:04:22 $, $Author: siefkes $
Author:
Christian Siefkes

Constructor Summary
FieldContainer()
          Creates a new empty instance.
FieldContainer(Element element)
          Creates a new instance from an XML element, fulfilling the recommandation of the XMLStorable interface.
 
Method Summary
 void add(FieldMap map)
          Adds a field map to this container.
protected  void add(FieldMap map, boolean checkKeys)
          Helper method for adding a field map to this container.
 void add(List values, int sectionNo)
          Adds a field map created from the specified values, using the n-th key from the set of all keys for the n-th specified value.
 void add(Storable storable)
          Adds the representation of a Storable to this container, by calling its Storable.storeFields() method and adding the resulting field map.
 void add(StorableContainer contents)
          Adds the contents of a StorableContainer to this container, by delegating to StorableContainer.storeEntries(FieldContainer).
protected  boolean addKey(String key)
          Helper method that adds a key to the set of all keys.
 FieldMap backgroundMap()
          This map can be used to extend newly added field maps: at each add(FieldMap) operation, any key/value pairs from this map are added to field map prior to storing it.
static FieldContainer createFieldContainer(TiesConfiguration config)
          Factory method that creates a field container in DelimSepValues format.
 List<Object> createObjects(Class type)
          Creates (deserializes) an list of objects of a specified type by calling FieldMap.createObject(Class) for each of the field maps contained in this container.
 Iterator<FieldMap> entryIterator()
          Returns an iterator over the FieldMaps in this container in the order they were added.
 int keyCount()
          Returns the number of keys in this container.
 Iterator<String> keyIterator()
          Returns an iterator over the set of all keys used in contained field maps.
 void read(CharSequence input)
          Subclasses can overwrite this method to deserialize their contents in a class-specific format.
 void read(InputStream in)
          Read deserialized data.
 void read(Reader reader)
          Read deserialized data.
static String recommendedExtension()
          Returns the file extension recommended for FieldContainers.
 int size()
          Returns the number of entries stored in this container.
 void store(OutputStream out)
          Serializes contents by wrapping the stream in a Unicode writer and delegating to store(Writer).
 void store(Writer writer)
          Subclasses can overwrite this method to serialize their contents in a class-specific format.
static File storeContainerInFile(StorableContainer sContainer, File directory, String baseName, String extension, TiesConfiguration config)
          Convenience method that serializes the contents of a container in a file in standard format, delegating to createFieldContainer(TiesConfiguration) and storeInFile(File, String, String, Configuration).
 File storeInFile(File directory, String baseName, String extension, Configuration config)
          Convenience method for serializing the contents of this container in a file.
 ObjectElement toElement()
          Stores all relevant fields of this object in an XML element for serialization. This implementation delegates to toElement(String), setting the name of the main element to "list".
 ObjectElement toElement(QName name)
          Stores all contents of this container in an XML element for serialization, without using a medium level.
 ObjectElement toElement(QName name, QName level2Name)
          Stores all contents of this container in an XML element for serialization.
 ObjectElement toElement(String localName)
          Stores all contents of this container in an XML element for serialization.
 String toString()
          Returns a string representation of this object.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

FieldContainer

public FieldContainer()
Creates a new empty instance.


FieldContainer

public FieldContainer(Element element)
Creates a new instance from an XML element, fulfilling the recommandation of the XMLStorable interface.

Parameters:
element - the XML element containing the serialized representation
Method Detail

createFieldContainer

public static FieldContainer createFieldContainer(TiesConfiguration config)
Factory method that creates a field container in DelimSepValues format.

Parameters:
config - used to configure the container
Returns:
the created container

recommendedExtension

public static String recommendedExtension()
Returns the file extension recommended for FieldContainers.

Returns:
the recommended extension: DelimSepValues.FILE_EXT

storeContainerInFile

public static File storeContainerInFile(StorableContainer sContainer,
                                        File directory,
                                        String baseName,
                                        String extension,
                                        TiesConfiguration config)
                                 throws IOException
Convenience method that serializes the contents of a container in a file in standard format, delegating to createFieldContainer(TiesConfiguration) and storeInFile(File, String, String, Configuration).

Parameters:
sContainer - the container to serialize
directory - the directory in which to store the data
baseName - the base name of the file using for storing the data
extension - the file extension to use; if null, the recommended extension is used
config - used to determine the container format and output character set
Returns:
the file used for storing the data
Throws:
IOException - if an I/O error occurs

addKey

protected boolean addKey(String key)
Helper method that adds a key to the set of all keys.

Parameters:
key - the key to add
Returns:
true if the set did not already contain the specified element

add

public void add(FieldMap map)
Adds a field map to this container. Any new keys in this set are added at the end of the set of all keys, in the order of the field map's key set.

Parameters:
map - the field map to add

add

public void add(Storable storable)
Adds the representation of a Storable to this container, by calling its Storable.storeFields() method and adding the resulting field map.

Parameters:
storable - the storable whose fields to add

add

public void add(StorableContainer contents)
Adds the contents of a StorableContainer to this container, by delegating to StorableContainer.storeEntries(FieldContainer).

Parameters:
contents - the contents to add by calling StorableContainer.storeEntries(FieldContainer)

add

protected void add(FieldMap map,
                   boolean checkKeys)
Helper method for adding a field map to this container.

Parameters:
map - the field map to add
checkKeys - whether to check the keys of the field map and add any missing keys to the set of all keys; subclasses calling this method can set this to false iff they know for sure that the map does not contain any new keys

add

public void add(List values,
                int sectionNo)
         throws IllegalArgumentException
Adds a field map created from the specified values, using the n-th key from the set of all keys for the n-th specified value. Empty strings and null values are omitted (the corresponding key is skipped).

Parameters:
values - the list of values to store in the field map
sectionNo - the number of the current section
Throws:
IllegalArgumentException - if the specified array contains more elements than the set of all keys

backgroundMap

public FieldMap backgroundMap()
This map can be used to extend newly added field maps: at each add(FieldMap) operation, any key/value pairs from this map are added to field map prior to storing it. The map is empty by default.

Returns:
the background map

createObjects

public List<Object> createObjects(Class type)
                           throws InstantiationException,
                                  SecurityException
Creates (deserializes) an list of objects of a specified type by calling FieldMap.createObject(Class) for each of the field maps contained in this container. The contained field maps are deserialized in the order they were added to this container.

Parameters:
type - the class of the objects to create; must have a constructor whose only argument is a FieldMap
Returns:
a list of the created object; all elements of this list will be instances of the specified class
Throws:
InstantiationException - if instantiation failed
SecurityException - if access to the required reflection information is denied

entryIterator

public Iterator<FieldMap> entryIterator()
Returns an iterator over the FieldMaps in this container in the order they were added.

Returns:
an iterator over the contained field maps

keyCount

public int keyCount()
Returns the number of keys in this container.

Returns:
the number of keys, i.e. the size of the set of all keys

keyIterator

public Iterator<String> keyIterator()
Returns an iterator over the set of all keys used in contained field maps.

Returns:
an iterator over the set of all keys

read

public void read(CharSequence input)
Subclasses can overwrite this method to deserialize their contents in a class-specific format. This class does not prescribe a specific format and thus cannot read the data, throwing an UnsupportedOperationException instead.

Parameters:
input - the input data to process

read

public final void read(InputStream in)
                throws IOException
Read deserialized data. This method wraps the stream in a Unicode reader and delegates to read(Reader). Internally uses IOUtils.openCompressableInStream(InputStream) so gzip-compressed streams are also supported.

Parameters:
in - the input stream to read from; not closed by this method
Throws:
IOException - if an I/O error occurs while reading the data

read

public final void read(Reader reader)
                throws IOException
Read deserialized data. This method delegates to read(CharSequence).

Parameters:
reader - the reader to read from; not closed by this method
Throws:
IOException - if an I/O error occurs while reading the data

size

public int size()
Returns the number of entries stored in this container.

Returns:
the number of entries

store

public final void store(OutputStream out)
                 throws IOException
Serializes contents by wrapping the stream in a Unicode writer and delegating to store(Writer).

Parameters:
out - the output stream to write to; flushed but not closed by this method
Throws:
IOException - if an I/O error occurs while writing to the stream

store

public void store(Writer writer)
           throws IOException
Subclasses can overwrite this method to serialize their contents in a class-specific format. This class does not prescribe a specific format and thus cannot store the data, throwing an UnsupportedOperationException instead.

Parameters:
writer - the writer to write to; not closed by this method
Throws:
IOException - if an I/O error occurs while serializing the data

storeInFile

public File storeInFile(File directory,
                        String baseName,
                        String extension,
                        Configuration config)
                 throws IOException
Convenience method for serializing the contents of this container in a file.

Parameters:
directory - the directory in which to store the data
baseName - the base name of the file using for storing the data
extension - the file extension to use; if null, the recommended extension is used
config - used to determine the output character set (by delegating to IOUtils.openWriter(File, Configuration)
Returns:
the file used for storing the data
Throws:
IOException - if an I/O error occurs

toElement

public ObjectElement toElement()
Stores all relevant fields of this object in an XML element for serialization. An equivalent object can be created by calling ObjectElement.createObject(org.dom4j.Element, Class) on the created element. This implementation delegates to toElement(String), setting the name of the main element to "list".

Specified by:
toElement in interface XMLStorable
Returns:
the created XML element

toElement

public ObjectElement toElement(QName name)
Stores all contents of this container in an XML element for serialization, without using a medium level.

Parameters:
name - the qualified name to use for the main element
Returns:
the created XML element

toElement

public ObjectElement toElement(QName name,
                               QName level2Name)
Stores all contents of this container in an XML element for serialization. If a level2Name is given, an element of this name is created for each non-empty section in this container; each field map is stored as child element of section it is in. Otherwise (if level2Name is null) all field maps are stored as direct child elements of the main element, without using a medium level.

Parameters:
name - the qualified name to use for the main element
level2Name - the name of elements inserted as medium level; or null if no medium level should be used
Returns:
the created XML element

toElement

public ObjectElement toElement(String localName)
Stores all contents of this container in an XML element for serialization. All field maps stored in this container are added as child elements.

Parameters:
localName - the local name to use for the main element, will be converted into a qualified name by calling DOMUtils.defaultName(String)
Returns:
the created XML element

toString

public String toString()
Returns a string representation of this object.

Overrides:
toString in class Object
Returns:
a textual representation


Copyright © 2003-2007 Christian Siefkes. All Rights Reserved.