|
J avolution v5.4 (J2SE 1.6+) | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectjavolution.xml.XMLFormat<T>
public abstract class XMLFormat<T>
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:
Here is the output
// 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();
list.xml
document produced:
The list can be read back with the following code:
<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>
// 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.
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
|
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 |
---|
protected static final XMLFormat<java.lang.Object> OBJECT_XML
Object.class
instances
(default format when a more specialized format does not exist).
The XML representation consists of an empty element with no attribute.
protected static final XMLFormat<java.lang.Class> CLASS_XML
java.lang.Class
instances. This representation consists of a "name"
attribute holding the class name.
protected static final XMLFormat<java.lang.String> STRING_XML
java.lang.String
instances. This representation consists of a "value"
attribute holding the string.
protected static final XMLFormat<java.lang.Appendable> APPENDABLE_XML
Appendable
instances. This representation consists of a "value"
attribute
holding the characters.
protected static final XMLFormat<java.util.Collection> COLLECTION_XML
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.
protected static final XMLFormat<java.util.Map> MAP_XML
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.
protected static final XMLFormat<java.lang.Object[]> OBJECT_ARRAY_XML
java.lang.Object[]
instances. This representation consists of nested XML elements one for
each element of the array.
/
protected static final XMLFormat<java.lang.Boolean> BOOLEAN_XML
java.lang.Boolean
.
This representation consists of a single "value"
attribute
holding the value.
protected static final XMLFormat<java.lang.Byte> BYTE_XML
java.lang.Byte
.
This representation consists of a single "value"
attribute
holding the value.
protected static final XMLFormat<java.lang.Character> CHARACTER_XML
java.lang.Character
.
This representation consists of a single "value"
attribute
holding the value.
protected static final XMLFormat<java.lang.Short> SHORT_XML
java.lang.Short
.
This representation consists of a single "value"
attribute
holding the value.
protected static final XMLFormat<java.lang.Integer> INTEGER_XML
java.lang.Integer
.
This representation consists of a single "value"
attribute
holding the value.
protected static final XMLFormat<java.lang.Long> LONG_XML
java.lang.Long
.
This representation consists of a single "value"
attribute
holding the value.
protected static final XMLFormat<java.lang.Float> FLOAT_XML
java.lang.Float
.
This representation consists of a single "value"
attribute
holding the value.
protected static final XMLFormat<java.lang.Double> DOUBLE_XML
java.lang.Double
.
This representation consists of a single "value"
attribute
holding the value.
protected static final XMLFormat<Text> TEXT_XML
"value"
attribute
holding the characters.
protected static final XMLFormat<FastMap> FAST_MAP_XML
MAP_XML
except that it may include the key/value comparators for the map
(if different from FastComparator.DEFAULT
) and the
"shared"
attribute.
protected static final XMLFormat<FastCollection> FAST_COLLECTION_XML
COLLECTION_XML
.
protected static final XMLFormat<FastComparator> FAST_COMPARATOR_XML
protected static final XMLFormat<Index> INDEX_XML
"value"
attribute
holding the index int
value.
protected static final XMLFormat<PersistentContext> PERSISTENT_CONTEXT_XML
protected static final XMLFormat<Configurable> CONFIGURABLE_XML
<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.
protected static final XMLFormat<QName> QNAME_XML
"namespaceURI"
attribute
and alocalName
attribute.
Constructor Detail |
---|
protected XMLFormat(java.lang.Class<T> cls)
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);
}
}
}
cls
- the root class/interface to associate to this XML format
or null
if this format is not bound.
java.lang.IllegalArgumentException
- if the specified class is already
bound to another format.Method Detail |
---|
public static <T> XMLFormat<T> getDefault(java.lang.Class<? extends T> forClass)
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
.
public final java.lang.Class<T> getBoundClass()
null
if none.
public boolean isReferenceable()
true
). This method can be overriden to return
false
if serialized objects are manipulated "by value".
true
if serialized object may hold a reference;
false
otherwise.XMLReferenceResolver
public T newInstance(java.lang.Class<T> cls, XMLFormat.InputElement xml) throws XMLStreamException
cls
- the class of the object to return.xml
- the XML input element.
XMLStreamException
public abstract void write(T obj, XMLFormat.OutputElement xml) throws XMLStreamException
obj
- the object to format.xml
- the XMLElement
destination.
XMLStreamException
public abstract void read(XMLFormat.InputElement xml, T obj) throws XMLStreamException
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.
XMLStreamException
public java.lang.String toString()
toString
in class java.lang.Object
|
J avolution v5.4 (J2SE 1.6+) | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |