Package org.dlese.dpc.xml

Class XMLDoc

java.lang.Object
org.dlese.dpc.xml.XMLDoc
public class XMLDoc extends Object
Reads and parses an XML document.
Author:
Steve Sullivan
See Also:

  • Constructor Summary

    Constructors
    Constructor
    Description
    XMLDoc()
    A non-initialized XMLDoc.
    XMLDoc(String systemid, boolean validating, boolean namespaceAware, boolean expandEntities)
    Reads and parses the XML document.

  • Method Summary

    Modifier and Type
    Method
    Description
    StringBuffer
    getErrors()
    Gets a human-readable validation error report if errors were found in the XML, otherwise returns an empty StringBuffer.
    StringBuffer
    getWarnings()
    Gets a human-readable validation warning report if warnings were found in the XML, otherwise returns an empty StringBuffer.
    boolean
    getXmlBoolean(String xpath)
    Retrieves a single boolean from an XML document.
    Element[]
    getXmlElements(int minnum, int maxnum, String xpathspec)
    Returns all Elements in an XML document that match the specified partial xpath.
    String
    getXmlField(String xpathspec)
    Returns the first occurance of the field that matches the specified partial xpath, or a an empty String if not found.
    String[]
    getXmlFields(int minnum, int maxnum, String xpathspec)
    Returns all strings in an XML document that match the specified partial xpath.
    String[]
    getXmlFields(String xpathspec)
    Returns all strings in an XML document that match the specified partial xpath, or a zero-length array if none were found.
    int
    getXmlInt(String xpath)
    Retrieves a single int from an XML document.
    String
    getXmlString(String xpath)
    Retrieves a single String from an XML document.
    boolean
    hasErrors()
    Determines whether the parser found any validation errors.
    boolean
    hasWarnings()
    Determines whether the parser found any validation warnings.
    static void
    main(String[] args)
    Test driver.
    void
    useXmlString(String xmlString, boolean validating, boolean namespaceAware, boolean expandEntities)
    Reads and parses the XML string, which is then the source of the XML used in this XMLDoc.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • XMLDoc

      public XMLDoc(String systemid, boolean validating, boolean namespaceAware, boolean expandEntities) throws XMLException
      Reads and parses the XML document.
      Parameters:
      systemid - Specifies the input file or url: e.g,
      • file:///usr/local/nonesuch.xml
      • http://www.nonesuch.com/nonsuch.xml
      If it represents a file, it must have 3 slashes and the path must be fully qualified.
      validating - Is the parser to be validating?
      namespaceAware - Is the parser to be namespace aware?
      expandEntities - DESCRIPTION
      Throws:
      XMLException - DESCRIPTION

    • XMLDoc

      public XMLDoc()
      A non-initialized XMLDoc. To read the actual XML, use method useXmlString(String, boolean,boolean,boolean).

  • Method Details

    • main

      public static void main(String[] args)
      Test driver.

    • useXmlString

      public void useXmlString(String xmlString, boolean validating, boolean namespaceAware, boolean expandEntities) throws XMLException
      Reads and parses the XML string, which is then the source of the XML used in this XMLDoc.
      Throws:
      XMLException

    • getXmlInt

      public int getXmlInt(String xpath) throws XMLException
      Retrieves a single int from an XML document. The specified xpath must occur exactly once in the document. See getXmlFields for additional doc on xpaths and on how occurances are counted.
      Parameters:
      xpath - The partial xpath specification.
      Returns:
      The int value
      Throws:
      XMLException - DESCRIPTION

    • getXmlBoolean

      public boolean getXmlBoolean(String xpath) throws XMLException
      Retrieves a single boolean from an XML document. The specified xpath must occur exactly once in the document. The boolean value is case insensitive and may be encoded as one of: "true", "false", "yes", "no". See getXmlFields for additional doc on xpaths and on how occurances are counted.
      Parameters:
      xpath - The partial xpath specification.
      Returns:
      The boolean value
      Throws:
      XMLException - DESCRIPTION

    • getXmlString

      public String getXmlString(String xpath) throws XMLException
      Retrieves a single String from an XML document. The specified xpath must occur exactly once in the document. See getXmlFields for additional doc on xpaths and on how occurances are counted.
      Parameters:
      xpath - The partial xpath specification.
      Returns:
      The xmlString value
      Throws:
      XMLException - If the requested xpath was not found.

    • getXmlElements

      public Element[] getXmlElements(int minnum, int maxnum, String xpathspec) throws XMLException
      Returns all Elements in an XML document that match the specified partial xpath. The xpathspec specifies the tail end (right side) of an xpath. For example:
      • "gamma": return the contents of all elements named "gamma"
      • "beta/gamma": return the contents of all elements named "gamma" whose immediate parent is named "beta", no matter what the higher level nodes are named.
      • "alpha/beta/gamma": return the contents of all elements named "gamma" whose immediate ancestors going up the chain are "beta", "alpha".
      • "beta/gamma@tau": find all beta/gamma as above, and for those having an attribute "tau" return the value of "tau".
      Notes : getXmlFields ...
      • Trims all leading and trailing white space.
      • Never returns a null or zero-length String. If the specified xpath or attribute exists in the document, but it's content is empty or all blank, it is not returned.
      • Never returns a null array. If there are no results, the returned array has length zero.
      • If the specified xpath is an interior node (not a leaf), returns the concatenation of all leafs under it. For example if the xpath is "beta" and the xml document contains:

        <beta>
        b1
        <gamma> ggg </gamma>
        b2
        <iota> iii </iota>
        b3
        </beta>

        the returned string will be "b1gggb2iiib3".

      Parameters:
      minnum - Minimum number of times xpathspec must be found.
      If there are fewer than minnum occurances of the xpathspec containing non-blank data, an XMLException is thrown.
      Occurances of xpathspec that are empty or all blank are not counted: see Notes above.
      maxnum - Maximum number of times xpathspec must be found.
      If there are more than maxnum occurances of the xpathspec containing non-blank data, an XMLException is thrown.
      If maxnum == 0, it is considered to be infinity.
      Occurances of xpathspec that are empty or all blank are not counted: see Notes above.
      xpathspec - the partial xpath specification; see above.
      Returns:
      The xmlFields value
      Throws:
      XMLException - if the minnum or maxnum constraints are violated.

    • getXmlFields

      public String[] getXmlFields(int minnum, int maxnum, String xpathspec) throws XMLException
      Returns all strings in an XML document that match the specified partial xpath. The xpathspec specifies the tail end (right side) of an xpath. For example:
      • "gamma": return the contents of all elements named "gamma"
      • "beta/gamma": return the contents of all elements named "gamma" whose immediate parent is named "beta", no matter what the higher level nodes are named.
      • "alpha/beta/gamma": return the contents of all elements named "gamma" whose immediate ancestors going up the chain are "beta", "alpha".
      • "beta/gamma@tau": find all beta/gamma as above, and for those having an attribute "tau" return the value of "tau".
      Notes : getXmlFields ...
      • Trims all leading and trailing white space.
      • Never returns a null or zero-length String. If the specified xpath or attribute exists in the document, but it's content is empty or all blank, it is not returned.
      • Never returns a null array. If there are no results, the returned array has length zero.
      • If the specified xpath is an interior node (not a leaf), returns the concatenation of all leafs under it. For example if the xpath is "beta" and the xml document contains:

        <beta>
        b1
        <gamma> ggg </gamma>
        b2
        <iota> iii </iota>
        b3
        </beta>

        the returned string will be "b1gggb2iiib3".

      Parameters:
      minnum - Minimum number of times xpathspec must be found.
      If there are fewer than minnum occurances of the xpathspec containing non-blank data, an XMLException is thrown.
      Occurances of xpathspec that are empty or all blank are not counted: see Notes above.
      maxnum - Maximum number of times xpathspec must be found.
      If there are more than maxnum occurances of the xpathspec containing non-blank data, an XMLException is thrown.
      If maxnum == 0, it is considered to be infinity.
      Occurances of xpathspec that are empty or all blank are not counted: see Notes above.
      xpathspec - the partial xpath specification; see above.
      Returns:
      The xmlFields value
      Throws:
      XMLException - if the minnum or maxnum constraints are violated.

    • getXmlFields

      public String[] getXmlFields(String xpathspec)
      Returns all strings in an XML document that match the specified partial xpath, or a zero-length array if none were found.
      Parameters:
      xpathspec - the partial xpath specification.
      Returns:
      The xmlFields value

    • getXmlField

      public String getXmlField(String xpathspec)
      Returns the first occurance of the field that matches the specified partial xpath, or a an empty String if not found.
      Parameters:
      xpathspec - the partial xpath specification.
      Returns:
      The xmlField value or empty String.

    • hasErrors

      public boolean hasErrors()
      Determines whether the parser found any validation errors.
      Returns:
      True if errors were found, else false.
      See Also:

    • hasWarnings

      public boolean hasWarnings()
      Determines whether the parser found any validation warnings.
      Returns:
      True if warnings were found, else false.
      See Also:

    • getErrors

      public StringBuffer getErrors()
      Gets a human-readable validation error report if errors were found in the XML, otherwise returns an empty StringBuffer.
      Returns:
      Error messages or an empty StringBuffer.
      See Also:

    • getWarnings

      public StringBuffer getWarnings()
      Gets a human-readable validation warning report if warnings were found in the XML, otherwise returns an empty StringBuffer.
      Returns:
      Warning messages or an empty StringBuffer.
      See Also: