weka.core.xml

Class XMLSerialization

java.lang.Object

weka.core.xml.XMLSerialization

All Implemented Interfaces:

RevisionHandler

Direct Known Subclasses:

XMLBasicSerialization

public class XMLSerialization
extends java.lang.Object
implements RevisionHandler

With this class objects can be serialized to XML instead into a binary format. It uses introspection (cf. beans) to retrieve the data from the given object, i.e. it can only access beans-conform fields automatically.

The generic approach of writing data as XML can be overriden by adding custom methods for reading/writing in a derived class (cf. m_Properties, m_CustomMethods).
Custom read and write methods must have the same signature (and also be public!) as the readFromXML and writeToXML methods. Methods that apply to the naming rule read + property name are added automatically to the list of methods by the method XMLSerializationMethodHandler.addMethods(...).

Other properties that are not conform the bean set/get-methods have to be processed manually in a derived class (cf. readPostProcess(Object), writePostProcess(Object)).

For a complete XML serialization/deserialization have a look at the KOML class.

If a stored class has a constructor that takes a String to initialize (e.g. String or Double) then the content of the tag will used for the constructor, e.g. from

 <object name="name" class="String" primitive="no">Smith</object>
 

"Smith" will be used to instantiate a String object as constructor argument.

See Also:

KOML, fromXML(Document), toXML(Object), m_Properties, m_CustomMethods, readPostProcess(Object), writePostProcess(Object), readFromXML(Element), writeToXML(Element, Object, String)

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	ATT_ARRAY the tag whether array or not (yes/no)
static java.lang.String	ATT_ARRAY_DEFAULT default value for attribute ATT_ARRAY
static java.lang.String	ATT_CLASS the tag for the class
static java.lang.String	ATT_NAME the tag for the name
static java.lang.String	ATT_NULL the tag whether null or not (yes/no)
static java.lang.String	ATT_NULL_DEFAULT default value for attribute ATT_NULL
static java.lang.String	ATT_PRIMITIVE the tag whether primitive or not (yes/no)
static java.lang.String	ATT_PRIMITIVE_DEFAULT default value for attribute ATT_PRIMITIVE
static java.lang.String	ATT_VERSION the version attribute
protected static boolean	DEBUG for debugging purposes only
static java.lang.String	DOCTYPE the DOCTYPE for the serialization
protected java.util.Hashtable<java.lang.Class<?>,java.lang.String>	m_ClassnameOverride for overriding class names (Class <-> Classname (String))
protected org.w3c.dom.Element	m_CurrentNode the node that is currently processed, in case of writing the parent node (something might go wrong writing the new child) and in case of reading the actual node that is tried to process
protected XMLSerializationMethodHandler	m_CustomMethods for handling custom read/write methods
protected XMLDocument	m_Document the XMLDocument that performs the transformation to and fro XML
protected PropertyHandler	m_Properties for handling properties (ignored/allowed)
protected boolean	m_suppressWarnings true to suppress warnings about loading newer/older versions etc.
static java.lang.String	ROOT_NODE the root node of the XML document
static java.util.List<java.lang.String>	SUPPRESS_PROPERTY_WARNINGS List of fully qualified property names to suppress any warning messages for
static java.lang.String	TAG_OBJECT the tag for an object
static java.lang.String	VAL_NO the value "no" for the primitive and array attribute
static java.lang.String	VAL_ROOT the value of the name for the root node
static java.lang.String	VAL_YES the value "yes" for the primitive and array attribute

Constructor Summary

Constructors

Constructor and Description
XMLSerialization() initializes the serialization

Method Summary

Modifier and Type	Method and Description
protected org.w3c.dom.Element	addElement(org.w3c.dom.Element parent, java.lang.String name, java.lang.String classname, boolean primitive) appends a new node to the parent with the given parameters (a non-array)
protected org.w3c.dom.Element	addElement(org.w3c.dom.Element parent, java.lang.String name, java.lang.String classname, boolean primitive, int array) appends a new node to the parent with the given parameters
protected org.w3c.dom.Element	addElement(org.w3c.dom.Element parent, java.lang.String name, java.lang.String classname, boolean primitive, int array, boolean isnull) appends a new node to the parent with the given parameters
protected java.lang.String	booleanToString(boolean b) returns either VAL_YES or VAL_NO depending on the value of b
void	clear() generates internally a new XML document and clears also the IgnoreList and the mappings for the Read/Write-Methods
protected java.lang.Class<?>	determineClass(java.lang.String name) returns the associated class for the given name
protected java.beans.PropertyDescriptor	determineDescriptor(java.lang.String className, java.lang.String displayName) returns a property descriptor if possible, otherwise null
java.lang.Object	fromXML(org.w3c.dom.Document document) returns the given DOM document as an instance of the specified class
protected int[]	getArrayDimensions(org.w3c.dom.Element node) returns an array with the dimensions of the array stored in XML
protected java.beans.PropertyDescriptor	getDescriptorByName(java.lang.Object o, java.lang.String name) returns a descriptor for a given objet by providing the name
protected java.util.Hashtable<java.lang.String,java.beans.PropertyDescriptor>	getDescriptors(java.lang.Object o) returns a hashtable with PropertyDescriptors that have "get" and "set" methods indexed by the property name.
protected java.lang.String	getPath(org.w3c.dom.Element node) returns the path of the "name" attribute from the root down to this node (including it).
protected java.lang.Object	getPrimitive(org.w3c.dom.Element node) returns an Object representing the primitive described by the given node.
java.lang.String	getRevision() Returns the revision string.
java.lang.String	getVersion() returns the WEKA version with which the serialized object was created
protected java.lang.Object	invokeReadFromXML(org.w3c.dom.Element node) either invokes a custom method to read a specific property/class or the standard method readFromXML(Element)
protected org.w3c.dom.Element	invokeWriteToXML(org.w3c.dom.Element parent, java.lang.Object o, java.lang.String name) either invokes a custom method to write a specific property/class or the standard method writeToXML(Element,Object,String)
protected boolean	isPrimitiveArray(java.lang.Class<?> c) checks whether the innermost class is a primitive class (handles multi-dimensional arrays)
static void	main(java.lang.String[] args) for testing only. if the first argument is a filename with ".xml" as extension it tries to generate an instance from the XML description and does a toString() of the generated object.
protected java.lang.String	overrideClassname(java.lang.Object o) if the class of the given object (or one of its ancestors) is stored in the classname override hashtable, then the override name is returned otherwise the classname of the given object.
protected java.lang.String	overrideClassname(java.lang.String classname) if the given classname is stored in the classname override hashtable, then the override name is returned otherwise the given classname.
java.lang.Object	read(java.io.File file) parses the given file and returns a DOM document
java.lang.Object	read(java.io.InputStream stream) parses the given stream and returns a DOM document
java.lang.Object	read(java.io.Reader reader) parses the given reader and returns a DOM document
java.lang.Object	read(java.lang.String xml) parses the given XML string (can be XML or a filename) and returns an Object generated from the representation
boolean	readBooleanFromXML(org.w3c.dom.Element node) builds the primitive from the given DOM node.
byte	readByteFromXML(org.w3c.dom.Element node) builds the primitive from the given DOM node.
char	readCharFromXML(org.w3c.dom.Element node) builds the primitive from the given DOM node.
double	readDoubleFromXML(org.w3c.dom.Element node) builds the primitive from the given DOM node.
float	readFloatFromXML(org.w3c.dom.Element node) builds the primitive from the given DOM node.
java.lang.Object	readFromXML(org.w3c.dom.Element node) builds the object from the given DOM node.
java.lang.Object	readFromXML(java.lang.Object o, java.lang.String name, org.w3c.dom.Element child) adds the specific node to the object via a set method
int	readIntFromXML(org.w3c.dom.Element node) builds the primitive from the given DOM node.
long	readLongFromXML(org.w3c.dom.Element node) builds the primitive from the given DOM node.
protected java.lang.Object	readPostProcess(java.lang.Object o) additional post-processing can happen in derived classes after reading from XML. right now it only returns the object as it is.
protected org.w3c.dom.Document	readPreProcess(org.w3c.dom.Document document) additional pre-processing can happen in derived classes before the actual reading from XML (working on the raw XML). right now it does nothing with the document.
short	readShortFromXML(org.w3c.dom.Element node) builds the primitive from the given DOM node.
void	setSuppressWarnings(boolean suppress) Set whether to suppress warning messages or not
protected boolean	stringToBoolean(java.lang.String s) turns the given string into a boolean, if a positive number is given, then zero is considered FALSE, every other number TRUE; the empty string is also considered being FALSE
XMLDocument	toXML(java.lang.Object o) extracts all accesible properties from the given object
protected void	trace(java.lang.Throwable t, java.lang.String msg) used for debugging purposes, i.e. only if DEBUG is set to true. needs a newly generated Throwable instance to get the method/line from
void	write(java.io.File file, java.lang.Object o) writes the given object into the file
void	write(java.io.OutputStream stream, java.lang.Object o) writes the given object into the stream
void	write(java.lang.String file, java.lang.Object o) writes the given object into the file
void	write(java.io.Writer writer, java.lang.Object o) writes the given object into the writer
protected org.w3c.dom.Element	writeBooleanToXML(org.w3c.dom.Element parent, boolean o, java.lang.String name) adds the given primitive to the DOM structure.
protected org.w3c.dom.Element	writeByteToXML(org.w3c.dom.Element parent, byte o, java.lang.String name) adds the given primitive to the DOM structure.
protected org.w3c.dom.Element	writeCharToXML(org.w3c.dom.Element parent, char o, java.lang.String name) adds the given primitive to the DOM structure.
protected org.w3c.dom.Element	writeDoubleToXML(org.w3c.dom.Element parent, double o, java.lang.String name) adds the given primitive to the DOM structure.
protected org.w3c.dom.Element	writeFloatToXML(org.w3c.dom.Element parent, float o, java.lang.String name) adds the given primitive to the DOM structure.
protected org.w3c.dom.Element	writeIntToXML(org.w3c.dom.Element parent, int o, java.lang.String name) adds the given primitive to the DOM structure.
protected org.w3c.dom.Element	writeLongToXML(org.w3c.dom.Element parent, long o, java.lang.String name) adds the given primitive to the DOM structure.
protected void	writePostProcess(java.lang.Object o) enables derived classes to add other properties to the DOM tree, e.g. ones that do not apply to the get/set convention of beans. only implemented with empty method body.
protected java.lang.Object	writePreProcess(java.lang.Object o) enables derived classes to due some pre-processing on the objects, that's about to be serialized.
protected org.w3c.dom.Element	writeShortToXML(org.w3c.dom.Element parent, short o, java.lang.String name) adds the given primitive to the DOM structure.
org.w3c.dom.Element	writeToXML(org.w3c.dom.Element parent, java.lang.Object o, java.lang.String name) adds the given Object to a DOM structure.

Methods inherited from class java.lang.Object

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

Field Detail

DEBUG

protected static boolean DEBUG

for debugging purposes only

m_CurrentNode

protected org.w3c.dom.Element m_CurrentNode

the node that is currently processed, in case of writing the parent node (something might go wrong writing the new child) and in case of reading the actual node that is tried to process

TAG_OBJECT

public static final java.lang.String TAG_OBJECT

the tag for an object

See Also:

Constant Field Values

ATT_VERSION

public static final java.lang.String ATT_VERSION

the version attribute

See Also:

Constant Field Values

ATT_NAME

public static final java.lang.String ATT_NAME

the tag for the name

See Also:

Constant Field Values

ATT_CLASS

public static final java.lang.String ATT_CLASS

the tag for the class

See Also:

Constant Field Values

ATT_PRIMITIVE

public static final java.lang.String ATT_PRIMITIVE

the tag whether primitive or not (yes/no)

See Also:

Constant Field Values

ATT_ARRAY

public static final java.lang.String ATT_ARRAY

the tag whether array or not (yes/no)

See Also:

Constant Field Values

ATT_NULL

public static final java.lang.String ATT_NULL

the tag whether null or not (yes/no)

See Also:

Constant Field Values

VAL_YES

public static final java.lang.String VAL_YES

the value "yes" for the primitive and array attribute

See Also:

Constant Field Values

VAL_NO

public static final java.lang.String VAL_NO

the value "no" for the primitive and array attribute

See Also:

Constant Field Values

VAL_ROOT

public static final java.lang.String VAL_ROOT

the value of the name for the root node

See Also:

Constant Field Values

ROOT_NODE

public static final java.lang.String ROOT_NODE

the root node of the XML document

See Also:

Constant Field Values

ATT_PRIMITIVE_DEFAULT

public static final java.lang.String ATT_PRIMITIVE_DEFAULT

default value for attribute ATT_PRIMITIVE

See Also:

ATT_PRIMITIVE, Constant Field Values

ATT_ARRAY_DEFAULT

public static final java.lang.String ATT_ARRAY_DEFAULT

default value for attribute ATT_ARRAY

See Also:

ATT_ARRAY, Constant Field Values

ATT_NULL_DEFAULT

public static final java.lang.String ATT_NULL_DEFAULT

default value for attribute ATT_NULL

See Also:

ATT_NULL, Constant Field Values

DOCTYPE

public static final java.lang.String DOCTYPE

the DOCTYPE for the serialization

SUPPRESS_PROPERTY_WARNINGS

public static final java.util.List<java.lang.String> SUPPRESS_PROPERTY_WARNINGS

List of fully qualified property names to suppress any warning messages for

m_Document

protected XMLDocument m_Document

the XMLDocument that performs the transformation to and fro XML

m_Properties

protected PropertyHandler m_Properties

for handling properties (ignored/allowed)

m_CustomMethods

protected XMLSerializationMethodHandler m_CustomMethods

for handling custom read/write methods

m_ClassnameOverride

protected java.util.Hashtable<java.lang.Class<?>,java.lang.String> m_ClassnameOverride

for overriding class names (Class <-> Classname (String))

See Also:

overrideClassname(Object)

m_suppressWarnings

protected boolean m_suppressWarnings

true to suppress warnings about loading newer/older versions etc.

Constructor Detail

XMLSerialization

public XMLSerialization()
                 throws java.lang.Exception

initializes the serialization

Throws:

java.lang.Exception - if initialization fails

Method Detail

setSuppressWarnings

public void setSuppressWarnings(boolean suppress)

Set whether to suppress warning messages or not

Parameters:

suppress - true to suppress warnings

trace

protected void trace(java.lang.Throwable t,
                     java.lang.String msg)

used for debugging purposes, i.e. only if DEBUG is set to true. needs a newly generated Throwable instance to get the method/line from

Parameters:

t - a throwable instance, generated in the calling method

msg - a message to pring

See Also:

DEBUG

clear

public void clear()
           throws java.lang.Exception

generates internally a new XML document and clears also the IgnoreList and the mappings for the Read/Write-Methods

Throws:

java.lang.Exception - if something goes wrong

getVersion

public java.lang.String getVersion()

returns the WEKA version with which the serialized object was created

Returns:

the current version

See Also:

Version

getDescriptors

protected java.util.Hashtable<java.lang.String,java.beans.PropertyDescriptor> getDescriptors(java.lang.Object o)
                                                                                      throws java.lang.Exception

returns a hashtable with PropertyDescriptors that have "get" and "set" methods indexed by the property name.

Parameters:

o - the object to retrieve the descriptors from

Returns:

the PropertyDescriptors indexed by name of the property

Throws:

java.lang.Exception - if the introspection fails

See Also:

PropertyDescriptor

getPath

protected java.lang.String getPath(org.w3c.dom.Element node)

returns the path of the "name" attribute from the root down to this node (including it).

Parameters:

node - the node to get the path for

Returns:

the complete "name" path of this node

booleanToString

protected java.lang.String booleanToString(boolean b)

returns either VAL_YES or VAL_NO depending on the value of b

Parameters:

b - the boolean to turn into a string

Returns:

the value in string representation

stringToBoolean

protected boolean stringToBoolean(java.lang.String s)

turns the given string into a boolean, if a positive number is given, then zero is considered FALSE, every other number TRUE; the empty string is also considered being FALSE

Parameters:

s - the string to turn into a boolean

Returns:

the string as boolean

addElement

protected org.w3c.dom.Element addElement(org.w3c.dom.Element parent,
                                         java.lang.String name,
                                         java.lang.String classname,
                                         boolean primitive)

appends a new node to the parent with the given parameters (a non-array)

Parameters:

parent - the parent of this node. if it is null the document root element is used

name - the name of the node

classname - the classname for this node

primitive - whether it is a primitve data type or not (i.e. an object)

Returns:

the generated node

addElement

protected org.w3c.dom.Element addElement(org.w3c.dom.Element parent,
                                         java.lang.String name,
                                         java.lang.String classname,
                                         boolean primitive,
                                         int array)

appends a new node to the parent with the given parameters

Parameters:

parent - the parent of this node. if it is null the document root element is used

name - the name of the node

classname - the classname for this node

primitive - whether it is a primitve data type or not (i.e. an object)

array - the dimensions of the array (0 if not an array)

Returns:

the generated node

addElement

protected org.w3c.dom.Element addElement(org.w3c.dom.Element parent,
                                         java.lang.String name,
                                         java.lang.String classname,
                                         boolean primitive,
                                         int array,
                                         boolean isnull)

appends a new node to the parent with the given parameters

Parameters:

parent - the parent of this node. if it is null the document root element is used

name - the name of the node

classname - the classname for this node

primitive - whether it is a primitve data type or not (i.e. an object)

array - the dimensions of the array (0 if not an array)

isnull - whether it is null

Returns:

the generated node

overrideClassname

protected java.lang.String overrideClassname(java.lang.Object o)

if the class of the given object (or one of its ancestors) is stored in the classname override hashtable, then the override name is returned otherwise the classname of the given object.

Parameters:

o - the object to check for overriding its classname

Returns:

if overridden then the classname stored in the hashtable, otherwise the classname of the given object

See Also:

m_ClassnameOverride

overrideClassname

protected java.lang.String overrideClassname(java.lang.String classname)

if the given classname is stored in the classname override hashtable, then the override name is returned otherwise the given classname. Note: in contrast to overrideClassname(Object) does this method only look for exact name matches. The other method checks whether the class of the given object is a subclass of any of the stored overrides.

Parameters:

classname - the classname to check for overriding

Returns:

if overridden then the classname stored in the hashtable, otherwise the given classname

See Also:

m_ClassnameOverride, overrideClassname(Object)

determineDescriptor

protected java.beans.PropertyDescriptor determineDescriptor(java.lang.String className,
                                                            java.lang.String displayName)

returns a property descriptor if possible, otherwise null

Parameters:

className - the name of the class to get the descriptor for

displayName - the name of the property

Returns:

the descriptor if available, otherwise null

writeBooleanToXML

protected org.w3c.dom.Element writeBooleanToXML(org.w3c.dom.Element parent,
                                                boolean o,
                                                java.lang.String name)
                                         throws java.lang.Exception

adds the given primitive to the DOM structure.

Parameters:

parent - the parent of this object, e.g. the class this object is a member of

o - the primitive to describe in XML

name - the name of the primitive

Returns:

the node that was created

Throws:

java.lang.Exception - if the DOM creation fails

writeByteToXML

protected org.w3c.dom.Element writeByteToXML(org.w3c.dom.Element parent,
                                             byte o,
                                             java.lang.String name)
                                      throws java.lang.Exception

adds the given primitive to the DOM structure.

Parameters:

parent - the parent of this object, e.g. the class this object is a member of

o - the primitive to describe in XML

name - the name of the primitive

Returns:

the node that was created

Throws:

java.lang.Exception - if the DOM creation fails

writeCharToXML

protected org.w3c.dom.Element writeCharToXML(org.w3c.dom.Element parent,
                                             char o,
                                             java.lang.String name)
                                      throws java.lang.Exception

adds the given primitive to the DOM structure.

Parameters:

parent - the parent of this object, e.g. the class this object is a member of

o - the primitive to describe in XML

name - the name of the primitive

Returns:

the node that was created

Throws:

java.lang.Exception - if the DOM creation fails

writeDoubleToXML

protected org.w3c.dom.Element writeDoubleToXML(org.w3c.dom.Element parent,
                                               double o,
                                               java.lang.String name)
                                        throws java.lang.Exception

adds the given primitive to the DOM structure.

Parameters:

parent - the parent of this object, e.g. the class this object is a member of

o - the primitive to describe in XML

name - the name of the primitive

Returns:

the node that was created

Throws:

java.lang.Exception - if the DOM creation fails

writeFloatToXML

protected org.w3c.dom.Element writeFloatToXML(org.w3c.dom.Element parent,
                                              float o,
                                              java.lang.String name)
                                       throws java.lang.Exception

adds the given primitive to the DOM structure.

Parameters:

parent - the parent of this object, e.g. the class this object is a member of

o - the primitive to describe in XML

name - the name of the primitive

Returns:

the node that was created

Throws:

java.lang.Exception - if the DOM creation fails

writeIntToXML

protected org.w3c.dom.Element writeIntToXML(org.w3c.dom.Element parent,
                                            int o,
                                            java.lang.String name)
                                     throws java.lang.Exception

adds the given primitive to the DOM structure.

Parameters:

parent - the parent of this object, e.g. the class this object is a member of

o - the primitive to describe in XML

name - the name of the primitive

Returns:

the node that was created

Throws:

java.lang.Exception - if the DOM creation fails

writeLongToXML

protected org.w3c.dom.Element writeLongToXML(org.w3c.dom.Element parent,
                                             long o,
                                             java.lang.String name)
                                      throws java.lang.Exception

adds the given primitive to the DOM structure.

Parameters:

parent - the parent of this object, e.g. the class this object is a member of

o - the primitive to describe in XML

name - the name of the primitive

Returns:

the node that was created

Throws:

java.lang.Exception - if the DOM creation fails

writeShortToXML

protected org.w3c.dom.Element writeShortToXML(org.w3c.dom.Element parent,
                                              short o,
                                              java.lang.String name)
                                       throws java.lang.Exception

adds the given primitive to the DOM structure.

Parameters:

parent - the parent of this object, e.g. the class this object is a member of

o - the primitive to describe in XML

name - the name of the primitive

Returns:

the node that was created

Throws:

java.lang.Exception - if the DOM creation fails

isPrimitiveArray

protected boolean isPrimitiveArray(java.lang.Class<?> c)

checks whether the innermost class is a primitive class (handles multi-dimensional arrays)

Parameters:

c - the array class to inspect

Returns:

whether the array consists of primitive elements

writeToXML

public org.w3c.dom.Element writeToXML(org.w3c.dom.Element parent,
                                      java.lang.Object o,
                                      java.lang.String name)
                               throws java.lang.Exception

adds the given Object to a DOM structure. (only public due to reflection).
Note: overrideClassname(Object) is not invoked in case of arrays, since the array class could be a superclass, whereas the elements of the array can be specialized subclasses. In case of an array the method overrideClassname(String) is invoked, which searches for an exact match of the classname in the override hashtable.

Parameters:

parent - the parent of this object, e.g. the class this object is a member of

o - the Object to describe in XML

name - the name of the object

Returns:

the node that was created

Throws:

java.lang.Exception - if the DOM creation fails

See Also:

overrideClassname(Object), overrideClassname(String), m_ClassnameOverride

invokeWriteToXML

protected org.w3c.dom.Element invokeWriteToXML(org.w3c.dom.Element parent,
                                               java.lang.Object o,
                                               java.lang.String name)
                                        throws java.lang.Exception

either invokes a custom method to write a specific property/class or the standard method writeToXML(Element,Object,String)

Parameters:

parent - the parent XML node

o - the object's content will be added as children to the given parent node

name - the name of the object

Returns:

the node that was created

Throws:

java.lang.Exception - if invocation or turning into XML fails

writePreProcess

protected java.lang.Object writePreProcess(java.lang.Object o)
                                    throws java.lang.Exception

enables derived classes to due some pre-processing on the objects, that's about to be serialized. Right now it only returns the object.

Parameters:

o - the object that is serialized into XML

Returns:

the possibly altered object

Throws:

java.lang.Exception - if post-processing fails

writePostProcess

protected void writePostProcess(java.lang.Object o)
                         throws java.lang.Exception

enables derived classes to add other properties to the DOM tree, e.g. ones that do not apply to the get/set convention of beans. only implemented with empty method body.

Parameters:

o - the object that is serialized into XML

Throws:

java.lang.Exception - if post-processing fails

toXML

public XMLDocument toXML(java.lang.Object o)
                  throws java.lang.Exception

extracts all accesible properties from the given object

Parameters:

o - the object to turn into an XML representation

Returns:

the generated DOM document

Throws:

java.lang.Exception - if XML generation fails

getDescriptorByName

protected java.beans.PropertyDescriptor getDescriptorByName(java.lang.Object o,
                                                            java.lang.String name)
                                                     throws java.lang.Exception

returns a descriptor for a given objet by providing the name

Parameters:

o - the object the get the descriptor for

name - the display name of the descriptor

Returns:

the Descriptor, if found, otherwise null

Throws:

java.lang.Exception - if introsepction fails

determineClass

protected java.lang.Class<?> determineClass(java.lang.String name)
                                     throws java.lang.Exception

returns the associated class for the given name

Parameters:

name - the name of the class to return a Class object for

Returns:

the class if it could be retrieved

Throws:

java.lang.Exception - if it class retrieval fails

getPrimitive

protected java.lang.Object getPrimitive(org.w3c.dom.Element node)
                                 throws java.lang.Exception

returns an Object representing the primitive described by the given node. Here we use a trick to return an object even though its a primitive: by creating a primitive array with reflection of length 1, setting the primtive value as real object and then returning the "object" at position 1 of the array.

Parameters:

node - the node to return the value as "primitive" object

Returns:

the primitive as "pseudo" object

Throws:

java.lang.Exception - if the instantiation of the array fails or any of the String conversions fails

readBooleanFromXML

public boolean readBooleanFromXML(org.w3c.dom.Element node)
                           throws java.lang.Exception

builds the primitive from the given DOM node.

Parameters:

node - the associated XML node

Returns:

the primitive created from the XML description

Throws:

java.lang.Exception - if instantiation fails

readByteFromXML

public byte readByteFromXML(org.w3c.dom.Element node)
                     throws java.lang.Exception

builds the primitive from the given DOM node.

Parameters:

node - the associated XML node

Returns:

the primitive created from the XML description

Throws:

java.lang.Exception - if instantiation fails

readCharFromXML

public char readCharFromXML(org.w3c.dom.Element node)
                     throws java.lang.Exception

builds the primitive from the given DOM node.

Parameters:

node - the associated XML node

Returns:

the primitive created from the XML description

Throws:

java.lang.Exception - if instantiation fails

readDoubleFromXML

public double readDoubleFromXML(org.w3c.dom.Element node)
                         throws java.lang.Exception

builds the primitive from the given DOM node.

Parameters:

node - the associated XML node

Returns:

the primitive created from the XML description

Throws:

java.lang.Exception - if instantiation fails

readFloatFromXML

public float readFloatFromXML(org.w3c.dom.Element node)
                       throws java.lang.Exception

builds the primitive from the given DOM node.

Parameters:

node - the associated XML node

Returns:

the primitive created from the XML description

Throws:

java.lang.Exception - if instantiation fails

readIntFromXML

public int readIntFromXML(org.w3c.dom.Element node)
                   throws java.lang.Exception

builds the primitive from the given DOM node.

Parameters:

node - the associated XML node

Returns:

the primitive created from the XML description

Throws:

java.lang.Exception - if instantiation fails

readLongFromXML

public long readLongFromXML(org.w3c.dom.Element node)
                     throws java.lang.Exception

builds the primitive from the given DOM node.

Parameters:

node - the associated XML node

Returns:

the primitive created from the XML description

Throws:

java.lang.Exception - if instantiation fails

readShortFromXML

public short readShortFromXML(org.w3c.dom.Element node)
                       throws java.lang.Exception

builds the primitive from the given DOM node.

Parameters:

node - the associated XML node

Returns:

the primitive created from the XML description

Throws:

java.lang.Exception - if instantiation fails

readFromXML

public java.lang.Object readFromXML(java.lang.Object o,
                                    java.lang.String name,
                                    org.w3c.dom.Element child)
                             throws java.lang.Exception

adds the specific node to the object via a set method

Parameters:

o - the object to set a property

name - the name of the object for which to set a property (only for information reasons)

child - the value of the property to add

Returns:

the provided object, but augmented by the child

Throws:

java.lang.Exception - if something goes wrong

getArrayDimensions

protected int[] getArrayDimensions(org.w3c.dom.Element node)

returns an array with the dimensions of the array stored in XML

Parameters:

node - the node to determine the dimensions for

Returns:

the dimensions of the array

readFromXML

public java.lang.Object readFromXML(org.w3c.dom.Element node)
                             throws java.lang.Exception

builds the object from the given DOM node. (only public due to reflection)

Parameters:

node - the associated XML node

Returns:

the instance created from the XML description

Throws:

java.lang.Exception - if instantiation fails

invokeReadFromXML

protected java.lang.Object invokeReadFromXML(org.w3c.dom.Element node)
                                      throws java.lang.Exception

either invokes a custom method to read a specific property/class or the standard method readFromXML(Element)

Parameters:

node - the associated XML node

Returns:

the instance created from the XML description

Throws:

java.lang.Exception - if instantiation fails

readPreProcess

protected org.w3c.dom.Document readPreProcess(org.w3c.dom.Document document)
                                       throws java.lang.Exception

additional pre-processing can happen in derived classes before the actual reading from XML (working on the raw XML). right now it does nothing with the document.

Parameters:

document - the document to pre-process

Returns:

the processed object

Throws:

java.lang.Exception - if post-processing fails

readPostProcess

protected java.lang.Object readPostProcess(java.lang.Object o)
                                    throws java.lang.Exception

additional post-processing can happen in derived classes after reading from XML. right now it only returns the object as it is.

Parameters:

o - the object to perform some additional processing on

Returns:

the processed object

Throws:

java.lang.Exception - if post-processing fails

fromXML

public java.lang.Object fromXML(org.w3c.dom.Document document)
                         throws java.lang.Exception

returns the given DOM document as an instance of the specified class

Parameters:

document - the parsed DOM document representing the object

Returns:

the XML as object

Throws:

java.lang.Exception - if object instantiation fails

read

public java.lang.Object read(java.lang.String xml)
                      throws java.lang.Exception

parses the given XML string (can be XML or a filename) and returns an Object generated from the representation

Parameters:

xml - the xml to parse (if "

Returns:

the generated instance

Throws:

java.lang.Exception - if something goes wrong with the parsing

read

public java.lang.Object read(java.io.File file)
                      throws java.lang.Exception

parses the given file and returns a DOM document

Parameters:

file - the XML file to parse

Returns:

the parsed DOM document

Throws:

java.lang.Exception - if something goes wrong with the parsing

read

public java.lang.Object read(java.io.InputStream stream)
                      throws java.lang.Exception

parses the given stream and returns a DOM document

Parameters:

stream - the XML stream to parse

Returns:

the parsed DOM document

Throws:

java.lang.Exception - if something goes wrong with the parsing

read

public java.lang.Object read(java.io.Reader reader)
                      throws java.lang.Exception

parses the given reader and returns a DOM document

Parameters:

reader - the XML reader to parse

Returns:

the parsed DOM document

Throws:

java.lang.Exception - if something goes wrong with the parsing

write

public void write(java.lang.String file,
                  java.lang.Object o)
           throws java.lang.Exception

writes the given object into the file

Parameters:

file - the filename to write to

o - the object to serialize as XML

Throws:

java.lang.Exception - if something goes wrong with the parsing

write

public void write(java.io.File file,
                  java.lang.Object o)
           throws java.lang.Exception

writes the given object into the file

Parameters:

file - the filename to write to

o - the object to serialize as XML

Throws:

java.lang.Exception - if something goes wrong with the parsing

write

public void write(java.io.OutputStream stream,
                  java.lang.Object o)
           throws java.lang.Exception

writes the given object into the stream

Parameters:

stream - the filename to write to

o - the object to serialize as XML

Throws:

java.lang.Exception - if something goes wrong with the parsing

write

public void write(java.io.Writer writer,
                  java.lang.Object o)
           throws java.lang.Exception

writes the given object into the writer

Parameters:

writer - the filename to write to

o - the object to serialize as XML

Throws:

java.lang.Exception - if something goes wrong with the parsing

main

public static void main(java.lang.String[] args)
                 throws java.lang.Exception

for testing only. if the first argument is a filename with ".xml" as extension it tries to generate an instance from the XML description and does a toString() of the generated object.

Throws:

java.lang.Exception

getRevision

public java.lang.String getRevision()

Returns the revision string.

Specified by:

getRevision in interface RevisionHandler

Returns:

the revision