weka.core.xml
Class XMLSerialization

java.lang.Object
  extended byweka.core.xml.XMLSerialization
Direct Known Subclasses:
XMLBasicSerialization

public class XMLSerialization
extends java.lang.Object

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: 1.1.2.5 $
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), #addMethods()

Field Summary
static java.lang.String ATT_ARRAY
          the tag whether array or not (yes/no)
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_PRIMITIVE
          the tag whether primitive or not (yes/no)
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.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
XMLSerialization()
          initializes the serialization
 
Method Summary
 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 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
 java.lang.Object readFromXML(org.w3c.dom.Element node)
          builds the object from the given DOM node.
 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
 void 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

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

DOCTYPE

public static final java.lang.String DOCTYPE
the DOCTYPE for the serialization

See Also:
Constant Field Values
Constructor Detail

XMLSerialization

public XMLSerialization()
                 throws java.lang.Exception
initializes the serialization

Throws:
java.lang.Exception - if initialization fails
Method Detail

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

getVersion

public java.lang.String getVersion()
returns the WEKA version with which the serialized object was created

See Also:
Version

writeToXML

public void 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
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

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:
if - object instantiation fails
java.lang.Exception

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:
if - something goes wrong with the parsing
java.lang.Exception

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:
if - something goes wrong with the parsing
java.lang.Exception

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:
if - something goes wrong with the parsing
java.lang.Exception

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:
if - something goes wrong with the parsing
java.lang.Exception

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:
if - something goes wrong with the parsing
java.lang.Exception

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:
if - something goes wrong with the parsing
java.lang.Exception

write

public void write(java.io.OutputStream stream,
                  java.lang.Object o)
           throws java.lang.Exception
writes the given object into the stream

Parameters:
o - the object to serialize as XML
Throws:
if - something goes wrong with the parsing
java.lang.Exception

write

public void write(java.io.Writer writer,
                  java.lang.Object o)
           throws java.lang.Exception
writes the given object into the writer

Parameters:
o - the object to serialize as XML
Throws:
if - something goes wrong with the parsing
java.lang.Exception

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