de.fu_berlin.ties.io
Class FieldMap

java.lang.Object
  extended by java.util.AbstractMap<K,V>
      extended by java.util.HashMap<K,V>
          extended by java.util.LinkedHashMap<String,Object>
              extended by de.fu_berlin.ties.io.FieldMap
All Implemented Interfaces:
XMLStorable, Serializable, Cloneable, Map<String,Object>

public class FieldMap
extends LinkedHashMap<String,Object>
implements XMLStorable

A map targeted at serialization and deserialiation of objects in human-readable formats. It that allows creating (deserializing) an object by passing itself to the constructor.

This class preserves the guarantees of LinkedHashMap: it allows both efficient retrieval of values by key/field name (due to the contained hash map) and iteration of key/value pairs in order of insertion (due to the contained linked list).

Note that this implementation is not synchronized. If multiple threads access a field map concurrently, and at least one of the threads modifies the map structurally, it must be synchronized externally. This is typically accomplished by synchronizing on some object that naturally encapsulates the map. If no such object exists, the map should be "wrapped" using the Collections.synchronizedMap(java.util.Map) method.

Version:
$Revision: 1.9 $, $Date: 2006/10/21 16:04:22 $, $Author: siefkes $
Author:
Christian Siefkes
See Also:
Serialized Form

Constructor Summary
FieldMap()
          Creates a new instance, setting the section number to 0.
FieldMap(Element element)
          Creates a new instance from an XML element, fulfilling the recommandation of the XMLStorable interface.
FieldMap(Element element, int sectionNo)
          Creates a new instance from an XML element, fulfilling the recommandation of the XMLStorable interface.
FieldMap(int sectionNo)
          Creates a new instance.
FieldMap(Map<String,Object> map)
          Creates a new instance with the same mappings as the specified map, setting the section number to 0.
FieldMap(Map<String,Object> map, int sectionNo)
          Creates a new instance with the same mappings as the specified map.
FieldMap(String firstKey, Object firstValue)
          Convenience constructor that delegates to the standard constructor and then puts a first key/value pair into the map.
 
Method Summary
 Object createObject(Class type)
          Creates (deserializes) an object of a specified type by calling a constructor of the class that accepts a field map as single argument and passing itself as parameter.
 int getSection()
          Returns the number of the section this field map is in.
 ObjectElement toElement()
          Stores all relevant fields of this object in an XML element for serialization. This implementation delegates to toElement(boolean), setting the Java attribute.
 ObjectElement toElement(boolean setJavaAttrib)
          Stores all relevant fields of this object in an XML element for serialization.
 
Methods inherited from class java.util.LinkedHashMap
clear, containsValue, get, removeEldestEntry
 
Methods inherited from class java.util.HashMap
clone, containsKey, entrySet, isEmpty, keySet, put, putAll, remove, size, values
 
Methods inherited from class java.util.AbstractMap
equals, hashCode, toString
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface java.util.Map
containsKey, entrySet, equals, hashCode, isEmpty, keySet, put, putAll, remove, size, values
 

Constructor Detail

FieldMap

public FieldMap()
Creates a new instance, setting the section number to 0.


FieldMap

public FieldMap(Map<String,Object> map)
         throws NullPointerException
Creates a new instance with the same mappings as the specified map, setting the section number to 0.

Parameters:
map - the map whose mappings are to be placed in this map
Throws:
NullPointerException - if the specified map is null

FieldMap

public FieldMap(String firstKey,
                Object firstValue)
Convenience constructor that delegates to the standard constructor and then puts a first key/value pair into the map.

Parameters:
firstKey - the key of the first key/value pair
firstValue - the value of the first key/value pair

FieldMap

public FieldMap(int sectionNo)
Creates a new instance.

Parameters:
sectionNo - the number of the section this field map is in

FieldMap

public FieldMap(Map<String,Object> map,
                int sectionNo)
         throws NullPointerException
Creates a new instance with the same mappings as the specified map.

Parameters:
map - the map whose mappings are to be placed in this map
sectionNo - the number of the section this field map is in
Throws:
NullPointerException - if the specified map is null

FieldMap

public FieldMap(Element element)
         throws IllegalArgumentException
Creates a new instance from an XML element, fulfilling the recommandation of the XMLStorable interface. The section number is set to 0.

Parameters:
element - the XML element containing the serialized representation
Throws:
IllegalArgumentException - if the element contains child elements

FieldMap

public FieldMap(Element element,
                int sectionNo)
         throws IllegalArgumentException
Creates a new instance from an XML element, fulfilling the recommandation of the XMLStorable interface.

Parameters:
element - the XML element containing the serialized representation
sectionNo - the number of the section this field map is in
Throws:
IllegalArgumentException - if the element contains child elements
Method Detail

createObject

public Object createObject(Class type)
                    throws InstantiationException,
                           SecurityException
Creates (deserializes) an object of a specified type by calling a constructor of the class that accepts a field map as single argument and passing itself as parameter. Only classes that provide a suitable constructor can be instantiated this way.

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

getSection

public int getSection()
Returns the number of the section this field map is in. Generally, a FieldContainers contains one or multiple sections which are numbered sequentially starting from 0. In case of the DSV format, sections are separated by empty lines.

Returns:
the section number

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(boolean), setting the Java attribute.

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

toElement

public ObjectElement toElement(boolean setJavaAttrib)
Stores all relevant fields of this object in an XML element for serialization. The key of the first field is used to name the element, the corresponding value is stored in the textual content of the. Keys and values of all further fields are stored in attribute name/value pairs. If this field map is empty, null is returned.

Parameters:
setJavaAttrib - whether to store the class of this object in the ObjectElement.JAVA_CLASS_ATTRIBUTE attribute; if false this attribute is not used
Returns:
the created XML element


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