J avolution v5.2 (J2SE 1.5+)

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 static XMLFormat class members. Formats are 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.
         private static final XMLFormat<Graphic> XML = 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 mapping between classes and XML formats is defined by 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);
     
     // Creates some aliases to use instead of class names.
     XMLBinding binding = new XMLBinding();
     binding.setAlias(FastMap.class, "Map");
     binding.setAlias(String.class, "String");
     binding.setAlias(Integer.class, "Integer");
     
     // 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.1, July 4, 2007
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).
 
Constructor Summary
protected XMLFormat()
          Deprecated. XMLFormat(null) should be used instead.
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.
 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.
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, toString, wait, wait, wait
 

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 ( dynamic format 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) { ... }; // Unmapped.
        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 mapped.
Throws:
java.lang.IllegalArgumentException - if the specified class is already bound to another format.

XMLFormat

protected XMLFormat()
Deprecated. XMLFormat(null) should be used instead.

Creates an unmapped XML format.

Method Detail

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

J avolution v5.2 (J2SE 1.5+)

Copyright © 2005 - 2007 Javolution.