Package weka.core.xml

# Class XMLSerialization

java.lang.Object
weka.core.xml.XMLSerialization

All Implemented Interfaces:
  `RevisionHandler`

Direct Known Subclasses:
  `XMLBasicSerialization`

public class XMLSerialization extends 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: 1.16 $
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
Description
`static final String`
`ATT_ARRAY`
the tag whether array or not (yes/no)
`static final String`
`ATT_ARRAY_DEFAULT`
default value for attribute ATT_ARRAY
`static final String`
`ATT_CLASS`
the tag for the class
`static final String`
`ATT_NAME`
the tag for the name
`static final String`
`ATT_NULL`
the tag whether null or not (yes/no)
`static final String`
`ATT_NULL_DEFAULT`
default value for attribute ATT_NULL
`static final String`
`ATT_PRIMITIVE`
the tag whether primitive or not (yes/no)
`static final String`
`ATT_PRIMITIVE_DEFAULT`
default value for attribute ATT_PRIMITIVE
`static final String`
`ATT_VERSION`
the version attribute
`static final String`
`DOCTYPE`
the DOCTYPE for the serialization
`static final String`
`ROOT_NODE`
the root node of the XML document
`static final String`
`TAG_OBJECT`
the tag for an object
`static final String`
`VAL_NO`
the value "no" for the primitive and array attribute
`static final String`
`VAL_ROOT`
the value of the name for the root node
`static final String`
`VAL_YES`
the value "yes" for the primitive and array attribute

## Constructor Summary

Constructors
Constructor
Description
`XMLSerialization()`
initializes the serialization

## Method Summary

Modifier and Type
Method
Description
`void`
`clear()`
generates internally a new XML document and clears also the IgnoreList and the mappings for the Read/Write-Methods
`Object`
`fromXML(Document document)`
returns the given DOM document as an instance of the specified class
`String`
`getRevision()`
Returns the revision string.
`String`
`getVersion()`
returns the WEKA version with which the serialized object was created
`static void`
`main(String[] args)`
for testing only.
`Object`
`read(File file)`
parses the given file and returns a DOM document
`Object`
`read(InputStream stream)`
parses the given stream and returns a DOM document
`Object`
`read(Reader reader)`
parses the given reader and returns a DOM document
`Object`
`read(String xml)`
parses the given XML string (can be XML or a filename) and returns an Object generated from the representation
`boolean`
`readBooleanFromXML(Element node)`
builds the primitive from the given DOM node.
`byte`
`readByteFromXML(Element node)`
builds the primitive from the given DOM node.
`char`
`readCharFromXML(Element node)`
builds the primitive from the given DOM node.
`double`
`readDoubleFromXML(Element node)`
builds the primitive from the given DOM node.
`float`
`readFloatFromXML(Element node)`
builds the primitive from the given DOM node.
`Object`
`readFromXML(Object o, String name, Element child)`
adds the specific node to the object via a set method
`Object`
`readFromXML(Element node)`
builds the object from the given DOM node.
`int`
`readIntFromXML(Element node)`
builds the primitive from the given DOM node.
`long`
`readLongFromXML(Element node)`
builds the primitive from the given DOM node.
`short`
`readShortFromXML(Element node)`
builds the primitive from the given DOM node.
`XMLDocument`
`toXML(Object o)`
extracts all accesible properties from the given object
`void`
`write(File file, Object o)`
writes the given object into the file
`void`
`write(OutputStream stream, Object o)`
writes the given object into the stream
`void`
`write(Writer writer, Object o)`
writes the given object into the writer
`void`
`write(String file, Object o)`
writes the given object into the file
`Element`
`writeToXML(Element parent, Object o, 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 Details

### TAG_OBJECT

public static final String TAG_OBJECT
the tag for an object

See Also:
  - Constant Field Values

### ATT_VERSION

public static final String ATT_VERSION
the version attribute

See Also:
  - Constant Field Values

### ATT_NAME

public static final String ATT_NAME
the tag for the name

See Also:
  - Constant Field Values

### ATT_CLASS

public static final String ATT_CLASS
the tag for the class

See Also:
  - Constant Field Values

### ATT_PRIMITIVE

public static final String ATT_PRIMITIVE
the tag whether primitive or not (yes/no)

See Also:
  - Constant Field Values

### ATT_ARRAY

public static final String ATT_ARRAY
the tag whether array or not (yes/no)

See Also:
  - Constant Field Values

### ATT_NULL

public static final String ATT_NULL
the tag whether null or not (yes/no)

See Also:
  - Constant Field Values

### VAL_YES

public static final String VAL_YES
the value "yes" for the primitive and array attribute

See Also:
  - Constant Field Values

### VAL_NO

public static final String VAL_NO
the value "no" for the primitive and array attribute

See Also:
  - Constant Field Values

### VAL_ROOT

public static final String VAL_ROOT
the value of the name for the root node

See Also:
  - Constant Field Values

### ROOT_NODE

public static final String ROOT_NODE
the root node of the XML document

See Also:
  - Constant Field Values

### ATT_PRIMITIVE_DEFAULT

public static final String ATT_PRIMITIVE_DEFAULT
default value for attribute ATT_PRIMITIVE

See Also:
  - `ATT_PRIMITIVE`
  - Constant Field Values

### ATT_ARRAY_DEFAULT

public static final String ATT_ARRAY_DEFAULT
default value for attribute ATT_ARRAY

See Also:
  - `ATT_ARRAY`
  - Constant Field Values

### ATT_NULL_DEFAULT

public static final String ATT_NULL_DEFAULT
default value for attribute ATT_NULL

See Also:
  - `ATT_NULL`
  - Constant Field Values

### DOCTYPE

public static final String DOCTYPE
the DOCTYPE for the serialization

## Constructor Details

### XMLSerialization

public XMLSerialization() throws Exception
initializes the serialization

Throws:
  `Exception` - if initialization fails

## Method Details

### clear

public void clear() throws Exception
generates internally a new XML document and clears also the IgnoreList and the mappings for the Read/Write-Methods

Throws:
  `Exception` - if something goes wrong

### getVersion

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

Returns:
  the current version
See Also:
  - `Version`

### writeToXML

public Element writeToXML(Element parent, Object o, String name) throws 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:
  `Exception` - if the DOM creation fails
See Also:
  - `overrideClassname(Object)`
  - `overrideClassname(String)`
  - `m_ClassnameOverride`

### toXML

public XMLDocument toXML(Object o) throws 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:
  `Exception` - if XML generation fails

### readBooleanFromXML

public boolean readBooleanFromXML(Element node) throws Exception
builds the primitive from the given DOM node.

Parameters:
  `node` - the associated XML node
Returns:
  the primitive created from the XML description
Throws:
  `Exception` - if instantiation fails

### readByteFromXML

public byte readByteFromXML(Element node) throws Exception
builds the primitive from the given DOM node.

Parameters:
  `node` - the associated XML node
Returns:
  the primitive created from the XML description
Throws:
  `Exception` - if instantiation fails

### readCharFromXML

public char readCharFromXML(Element node) throws Exception
builds the primitive from the given DOM node.

Parameters:
  `node` - the associated XML node
Returns:
  the primitive created from the XML description
Throws:
  `Exception` - if instantiation fails

### readDoubleFromXML

public double readDoubleFromXML(Element node) throws Exception
builds the primitive from the given DOM node.

Parameters:
  `node` - the associated XML node
Returns:
  the primitive created from the XML description
Throws:
  `Exception` - if instantiation fails

### readFloatFromXML

public float readFloatFromXML(Element node) throws Exception
builds the primitive from the given DOM node.

Parameters:
  `node` - the associated XML node
Returns:
  the primitive created from the XML description
Throws:
  `Exception` - if instantiation fails

### readIntFromXML

public int readIntFromXML(Element node) throws Exception
builds the primitive from the given DOM node.

Parameters:
  `node` - the associated XML node
Returns:
  the primitive created from the XML description
Throws:
  `Exception` - if instantiation fails

### readLongFromXML

public long readLongFromXML(Element node) throws Exception
builds the primitive from the given DOM node.

Parameters:
  `node` - the associated XML node
Returns:
  the primitive created from the XML description
Throws:
  `Exception` - if instantiation fails

### readShortFromXML

public short readShortFromXML(Element node) throws Exception
builds the primitive from the given DOM node.

Parameters:
  `node` - the associated XML node
Returns:
  the primitive created from the XML description
Throws:
  `Exception` - if instantiation fails

### readFromXML

public Object readFromXML(Object o, String name, Element child) throws 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:
  `Exception` - if something goes wrong

### readFromXML

public Object readFromXML(Element node) throws 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:
  `Exception` - if instantiation fails

### fromXML

public Object fromXML(Document document) throws 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:
  `Exception` - if object instantiation fails

### read

public Object read(String xml) throws 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 "invalid input: '<'?xml" is not found then it is considered a file)
Returns:
  the generated instance
Throws:
  `Exception` - if something goes wrong with the parsing

### read

public Object read(File file) throws Exception
parses the given file and returns a DOM document

Parameters:
  `file` - the XML file to parse
Returns:
  the parsed DOM document
Throws:
  `Exception` - if something goes wrong with the parsing

### read

public Object read(InputStream stream) throws Exception
parses the given stream and returns a DOM document

Parameters:
  `stream` - the XML stream to parse
Returns:
  the parsed DOM document
Throws:
  `Exception` - if something goes wrong with the parsing

### read

public Object read(Reader reader) throws Exception
parses the given reader and returns a DOM document

Parameters:
  `reader` - the XML reader to parse
Returns:
  the parsed DOM document
Throws:
  `Exception` - if something goes wrong with the parsing

### write

public void write(String file, Object o) throws Exception
writes the given object into the file

Parameters:
  `file` - the filename to write to
  `o` - the object to serialize as XML
Throws:
  `Exception` - if something goes wrong with the parsing

### write

public void write(File file, Object o) throws Exception
writes the given object into the file

Parameters:
  `file` - the filename to write to
  `o` - the object to serialize as XML
Throws:
  `Exception` - if something goes wrong with the parsing

### write

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

Parameters:
  `stream` - the filename to write to
  `o` - the object to serialize as XML
Throws:
  `Exception` - if something goes wrong with the parsing

### write

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

Parameters:
  `writer` - the filename to write to
  `o` - the object to serialize as XML
Throws:
  `Exception` - if something goes wrong with the parsing

### main

public static void main(String[] args) throws 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:
  `Exception`

### getRevision

public String getRevision()
Returns the revision string.

Specified by:
  `getRevision` in interface `RevisionHandler`
Returns:
  the revision