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: 11102 $
  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

    Methods
    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.
    `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

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