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: 13477 $
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 List<String>`
  `SUPPRESS_PROPERTY_WARNINGS`
  List of fully qualified property names to suppress any warning messages for
  `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.
  `void`
  `setSuppressWarnings(boolean suppress)`
  Set whether to suppress warning messages or not
  `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

  - ### SUPPRESS_PROPERTY_WARNINGS

    public static final List<String> SUPPRESS_PROPERTY_WARNINGS
    List of fully qualified property names to suppress any warning messages for

- ## Constructor Details

  - ### XMLSerialization

    public XMLSerialization() throws Exception
    initializes the serialization
    Throws:
      `Exception` - if initialization fails

- ## Method Details

  - ### 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 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 "<?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