de.fu_berlin.ties.io
Class FieldContainer

java.lang.Object
  extended byde.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.7 $, $Date: 2004/04/13 08:13: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(Object key)
          Helper method that adds a key to to the set of all keys.
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.
 List 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 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 keyIterator()
          Returns an iterator over the set of all keys used in contained field maps.
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 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.

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(Object key)
Helper method that adds a key to 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

createObjects

public List 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 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 keyIterator()
Returns an iterator over the set of all keys used in contained field maps.

Returns:
an iterator over the set of all keys

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). Subclasses can overwrite this method, e.g. if they prefer another character set.

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,
                  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.

Returns:
a textual representation


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