J avolution v5.4 (J2SE 1.6+)

javolution.xml
Class XMLFormat<T>

java.lang.Object
  extended by javolution.xml.XMLFormat<T>

public abstract class XMLFormat<T>
extends java.lang.Object

This class represents the format base class for XML serialization and deserialization.

Application classes typically define a default XML format for their instances using protected static XMLFormat class members. Formats are inherited by sub-classes. For example:

     
     public abstract class Graphic implements XMLSerializable {
         private boolean _isVisible;
         private Paint _paint; // null if none.
         private Stroke _stroke; // null if none.
         private Transform _transform; // null if none.
          
         // XML format with positional associations (members identified by their position),
         // see XML package description for examples of name associations.
         protected static final XMLFormat<Graphic> XML_FORMAT = new XMLFormat<Graphic>(Graphic.class) {
              public void write(Graphic g, OutputElement xml) {
                  xml.setAttribute("isVisible", g._isVisible); 
                  xml.add(g._paint); // First.
                  xml.add(g._stroke); // Second.
                  xml.add(g._transform); // Third.
              }
              public void read(InputElement xml, Graphic g) {
                  g._isVisible = xml.getAttribute("isVisible", true);
                  g._paint = xml.getNext();
                  g._stroke = xml.getNext();
                  g._transform = xml.getNext();
                  return g;
             }
         };
    }

Due to the sequential nature of XML serialization/deserialization, formatting/parsing of XML attributes should always be performed before formatting/parsing of the XML content.

The default mapping between classes and XML formats can be overriden through XMLBinding instances. Here is an example of serialization/deserialization:

     
     // Creates a list holding diverse objects.
     List list = new ArrayList();
     list.add("John Doe");
     list.add(null);
     Map map = new FastMap();
     map.put("ONE", new Integer(1));
     map.put("TWO", new Integer(2));
     list.add(map);
     
     // Use of custom binding.
     XMLBinding binding = new XMLBinding() {
          protected XMLFormat getFormat(Class forClass) throws XMLSreamException  {
              return Map.class.isAssignableFrom(forClass) ?
                  myMapFormat : super.getFormat(forClass); // Overrides the default format for Map instances.
          }
     }
     binding.setAlias(FastMap.class, "Map");
     binding.setAlias(String.class, "String");
     binding.setAlias(Integer.class, "Integer");
     binding.set
     
     // Formats the list to XML .
     OutputStream out = new FileOutputStream("C:/list.xml");
     XMLObjectWriter writer = new XMLObjectWriter().setOutput(out).setBinding(binding);
     writer.write(list, "MyList", ArrayList.class);
     writer.close();
Here is the output list.xml document produced:
     
     <MyList>
         <String value="John Doe"/>
         <Null/>
         <Map>
             <Key class="String" value="ONE"/>
             <Value class="Integer" value="1"/>
             <Key class="String" value="TWO"/>
             <Value class="Integer" value="2"/>
         </Map>
     </MyList>
The list can be read back with the following code:
     
     // Reads back to a FastTable instance.
     InputStream in = new FileInputStream("C:/list.xml");
     XMLObjectReader reader = new XMLObjectReader().setInput(in).setBinding(binding);
     FastTable table = reader.read("MyList", FastTable.class); 
     reader.close();

Note: Any type for which a text format is known can be represented as a XML attribute.

Version:
5.4, December 1, 2009
Author:
Jean-Marie Dautelle

Nested Class Summary
static class XMLFormat.InputElement
          This class represents an input XML element (unmarshalling).
static class XMLFormat.OutputElement
          This class represents an output XML element (marshalling).
 
Field Summary
protected static XMLFormat<java.lang.Appendable> APPENDABLE_XML
          Holds the default XML representation for Appendable instances.
protected static XMLFormat<java.lang.Boolean> BOOLEAN_XML
          Holds the default XML representation for java.lang.Boolean.
protected static XMLFormat<java.lang.Byte> BYTE_XML
          Holds the default XML representation for java.lang.Byte.
protected static XMLFormat<java.lang.Character> CHARACTER_XML
          Holds the default XML representation for java.lang.Character.
protected static XMLFormat<java.lang.Class> CLASS_XML
          Holds the default XML representation for java.lang.Class instances.
protected static XMLFormat<java.util.Collection> COLLECTION_XML
          Holds the default XML representation for java.util.Collection instances.
protected static XMLFormat<Configurable> CONFIGURABLE_XML
          Holds the default XML representation of a configurable.
protected static XMLFormat<java.lang.Double> DOUBLE_XML
          Holds the default XML representation for java.lang.Double.
protected static XMLFormat<FastCollection> FAST_COLLECTION_XML
          Holds the default XML representation for FastCollection instances.
protected static XMLFormat<FastComparator> FAST_COMPARATOR_XML
          Holds the default XML representation for FastComparator instances (format ensures unicity of predefined comparator).
protected static XMLFormat<FastMap> FAST_MAP_XML
          Holds the default XML representation for FastMap instances.
protected static XMLFormat<java.lang.Float> FLOAT_XML
          Holds the default XML representation for java.lang.Float.
protected static XMLFormat<Index> INDEX_XML
          Holds the default XML representation for indexes.
protected static XMLFormat<java.lang.Integer> INTEGER_XML
          Holds the default XML representation for java.lang.Integer.
protected static XMLFormat<java.lang.Long> LONG_XML
          Holds the default XML representation for java.lang.Long.
protected static XMLFormat<java.util.Map> MAP_XML
          Holds the default XML representation for java.util.Map instances.
protected static XMLFormat<java.lang.Object[]> OBJECT_ARRAY_XML
          Holds the default XML representation for java.lang.Object[] instances.
protected static XMLFormat<java.lang.Object> OBJECT_XML
          Holds the static XML format for Object.class instances (default format when a more specialized format does not exist).
protected static XMLFormat<PersistentContext> PERSISTENT_CONTEXT_XML
          Holds the XML representation for persistent contexts (holds persistent reference mapping).
protected static XMLFormat<QName> QNAME_XML
          Holds the XML representation for QName This presentation consists of a "namespaceURI" attribute and alocalName attribute.
protected static XMLFormat<java.lang.Short> SHORT_XML
          Holds the default XML representation for java.lang.Short.
protected static XMLFormat<java.lang.String> STRING_XML
          Holds the default XML representation for java.lang.String instances.
protected static XMLFormat<Text> TEXT_XML
          Holds the default XML representation for Text instances.
 
Constructor Summary
protected XMLFormat(java.lang.Class<T> cls)
          Creates a XML format mapped to the specified class.
 
Method Summary
 java.lang.Class<T> getBoundClass()
          Returns the class/interface statically bound to this format or null if none.
static
<T> XMLFormat<T>
getDefault(java.lang.Class<? extends T> forClass)
          Returns the default format for the specified class/interface.
 boolean isReferenceable()
          Indicates if the object serialized through this format can be referenced to (default true).
 T newInstance(java.lang.Class<T> cls, XMLFormat.InputElement xml)
          Allocates a new object of the specified class from the specified XML input element.
abstract  void read(XMLFormat.InputElement xml, T obj)
          Parses an XML input element into the specified object.
 java.lang.String toString()
          Returns textual information about this format.
abstract  void write(T obj, XMLFormat.OutputElement xml)
          Formats an object into the specified XML output element.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

OBJECT_XML

protected static final XMLFormat<java.lang.Object> OBJECT_XML
Holds the static XML format for Object.class instances (default format when a more specialized format does not exist). The XML representation consists of an empty element with no attribute.


CLASS_XML

protected static final XMLFormat<java.lang.Class> CLASS_XML
Holds the default XML representation for java.lang.Class instances. This representation consists of a "name" attribute holding the class name.


STRING_XML

protected static final XMLFormat<java.lang.String> STRING_XML
Holds the default XML representation for java.lang.String instances. This representation consists of a "value" attribute holding the string.


APPENDABLE_XML

protected static final XMLFormat<java.lang.Appendable> APPENDABLE_XML
Holds the default XML representation for Appendable instances. This representation consists of a "value" attribute holding the characters.


COLLECTION_XML

protected static final XMLFormat<java.util.Collection> COLLECTION_XML
Holds the default XML representation for java.util.Collection instances. This representation consists of nested XML elements one for each element of the collection. The elements' order is defined by the collection iterator order. Collections are deserialized using their default constructor.


MAP_XML

protected static final XMLFormat<java.util.Map> MAP_XML
Holds the default XML representation for java.util.Map instances. This representation consists of key/value pair as nested XML elements. For example:
 <javolution.util.FastMap>
     <Key class="java.lang.String" value="ONE"/>
     <Value class="java.lang.Integer" value="1"/>
     <Key class="java.lang.String" value="TWO"/>
     <Value class="java.lang.Integer" value="2"/>
     <Key class="java.lang.String" value="THREE"/>
     <Value class="java.lang.Integer" value="3"/>
 </javolution.util.FastMap>
The elements' order is defined by the map's entries iterator order. Maps are deserialized using their default constructor.


OBJECT_ARRAY_XML

protected static final XMLFormat<java.lang.Object[]> OBJECT_ARRAY_XML
Holds the default XML representation for java.lang.Object[] instances. This representation consists of nested XML elements one for each element of the array. /


BOOLEAN_XML

protected static final XMLFormat<java.lang.Boolean> BOOLEAN_XML
Holds the default XML representation for java.lang.Boolean. This representation consists of a single "value" attribute holding the value.


BYTE_XML

protected static final XMLFormat<java.lang.Byte> BYTE_XML
Holds the default XML representation for java.lang.Byte. This representation consists of a single "value" attribute holding the value.


CHARACTER_XML

protected static final XMLFormat<java.lang.Character> CHARACTER_XML
Holds the default XML representation for java.lang.Character. This representation consists of a single "value" attribute holding the value.


SHORT_XML

protected static final XMLFormat<java.lang.Short> SHORT_XML
Holds the default XML representation for java.lang.Short. This representation consists of a single "value" attribute holding the value.


INTEGER_XML

protected static final XMLFormat<java.lang.Integer> INTEGER_XML
Holds the default XML representation for java.lang.Integer. This representation consists of a single "value" attribute holding the value.


LONG_XML

protected static final XMLFormat<java.lang.Long> LONG_XML
Holds the default XML representation for java.lang.Long. This representation consists of a single "value" attribute holding the value.


FLOAT_XML

protected static final XMLFormat<java.lang.Float> FLOAT_XML
Holds the default XML representation for java.lang.Float. This representation consists of a single "value" attribute holding the value.


DOUBLE_XML

protected static final XMLFormat<java.lang.Double> DOUBLE_XML
Holds the default XML representation for java.lang.Double. This representation consists of a single "value" attribute holding the value.


TEXT_XML

protected static final XMLFormat<Text> TEXT_XML
Holds the default XML representation for Text instances. This representation consists of a "value" attribute holding the characters.


FAST_MAP_XML

protected static final XMLFormat<FastMap> FAST_MAP_XML
Holds the default XML representation for FastMap instances. This representation is identical to MAP_XML except that it may include the key/value comparators for the map (if different from FastComparator.DEFAULT) and the "shared" attribute.


FAST_COLLECTION_XML

protected static final XMLFormat<FastCollection> FAST_COLLECTION_XML
Holds the default XML representation for FastCollection instances. This representation is identical to COLLECTION_XML.


FAST_COMPARATOR_XML

protected static final XMLFormat<FastComparator> FAST_COMPARATOR_XML
Holds the default XML representation for FastComparator instances (format ensures unicity of predefined comparator).


INDEX_XML

protected static final XMLFormat<Index> INDEX_XML
Holds the default XML representation for indexes. This presentation consists of a "value" attribute holding the index int value.


PERSISTENT_CONTEXT_XML

protected static final XMLFormat<PersistentContext> PERSISTENT_CONTEXT_XML
Holds the XML representation for persistent contexts (holds persistent reference mapping).


CONFIGURABLE_XML

protected static final XMLFormat<Configurable> CONFIGURABLE_XML
Holds the default XML representation of a configurable. Because configurable instances are unique. Deserialisation of a configurable returns this unique instance (typically public static) and configure its value accordingly. The default XML representation consists of the name of the configurable as an attribute and its optional new value as a nested element. For example:
   <javolution.lang.Configurable name="javolution.context.ConcurrentContext#MAXIMUM_CONCURRENCY" />
      <Value class="java.lang.Integer" value="0"/>
   </javolution.lang.Configurable>
 
XML configuration files can be read directly using the Configurable.read(java.io.InputStream) utility method.


QNAME_XML

protected static final XMLFormat<QName> QNAME_XML
Holds the XML representation for QName This presentation consists of a "namespaceURI" attribute and alocalName attribute.

Constructor Detail

XMLFormat

protected XMLFormat(java.lang.Class<T> cls)
Creates a XML format mapped to the specified class. If the specified class is null then the format is left unmapped (unbound formats used by custom binding instances). The static binding is unique and can only be overriden by custom XMLBinding. For example:
    // Overrides default binding for java.util.Collection.
    class MyBinding extends XMLBinding {
        XMLFormat<Collection> collectionXML = new XMLFormat<Collection>(null) { ... }; // Unbound.
        public XMLFormat getFormat(Class cls) {
            if (Collection.isAssignableFrom(cls)) {
                return collectionXML; // Overrides default XML format.
            } else {
                return super.getFormat(cls);
            }
        }
    }

Parameters:
cls - the root class/interface to associate to this XML format or null if this format is not bound.
Throws:
java.lang.IllegalArgumentException - if the specified class is already bound to another format.
Method Detail

getDefault

public static <T> XMLFormat<T> getDefault(java.lang.Class<? extends T> forClass)
Returns the default format for the specified class/interface. If there no direct mapping for the specified class, a mapping for the interfaces being implemented is searched, if still none is found a recurcive search is performed on the superclass. For non-interface this method never returns null as the mapping for object will always be found. For a list of all predefined (default) formats see the protected static members of XMLFormat.

Returns:
the class/interface bound to this format.

getBoundClass

public final java.lang.Class<T> getBoundClass()
Returns the class/interface statically bound to this format or null if none.

Returns:
the class/interface bound to this format.

isReferenceable

public boolean isReferenceable()
Indicates if the object serialized through this format can be referenced to (default true). This method can be overriden to return false if serialized objects are manipulated "by value".

Returns:
true if serialized object may hold a reference; false otherwise.
See Also:
XMLReferenceResolver

newInstance

public T newInstance(java.lang.Class<T> cls,
                     XMLFormat.InputElement xml)
              throws XMLStreamException
Allocates a new object of the specified class from the specified XML input element. By default, this method returns an object created using the public no-arg constructor of the specified class. XML formats may override this method in order to use private/multi-arg constructors.

Parameters:
cls - the class of the object to return.
xml - the XML input element.
Returns:
the object corresponding to the specified XML element.
Throws:
XMLStreamException

write

public abstract void write(T obj,
                           XMLFormat.OutputElement xml)
                    throws XMLStreamException
Formats an object into the specified XML output element.

Parameters:
obj - the object to format.
xml - the XMLElement destination.
Throws:
XMLStreamException

read

public abstract void read(XMLFormat.InputElement xml,
                          T obj)
                   throws XMLStreamException
Parses an XML input element into the specified object.

Parameters:
xml - the XML element to parse.
obj - the object created through newInstance(java.lang.Class, javolution.xml.XMLFormat.InputElement) and to setup from the specified XML element.
Throws:
XMLStreamException

toString

public java.lang.String toString()
Returns textual information about this format.

Overrides:
toString in class java.lang.Object
Returns:
this format textual information.

J avolution v5.4 (J2SE 1.6+)

Copyright © 2005 - 2009 Javolution.