de.fu_berlin.ties.io
Class FieldContainer

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

public class FieldContainer
extends Object

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.16 $, $Date: 2004/11/09 10:11:29 $, $Author: siefkes $
Author:
Christian Siefkes

Constructor Summary
FieldContainer()
          Creates a new empty instance.
FieldContainer(StorableContainer contents)
          Creates a new instance and populates it from a StorableContainer.
 
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)
          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.
protected  boolean addKey(String key)
          Helper method that adds a key to the set of all keys.
 int attributeCount()
          Returns the number of attributes stored in this container.
 Iterator<String> attributeIterator()
          Returns an iterator over the names of the attributes stored in this container.
 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()
          Factory method that creates a field container in DelimSepValues format.
static FieldContainer createFieldContainer(CharSequence input)
          Factory method that creates a field container from serialized data in DelimSepValues format.
static FieldContainer createFieldContainer(InputStream in)
          Factory method that creates a field container from serialized data in DelimSepValues format.
static FieldContainer createFieldContainer(Reader reader)
          Factory method that creates a field container from serialized data in DelimSepValues format.
 FieldContainer createNestedContainer(String name)
          Creates and returns a new nested subcontainer.
 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.
 Object getAttribute(String name)
          Returns the value of an attribute.
 FieldContainer getNestedContainer(String name)
          Returns a nested subcontainer managed by this instance.
 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.
 int nestedCount()
          Returns the number of nested containers managed by container.
 Iterator<String> nestedIterator()
          Returns an iterator over the names of nested containers managed by this container.
static String recommendedExtension()
          Returns the file extension recommended for FieldContainers.
 Object setAttribute(String name, Object value)
          Sets name and value of an attribute.
 int size()
          Returns the number of entries stored in this container.
 void store(OutputStream out)
          Serializes contents by wrapping the stream in a writer with UTF-8 character set and delegating to store(Writer).
 void store(Writer writer)
          Subclasses can overwrite this method to serialize their contents in a class-specific format.
 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(StorableContainer contents)
Creates a new instance and populates it from a StorableContainer.

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

createFieldContainer

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

Returns:
the created container

createFieldContainer

public static FieldContainer createFieldContainer(CharSequence input)
                                           throws IllegalArgumentException
Factory method that creates a field container from serialized data in DelimSepValues format.

Parameters:
input - the input data to process
Returns:
the created container
Throws:
IllegalArgumentException - if the input data contains errors

createFieldContainer

public static FieldContainer createFieldContainer(InputStream in)
                                           throws IOException,
                                                  IllegalArgumentException
Factory method that creates a field container from serialized data in DelimSepValues format. Internally uses IOUtils.openCompressableInStream(InputStream) so gzip-compressed streams are also supported.

Parameters:
in - a stream containing the input data to process, must use the UTF-8 charset; the stream is not closed by this method
Returns:
the created container
Throws:
IOException - if an I/O error occurs while reading from the stream
IllegalArgumentException - if the input data contains errors

createFieldContainer

public static FieldContainer createFieldContainer(Reader reader)
                                           throws IOException,
                                                  IllegalArgumentException
Factory method that creates a field container from serialized data in DelimSepValues format.

Parameters:
reader - a reader containing the input data to process; not closed by this method
Returns:
the created container
Throws:
IOException - if an I/O error occurs while reading from the stream
IllegalArgumentException - if the input data contains errors

recommendedExtension

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

Returns:
the recommended extension: DelimSepValues.FILE_EXT

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

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)
         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
Throws:
IllegalArgumentException - if the specified array contains more elements than the set of all keys

attributeCount

public int attributeCount()
Returns the number of attributes stored in this container.

Returns:
the number of attributes

attributeIterator

public Iterator<String> attributeIterator()
Returns an iterator over the names of the attributes stored in this container.

Returns:
an iterator over the attribute names

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

createNestedContainer

public FieldContainer createNestedContainer(String name)
                                     throws IllegalArgumentException
Creates and returns a new nested subcontainer.

Parameters:
name - the name of the new subcontainer
Returns:
the newly created nested container
Throws:
IllegalArgumentException - if the specified name contains whitespace or is null or empty or if a nested container with the given name already exists

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

getAttribute

public Object getAttribute(String name)
Returns the value of an attribute.

Parameters:
name - the name of the attribute to look up
Returns:
the value of the attribute; or null if the attribute doesn't exist

getNestedContainer

public FieldContainer getNestedContainer(String name)
Returns a nested subcontainer managed by this instance.

Parameters:
name - the name of the container to retrieve
Returns:
the nested container; or null if there is no container with this name

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

nestedCount

public int nestedCount()
Returns the number of nested containers managed by container.

Returns:
the number of nested containers

nestedIterator

public Iterator<String> nestedIterator()
Returns an iterator over the names of nested containers managed by this container.

Returns:
an iterator over the names of nested containers

size

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

Returns:
the number of entries

store

public void store(OutputStream out)
           throws IOException
Serializes contents by wrapping the stream in a writer with UTF-8 character set 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

setAttribute

public Object setAttribute(String name,
                           Object value)
                    throws IllegalArgumentException
Sets name and value of an attribute.

Parameters:
name - the name of the attribute, must not contain whitespace
value - to value of the attribute
Returns:
the previous value associated with the specified attribute name, or null if there was no previous value
Throws:
IllegalArgumentException - if the specified name contains whitespace or is null or empty

store

public void store(Writer writer)
           throws IOException,
                  UnsupportedOperationException
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 - might be thrown by subclasses if an I/O error occurs while serializing the data
UnsupportedOperationException - always thrown by instances of this class

toString

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

Overrides:
toString in class Object
Returns:
a textual representation


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