Package weka.core.xml

# Class XMLDocument

java.lang.Object
weka.core.xml.XMLDocument

All Implemented Interfaces:
  `RevisionHandler`

Direct Known Subclasses:
  `XMLInstances`

public class XMLDocument extends Object implements RevisionHandler
This class offers some methods for generating, reading and writing XML documents.
It can only handle UTF-8.

Version:
  $Revision: 8034 $
Author:
  FracPete (fracpete at waikato dot ac dot nz)
See Also:
  - `PI`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `ATT_NAME`
  the "name" attribute.
  `static final String`
  `ATT_VERSION`
  the "version" attribute.
  `static final String`
  `DTD_ANY`
  the ANY placeholder.
  `static final String`
  `DTD_AT_LEAST_ONE`
  the at least one marker.
  `static final String`
  `DTD_ATTLIST`
  the AttList definition.
  `static final String`
  `DTD_CDATA`
  the CDATA placeholder.
  `static final String`
  `DTD_DOCTYPE`
  the DocType definition.
  `static final String`
  `DTD_ELEMENT`
  the Element definition.
  `static final String`
  `DTD_IMPLIED`
  the #IMPLIED placeholder.
  `static final String`
  `DTD_OPTIONAL`
  the optional marker.
  `static final String`
  `DTD_PCDATA`
  the #PCDATA placeholder.
  `static final String`
  `DTD_REQUIRED`
  the #REQUIRED placeholder.
  `static final String`
  `DTD_SEPARATOR`
  the option separator.
  `static final String`
  `DTD_ZERO_OR_MORE`
  the zero or more marker.
  `static final String`
  `PI`
  the parsing instructions "<?xml version=\"1.0\" encoding=\"utf-8\"?>" (may not show up in Javadoc due to tags!).
  `static final String`
  `VAL_NO`
  the value "no".
  `static final String`
  `VAL_YES`
  the value "yes".

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `XMLDocument()`
  initializes the factory with non-validating parser.
  `XMLDocument(File file)`
  Creates a new instance of XMLDocument.
  `XMLDocument(InputStream stream)`
  Creates a new instance of XMLDocument.
  `XMLDocument(Reader reader)`
  Creates a new instance of XMLDocument.
  `XMLDocument(String xml)`
  Creates a new instance of XMLDocument.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `clear()`
  sets up an empty DOM document, with the current DOCTYPE and root node.
  `Boolean`
  `evalBoolean(String xpath)`
  Evaluates and returns the boolean result of the XPath expression.
  `Double`
  `evalDouble(String xpath)`
  Evaluates and returns the double result of the XPath expression.
  `String`
  `evalString(String xpath)`
  Evaluates and returns the boolean result of the XPath expression.
  `NodeList`
  `findNodes(String xpath)`
  Returns the nodes that the given xpath expression will find in the document.
  `DocumentBuilder`
  `getBuilder()`
  returns the DocumentBuilder.
  `static Vector<Element>`
  `getChildTags(Node parent)`
  returns all non tag-children from the given node.
  `static Vector<Element>`
  `getChildTags(Node parent, String name)`
  returns all non tag-children from the given node.
  `static String`
  `getContent(Element node)`
  returns the text between the opening and closing tag of a node (performs a `trim()` on the result).
  `String`
  `getDocType()`
  returns the current DOCTYPE, can be `null`.
  `Document`
  `getDocument()`
  returns the parsed DOM document.
  `DocumentBuilderFactory`
  `getFactory()`
  returns the DocumentBuilderFactory.
  `Node`
  `getNode(String xpath)`
  Returns the node represented by the XPath expression.
  `String`
  `getRevision()`
  Returns the revision string.
  `String`
  `getRootNode()`
  returns the current root node.
  `boolean`
  `getValidating()`
  returns whether a validating parser is used.
  `static void`
  `main(String[] args)`
  for testing only.
  `Document`
  `newDocument(String docType, String rootNode)`
  creates a new Document with the given information.
  `void`
  `print()`
  prints the current DOM document to standard out.
  `Document`
  `read(File file)`
  parses the given file and returns a DOM document.
  `Document`
  `read(InputStream stream)`
  parses the given stream and returns a DOM document.
  `Document`
  `read(Reader reader)`
  parses the given reader and returns a DOM document.
  `Document`
  `read(String xml)`
  parses the given XML string (can be XML or a filename) and returns a DOM Document.
  `void`
  `setDocType(String docType)`
  sets the DOCTYPE-String to use in the XML output.
  `void`
  `setDocument(Document newDocument)`
  sets the DOM document to use.
  `void`
  `setRootNode(String rootNode)`
  sets the root node to use in the XML output.
  `void`
  `setValidating(boolean validating)`
  sets whether to use a validating parser or not.
  Note: this does clear the current DOM document!
  `String`
  `toString()`
  returns the current DOM document as XML-string.
  `void`
  `write(File file)`
  writes the current DOM document into the given file.
  `void`
  `write(OutputStream stream)`
  writes the current DOM document into the given stream.
  `void`
  `write(Writer writer)`
  writes the current DOM document into the given writer.
  `void`
  `write(String file)`
  writes the current DOM document into the given file.

  ### Methods inherited from class java.lang.Object

  `equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- ## Field Details

  - ### PI

    public static final String PI
    the parsing instructions "<?xml version=\"1.0\" encoding=\"utf-8\"?>" (may not show up in Javadoc due to tags!).
    See Also:
      - Constant Field Values

  - ### DTD_DOCTYPE

    public static final String DTD_DOCTYPE
    the DocType definition.
    See Also:
      - Constant Field Values

  - ### DTD_ELEMENT

    public static final String DTD_ELEMENT
    the Element definition.
    See Also:
      - Constant Field Values

  - ### DTD_ATTLIST

    public static final String DTD_ATTLIST
    the AttList definition.
    See Also:
      - Constant Field Values

  - ### DTD_OPTIONAL

    public static final String DTD_OPTIONAL
    the optional marker.
    See Also:
      - Constant Field Values

  - ### DTD_AT_LEAST_ONE

    public static final String DTD_AT_LEAST_ONE
    the at least one marker.
    See Also:
      - Constant Field Values

  - ### DTD_ZERO_OR_MORE

    public static final String DTD_ZERO_OR_MORE
    the zero or more marker.
    See Also:
      - Constant Field Values

  - ### DTD_SEPARATOR

    public static final String DTD_SEPARATOR
    the option separator.
    See Also:
      - Constant Field Values

  - ### DTD_CDATA

    public static final String DTD_CDATA
    the CDATA placeholder.
    See Also:
      - Constant Field Values

  - ### DTD_ANY

    public static final String DTD_ANY
    the ANY placeholder.
    See Also:
      - Constant Field Values

  - ### DTD_PCDATA

    public static final String DTD_PCDATA
    the #PCDATA placeholder.
    See Also:
      - Constant Field Values

  - ### DTD_IMPLIED

    public static final String DTD_IMPLIED
    the #IMPLIED placeholder.
    See Also:
      - Constant Field Values

  - ### DTD_REQUIRED

    public static final String DTD_REQUIRED
    the #REQUIRED placeholder.
    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 "name" attribute.
    See Also:
      - Constant Field Values

  - ### VAL_YES

    public static final String VAL_YES
    the value "yes".
    See Also:
      - Constant Field Values

  - ### VAL_NO

    public static final String VAL_NO
    the value "no".
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### XMLDocument

    public XMLDocument() throws Exception
    initializes the factory with non-validating parser.
    Throws:
      `Exception` - if the construction fails

  - ### XMLDocument

    public XMLDocument(String xml) throws Exception
    Creates a new instance of XMLDocument.
    Parameters:
      `xml` - the xml to parse (if "<?xml" is not found then it is considered a file)
    Throws:
      `Exception` - if the construction of the DocumentBuilder fails
    See Also:
      - `setValidating(boolean)`

  - ### XMLDocument

    public XMLDocument(File file) throws Exception
    Creates a new instance of XMLDocument.
    Parameters:
      `file` - the XML file to parse
    Throws:
      `Exception` - if the construction of the DocumentBuilder fails
    See Also:
      - `setValidating(boolean)`

  - ### XMLDocument

    public XMLDocument(InputStream stream) throws Exception
    Creates a new instance of XMLDocument.
    Parameters:
      `stream` - the XML stream to parse
    Throws:
      `Exception` - if the construction of the DocumentBuilder fails
    See Also:
      - `setValidating(boolean)`

  - ### XMLDocument

    public XMLDocument(Reader reader) throws Exception
    Creates a new instance of XMLDocument.
    Parameters:
      `reader` - the XML reader to parse
    Throws:
      `Exception` - if the construction of the DocumentBuilder fails
    See Also:
      - `setValidating(boolean)`

- ## Method Details

  - ### getFactory

    public DocumentBuilderFactory getFactory()
    returns the DocumentBuilderFactory.
    Returns:
      the DocumentBuilderFactory

  - ### getBuilder

    public DocumentBuilder getBuilder()
    returns the DocumentBuilder.
    Returns:
      the DocumentBuilder

  - ### getValidating

    public boolean getValidating()
    returns whether a validating parser is used.
    Returns:
      whether a validating parser is used

  - ### setValidating

    public void setValidating(boolean validating) throws Exception
    sets whether to use a validating parser or not.
    Note: this does clear the current DOM document!
    Parameters:
      `validating` - whether to use a validating parser
    Throws:
      `Exception` - if the instantiating of the DocumentBuilder fails

  - ### getDocument

    public Document getDocument()
    returns the parsed DOM document.
    Returns:
      the parsed DOM document

  - ### setDocument

    public void setDocument(Document newDocument)
    sets the DOM document to use.
    Parameters:
      `newDocument` - the DOM document to use

  - ### setDocType

    public void setDocType(String docType)
    sets the DOCTYPE-String to use in the XML output. Performs NO checking! if it is `null` the DOCTYPE is omitted.
    Parameters:
      `docType` - the DOCTYPE definition to use in XML output

  - ### getDocType

    public String getDocType()
    returns the current DOCTYPE, can be `null`.
    Returns:
      the current DOCTYPE definition, can be `null`

  - ### setRootNode

    public void setRootNode(String rootNode)
    sets the root node to use in the XML output. Performs NO checking with DOCTYPE!
    Parameters:
      `rootNode` - the root node to use in the XML output

  - ### getRootNode

    public String getRootNode()
    returns the current root node.
    Returns:
      the current root node

  - ### clear

    public void clear()
    sets up an empty DOM document, with the current DOCTYPE and root node.
    See Also:
      - `setRootNode(String)`
      - `setDocType(String)`

  - ### newDocument

    public Document newDocument(String docType, String rootNode)
    creates a new Document with the given information.
    Parameters:
      `docType` - the DOCTYPE definition (no checking happens!), can be null
      `rootNode` - the name of the root node (must correspond to the one given in `docType`)
    Returns:
      returns the just created DOM document for convenience

  - ### read

    public Document read(String xml) throws Exception
    parses the given XML string (can be XML or a filename) and returns a DOM Document.
    Parameters:
      `xml` - the xml to parse (if "<?xml" is not found then it is considered a file)
    Returns:
      the parsed DOM document
    Throws:
      `Exception` - if something goes wrong with the parsing

  - ### read

    public Document 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 Document 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 Document 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) throws Exception
    writes the current DOM document into the given file.
    Parameters:
      `file` - the filename to write to
    Throws:
      `Exception` - if something goes wrong with the parsing

  - ### write

    public void write(File file) throws Exception
    writes the current DOM document into the given file.
    Parameters:
      `file` - the filename to write to
    Throws:
      `Exception` - if something goes wrong with the parsing

  - ### write

    public void write(OutputStream stream) throws Exception
    writes the current DOM document into the given stream.
    Parameters:
      `stream` - the filename to write to
    Throws:
      `Exception` - if something goes wrong with the parsing

  - ### write

    public void write(Writer writer) throws Exception
    writes the current DOM document into the given writer.
    Parameters:
      `writer` - the filename to write to
    Throws:
      `Exception` - if something goes wrong with the parsing

  - ### getChildTags

    public static Vector<Element> getChildTags(Node parent)
    returns all non tag-children from the given node.
    Parameters:
      `parent` - the node to get the children from
    Returns:
      a vector containing all the non-text children

  - ### getChildTags

    public static Vector<Element> getChildTags(Node parent, String name)
    returns all non tag-children from the given node.
    Parameters:
      `parent` - the node to get the children from
      `name` - the name of the tags to return, "" for all
    Returns:
      a vector containing all the non-text children

  - ### findNodes

    public NodeList findNodes(String xpath)
    Returns the nodes that the given xpath expression will find in the document. Can return null if an error occurred.
    Parameters:
      `xpath` - the XPath expression to run on the document
    Returns:
      the nodelist

  - ### getNode

    public Node getNode(String xpath)
    Returns the node represented by the XPath expression. Can return null if an error occurred.
    Parameters:
      `xpath` - the XPath expression to run on the document
    Returns:
      the node

  - ### evalBoolean

    public Boolean evalBoolean(String xpath)
    Evaluates and returns the boolean result of the XPath expression.
    Parameters:
      `xpath` - the expression to evaluate
    Returns:
      the result of the evaluation, null in case of an error

  - ### evalDouble

    public Double evalDouble(String xpath)
    Evaluates and returns the double result of the XPath expression.
    Parameters:
      `xpath` - the expression to evaluate
    Returns:
      the result of the evaluation, null in case of an error

  - ### evalString

    public String evalString(String xpath)
    Evaluates and returns the boolean result of the XPath expression.
    Parameters:
      `xpath` - the expression to evaluate
    Returns:
      the result of the evaluation

  - ### getContent

    public static String getContent(Element node)
    returns the text between the opening and closing tag of a node (performs a `trim()` on the result).
    Parameters:
      `node` - the node to get the text from
    Returns:
      the content of the given node

  - ### print

    public void print()
    prints the current DOM document to standard out.

  - ### toString

    public String toString()
    returns the current DOM document as XML-string.
    Overrides:
      `toString` in class `Object`
    Returns:
      the document as XML-string representation

  - ### getRevision

    public String getRevision()
    Returns the revision string.
    Specified by:
      `getRevision` in interface `RevisionHandler`
    Returns:
      the revision

  - ### main

    public static void main(String[] args) throws Exception
    for testing only. takes the name of an XML file as first arg, reads that file, prints it to stdout and if a second filename is given, writes the parsed document to that again.
    Parameters:
      `args` - the commandline arguments
    Throws:
      `Exception` - if something goes wrong