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:

XMLException

Constructor Summary

XMLDoc()
A non-initialized XMLDoc.

XMLDoc(String systemid, boolean validating, boolean namespaceAware, boolean expandEntities)
Reads and parses the XML document.

Method Summary

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 Detail

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 Detail

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:

getErrors()

hasWarnings

public boolean hasWarnings()

Determines whether the parser found any validation warnings.

Returns:

True if warnings were found, else false.

See Also:

getWarnings()

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:

hasErrors()

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:

hasWarnings()