javolution.xml
Class XmlFormat<T>

java.lang.Object
  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 XML format for their instances using static XmlFormat class members. The format is inherited by sub-classes. For example:

     public abstract class Graphic {
         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> GRAPHIC_XML = new XmlFormat<Graphic>(Graphic.class) {
              public void format(Graphic g, XmlElement xml) {
                  xml.setAttribute("isVisible", g._isVisible); 
                  xml.add(g._paint); // First.
                  xml.add(g._stroke); // Second.
                  xml.add(g._transform); // Third.
              }
              public Graphic parse(XmlElement xml) {
                  Graphic g = xml.object();
                  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.

Xml formats can dynamically associated. For example:

 
     // XML Conversion (different formats for reading and writing).
     XmlFormat<Foo> readFormat = new XmlFormat<Foo>() {...};
     XmlFormat<Foo> writeFormat = new XmlFormat<Foo>() {...};
     LocalContext.enter();
     try {  // Local context to avoid impacting other threads.
        XmlFormat.setFormat(Foo.class, readFormat);
        Foo foo = new ObjectReader<Foo>().read(in);
        XmlFormat.setFormat(Foo.class, writeFormat);
        new ObjectWriter<Foo>().write(foo, out);
     } finally {
        LocalContext.exit();
     }
     
     // Temporary change of String format during formatting.
     public void format(List list, XmlElement xml) {
         LocalContext.enter();
         try {  // Always safer to scope the change.
             XmlFormat.setFormat(String.class, MY_STRING_FORMAT);
             for (Object elem : list)  {
                 xml.add(elem);
             }
        } finally {
            LocalContext.exit(); 
        }      
     }

A default format is defined for null values (<null/>) and the following types:

• java.lang.Object (default)
• java.lang.Class
• java.lang.String
• javolution.lang.Text
• java.lang.Appendable
• java.util.Collection
• java.util.Map
• and all primitive types wrappers (e.g. Boolean, Integer ...)

Here is an example of serialization/deserialization using predefined formats:

     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);
     ObjectWriter ow = new ObjectWriter();
     ow.write(list, new FileOutputStream("C:/list.xml"));

Here is the output list.xml document produced:

     <java.util.ArrayList xmlns:j="http://javolution.org">
         <java.lang.String value="John Doe"/>
         <null/>
         <javolution.util.FastMap>
             <Key j:class="java.lang.String" value="ONE"/>
             <Value j:class="java.lang.Integer" value="1"/>
             <Key j:class="java.lang.String" value="TWO"/>
             <Value j:class="java.lang.Integer" value="2"/>
         </javolution.util.FastMap>

The list can be read back with the following code:

     ObjectReader or = new ObjectReader();
     List list = (List) or.read(new FileInputStream("C:/list.xml"));
     

Finally, xml formats can be made impervious to obfuscation by setting local aliases for the obfuscated classes.

Version:

3.6, October 13, 2005

Author:

Jean-Marie Dautelle

Field Summary

static XmlFormat<java.lang.Appendable>	APPENDABLE_XML Holds the default XML representation for java.lang.Appendable classes.
static XmlFormat<java.lang.Boolean>	BOOLEAN_XML Holds the default XML representation for java.lang.Boolean.
static XmlFormat<java.lang.Byte>	BYTE_XML Holds the default XML representation for java.lang.Byte.
static XmlFormat<java.lang.Character>	CHARACTER_XML Holds the default XML representation for java.lang.Character.
static XmlFormat<java.lang.Class>	CLASS_XML Holds the default XML representation for java.lang.Class instances.
static XmlFormat<java.util.Collection>	COLLECTION_XML Holds the default XML representation for classes implementing the java.util.Collection interface.
static XmlFormat<java.lang.Object>	DEFAULT_XML Holds the default XML representation when a more specific format cannot be found.
static XmlFormat<java.lang.Double>	DOUBLE_XML Holds the default XML representation for java.lang.Double.
static XmlFormat<java.lang.Float>	FLOAT_XML Holds the default XML representation for java.lang.Float.
static XmlFormat<java.lang.Integer>	INTEGER_XML Holds the default XML representation for java.lang.Integer.
static XmlFormat<java.lang.Long>	LONG_XML Holds the default XML representation for java.lang.Long.
static XmlFormat<java.util.Map>	MAP_XML Holds the default XML representation for classes implementing the java.util.Map interface.
static XmlFormat<java.lang.Short>	SHORT_XML Holds the default XML representation for java.lang.Short.
static XmlFormat<java.lang.String>	STRING_XML Holds the default XML representation for java.lang.String classes.
static XmlFormat<Text>	TEXT_XML Holds the default XML representation for javolution.lang.Text classes.

Constructor Summary

protected	XmlFormat() Creates a dynamic XML format which can be locally mapped to any class (see setFormat(java.lang.Class, javolution.xml.XmlFormat)).
protected	XmlFormat(java.lang.Class<T> rootClass) Creates a default XML format for instances of the specified class/interface.
protected	XmlFormat(java.lang.String className) Creates a default XML format for instances of the class/interface identified by the specified String.

Method Summary

T	allocate(XmlElement xml) Allocates a new object corresponding to this xml element.
java.lang.String	defaultName() Returns the name to be used when objects associated to this format are added with no name specified (default null the element name is the object class name).
abstract void	format(T obj, XmlElement xml) Formats an object into the specified XmlElement.
static <T> XmlFormat<T>	getInstance(java.lang.Class<T> forClass) Returns the format for the specified class/interface.
java.lang.String	identifier(boolean isReference) Returns the names of the identifiers attributes when cross-reference is enabled.
abstract T	parse(XmlElement xml) Parses the specified XmlElement to produce an object.
static void	setAlias(java.lang.Class forClass, java.lang.String alias) Sets the local alias to be used instead of the class name for the specified class (element tag name or "j:class" attribute).
static void	setFormat(java.lang.Class forClass, XmlFormat that) Specifies the format associated to the specified class (local association).

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_XML

public static final XmlFormat<java.lang.Object> DEFAULT_XML

Holds the default XML representation when a more specific format cannot be found. This representation consists of an empty XML element with no attribute. Objects are deserialized using the class public no-arg constructor (the class being identified by the element's name).

CLASS_XML

public 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

public static final XmlFormat<java.lang.String> STRING_XML

Holds the default XML representation for java.lang.String classes. This representation consists of a "value" attribute holding the string.

TEXT_XML

public static final XmlFormat<Text> TEXT_XML

Holds the default XML representation for javolution.lang.Text classes. This representation consists of a "value" attribute holding the characters.

APPENDABLE_XML

public static final XmlFormat<java.lang.Appendable> APPENDABLE_XML

Holds the default XML representation for java.lang.Appendable classes. This representation consists of a "value" attribute holding the characters.

COLLECTION_XML

public static final XmlFormat<java.util.Collection> COLLECTION_XML

Holds the default XML representation for classes implementing the java.util.Collection interface. 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

public static final XmlFormat<java.util.Map> MAP_XML

Holds the default XML representation for classes implementing the java.util.Map interface. This representation consists of key/value pair as nested XML elements. For example:

 <javolution.util.FastMap>
     <Key j:class="java.lang.String" value="ONE"/>
     <Value j:class="java.lang.Integer" value="1"/>
     <Key j:class="java.lang.String" value="TWO"/>
     <Value j:class="java.lang.Integer" value="2"/>
     <Key j:class="java.lang.String" value="THREE"/>
     <Value j: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.

BOOLEAN_XML

public static final XmlFormat<java.lang.Boolean> BOOLEAN_XML

Holds the default XML representation for java.lang.Boolean.

BYTE_XML

public static final XmlFormat<java.lang.Byte> BYTE_XML

Holds the default XML representation for java.lang.Byte.

CHARACTER_XML

public static final XmlFormat<java.lang.Character> CHARACTER_XML

Holds the default XML representation for java.lang.Character.

INTEGER_XML

public static final XmlFormat<java.lang.Integer> INTEGER_XML

Holds the default XML representation for java.lang.Integer.

LONG_XML

public static final XmlFormat<java.lang.Long> LONG_XML

Holds the default XML representation for java.lang.Long.

SHORT_XML

public static final XmlFormat<java.lang.Short> SHORT_XML

Holds the default XML representation for java.lang.Short.

FLOAT_XML

public static final XmlFormat<java.lang.Float> FLOAT_XML

Holds the default XML representation for java.lang.Float. /

DOUBLE_XML

public static final XmlFormat<java.lang.Double> DOUBLE_XML

Holds the default XML representation for java.lang.Double. /

Constructor Detail

XmlFormat

protected XmlFormat()

Creates a dynamic XML format which can be locally mapped to any class (see setFormat(java.lang.Class, javolution.xml.XmlFormat)).

XmlFormat

protected XmlFormat(java.lang.Class<T> rootClass)

Creates a default XML format for instances of the specified class/interface.

Parameters:

rootClass - the root class/interface for this XML format.

Throws:

java.lang.IllegalStateException - if the specified class is already mapped to another format.

XmlFormat

protected XmlFormat(java.lang.String className)

Creates a default XML format for instances of the class/interface identified by the specified String.

Parameters:

className - the name of the target class/interface for this XML format.

Throws:

java.lang.IllegalStateException - if the specified class is already mapped to another format.

Method Detail

setFormat

public static void setFormat(java.lang.Class forClass,
                             XmlFormat that)

Specifies the format associated to the specified class (local association).

Parameters:

forClass - the class/interface being locally mapped.

that - the format to be associated to the specified class.

getInstance

public static <T> XmlFormat<T> getInstance(java.lang.Class<T> forClass)

Returns the format for the specified class/interface. This method searches for the more specialized format (default or dynamic); if none is found DEFAULT_XML format is returned.

Note: This method forces the initialization of the specified class. This to ensure that the class static fields (which may hold the most specialized format) are initialized.

Parameters:

forClass - the class/interface for which the most specialized format is returned.

Returns:

the format to use for the specified class.

setAlias

public static void setAlias(java.lang.Class forClass,
                            java.lang.String alias)

Sets the local alias to be used instead of the class name for the specified class (element tag name or "j:class" attribute). This method is particularly useful in case of obfuscation to ensure proper/invariant xml formatting (you don't want to use the obfuscated class name in such case).

Parameters:

forClass - the class for which the specified alias should be used.

alias - the name to use for the specified class.

See Also:

LocalMap

defaultName

public java.lang.String defaultName()

Returns the name to be used when objects associated to this format are added with no name specified (default null the element name is the object class name).

Returns:

the default element name for objects using this format.

identifier

public java.lang.String identifier(boolean isReference)

Returns the names of the identifiers attributes when cross-reference is enabled. The default implementation returns isReference ? "j:ref" : "j:id". Format sub-classes may override this method to use different attribute names. This method may also return null for objects exclusively manipulated by value (e.g. immutable objects).

Parameters:

isReference - indicates if the attribute name returned is for a reference or an identifier.

Returns:

the name of the attribute identifier or null if references should not be used.

See Also:

ObjectWriter.setReferencesEnabled(boolean)

allocate

public T allocate(XmlElement xml)

Allocates a new object corresponding to this xml element. By default, the XmlElement.object() method returns an object created using the deserialized class public no-arg constructor. Xml formats may perform custom allocations by overriding this method.

Parameters:

xml - the xml elements.

Returns:

the object corresponding to the specified xml element.

format

public abstract void format(T obj,
                            XmlElement xml)

Formats an object into the specified XmlElement.

Parameters:

obj - the object to format.

xml - the XmlElement destination.

parse

public abstract T parse(XmlElement xml)

Parses the specified XmlElement to produce an object.

Parameters:

xml - the XmlElement to parse.

Returns:

an Object parsed from the specified XmlElement.

Throws:

java.lang.IllegalArgumentException - if the character sequence contains an illegal syntax.