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.

Version:

$Revision: 13476 $

Author:

FracPete (fracpete at waikato dot ac dot nz)

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
static java.lang.String	DOCTYPE the DOCTYPE for the serialization
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
void	clear() generates internally a new XML document and clears also the IgnoreList and the mappings for the Read/Write-Methods
java.lang.Object	fromXML(org.w3c.dom.Document document) returns the given DOM document as an instance of the specified class
java.lang.String	getRevision() Returns the revision string.
java.lang.String	getVersion() returns the WEKA version with which the serialized object was created
static void	main(java.lang.String[] args) for testing only.
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.
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
XMLDocument	toXML(java.lang.Object o) extracts all accesible properties from the given object
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
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

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

Field Detail

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

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

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

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

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

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

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

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