Overview | Package | Class | Tree | Deprecated | Index | Help
| J avolution v5.2 (J2SE 1.5+)
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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 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`

Overview | Package | Class | Tree | Deprecated | Index | Help
| J avolution v5.2 (J2SE 1.5+)
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2005 - 2007 Javolution.