com.isti.util
Class IstiXmlUtils

java.lang.Object
  com.isti.util.ErrorMessageMgr
      com.isti.util.IstiXmlUtils

All Implemented Interfaces:

ErrorMsgMgrIntf

Direct Known Subclasses:

IstiXmlLoader, XmlConfigLoader

public class IstiXmlUtils

extends ErrorMessageMgr

Class IstiXmlUtils implements utilities for XML. The JDOM library 'jdom.jar' is required, and under Java 1.3 the Xerces library ('xerces.jar' from Apache) is also needed.

Nested Class Summary

static class

IstiXmlUtils.RootElement Root element.

Field Summary

static java.lang.String	ISO_8859_1_ENCODING_FORMAT ISO-8859-1 encoding.
protected boolean	loadFileOpenedFlag Flag set true if file opened successfully by 'loadFile()' method.
protected Element	rootElement Root element in file.
static boolean	useDocumentFlag Use document flag.
static java.lang.String	UTF_8_ENCODING_FORMAT UTF-8 encoding.
static java.lang.String	XML_FILE_EXTENSION XML file extension.
static java.lang.String	XML_STYLESHEET XML stylesheet text.
static java.lang.String	XML_STYLESHEET_PROCESSING_INSTRUCTION XML stylesheet processing text.
static SAXBuilder	xmlBuilderObj Static JDOM XML Document builder object (without validation).
static XMLOutputter	xmlFileOutputterObj Static JDOM XML text output formatter object (for file output).
static XMLOutputter	xmlFixedStrOutputterObj Static text output formatter object (for "fixed" string output).
static XMLOutputter	xmlStrOutputterObj Static JDOM XML text output formatter object (for string output).

Constructor Summary

IstiXmlUtils()
Constructs a XML utilities object.

Method Summary

static java.lang.String	addXmlFileExtension(java.lang.String fileName) Adds the ".xml" file extension to a file name.
void	clearErrorMessage() Clears the error message string.
static java.lang.String	convertFromEscapedCodes(java.lang.String srcStr, int maxEscVal) Converts "&##;" escape strings in the given data to characters.
Element	createRootElement(java.lang.String name) Creates the root element with the specified name.
static java.lang.String	ctrlCharsFromEscapedCodes(java.lang.String srcStr) Converts "&##;" escape strings in the given data to control characters.
static java.lang.String	ctrlCharsToEscapedCodes(java.lang.String srcStr) Converts control characters in the given data to "&##;" escape strings.
static boolean	ctrlCharsToEscapedCodes(java.lang.StringBuffer buff) Converts control characters in the given data to "&##;" escape strings.
static java.lang.String	elementToFixedString(Element xmlMsgObj) Converts a JDOM 'Element' object to an XML-format string.
static java.lang.String	elementToString(Element xmlMsgObj) Converts a JDOM 'Element' object to an XML-format string.
static java.lang.String	elementToString(Element xmlMsgObj, boolean normalizeFlag) Converts a JDOM 'Element' object to an XML-format string.
protected Element	findElement(java.lang.String attribute, java.lang.String value) Finds the element with the specified attribute value.
protected Element	findElement(java.lang.String attribute, java.lang.String value, Element element) Finds the element with the specified attribute value.
static Element	getAnyNSChild(Element parentElem, java.lang.String childNameStr) Returns the first child element within the given element with the given local name (regardless of namespace).
static java.lang.String	getChildDataFixedStr(Element parentElementObj) Converts all the child elements of the given element to strings and returns the concatenation of all the strings.
static java.lang.String	getChildDataStr(Element parentElementObj) Converts all the child elements of the given element to strings and returns the concatenation of all the strings.
static java.lang.String	getChildDataStr(Element parentElementObj, boolean normalizeFlag) Converts all the child elements of the given element to strings and returns the concatenation of all the strings.
protected static java.lang.String	getChildDataStr(Element parentElementObj, boolean normalizeFlag, boolean fixStrFlag) Converts all the child elements of the given element to strings and returns the concatenation of all the strings.
protected java.lang.Object	getComponentForClass(java.lang.String className) Creates a new instance of the class represented by the class or interface with the given string name.
static java.lang.String	getEncodedString(java.lang.String s, java.lang.String encoding) Gets the encoded string.
boolean	getErrorFlag() Returns true if an error was detected.
java.lang.String	getErrorMessage() Returns message string for last error (or 'No error' if none).
boolean	getLoadFileOpenedFlag() Returns the flag indicator of whether or not the XML file was successfully opened in the last call to 'loadFile()'.
Element	getRootElement() Gets the root element that was loaded.
boolean	loadFile(java.lang.String fileName, java.lang.String rootElementName) Loads an XML file.
boolean	loadStream(java.io.InputStream stmObj, java.lang.String rootElementName) Loads an XML data from an input stream.
boolean	loadStream(java.io.InputStream stmObj, java.lang.String rootElementName, java.lang.String fileName) Loads an XML data from an input stream.
boolean	loadStream(java.io.Reader rdrObj, java.lang.String rootElementName) Loads an XML data from an input stream.
boolean	loadStream(java.io.Reader rdrObj, java.lang.String rootElementName, java.lang.String fileName) Loads an XML data from an input stream.
boolean	saveToFile(java.lang.String fileName) Saves the "root" element loaded via 'loadFile()' to a file.
boolean	saveToFile(java.lang.String fileName, Element elemObj) Saves an element to a file.
static void	saveToStream(java.io.OutputStream stmObj, Element elemObj) Saves an element to a stream.
static void	saveToStream(java.io.Writer wtrObj, Element elemObj) Saves an element to a stream.
static void	setDocumentStylesheet(Document documentObj, java.lang.String uri) Sets the Document stylesheet.
static void	setElementNamespace(Element elementObj, Namespace namespaceObj) Sets the element namespace.
static void	setElementNamespace(Element elementObj, java.lang.String prefix, java.lang.String uri) Sets the element namespace.
protected void	setErrorMessage(java.lang.String str) Enters an error message (if none previously entered).
static void	setFileLineSeparator(java.lang.String lineSeparator) This will set the newline separator (lineSeparator).
static void	setFileOmitDeclaration(boolean flgVal) Sets whether the XML declaration will be omitted while outputting to files.
static void	setFileOmitEncoding(boolean flgVal) Sets whether the document encoding will be omitted while outputting to files.
static void	setFileOutExpandEmptyElements(boolean flgVal) Sets whether empty elements are expanded from <tagName/> to <tagName></tagName> while outputting to files.
static void	setFileOutIndent(java.lang.String indentStr) Sets the indent String to use while outputting to files.
static void	setFileOutNewlines(boolean flgVal) Sets whether newlines should be added while outputting to files.
static void	setFileOutTextTrim(boolean flgVal) Sets whether the text has leading/trailing whitespace trimmed while outputting to files.
static void	setLoadExternalDTDFeature(boolean flgVal) Sets the state of the load-external-DTD feature on the SAX parser.
void	setRootElement(Element elemObj) Sets the root element.
static void	setStrOutExpandEmptyElements(boolean flgVal) Sets whether empty elements are expanded from <tagName/> to <tagName></tagName> while outputting to strings.
static void	setStrOutIndent(java.lang.String indentStr) Sets the indent String to use while outputting to strings.
static void	setStrOutNewlines(boolean flgVal) Sets whether newlines should be added while outputting to strings.
static void	setStrOutTextTrim(boolean flgVal) Sets whether the text has leading/trailing whitespace trimmed while outputting to strings.
static Element	stringToElement(java.lang.String xmlStr) Converts an XML-format string to a JDOM 'Element' object.

Methods inherited from class com.isti.util.ErrorMessageMgr

clearErrorMessageString, clearFetchedErrorMessage, enterErrorMessageString, getErrorMessageFlag, getErrorMessageString, getUnfetchedMessageFlag, setErrorMessageString

Methods inherited from class java.lang.Object

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

Field Detail

useDocumentFlag

public static boolean useDocumentFlag

Use document flag.

loadFileOpenedFlag

protected boolean loadFileOpenedFlag

Flag set true if file opened successfully by 'loadFile()' method.

rootElement

protected Element rootElement

Root element in file.

XML_STYLESHEET

public static final java.lang.String XML_STYLESHEET

XML stylesheet text.

See Also:

Constant Field Values

XML_STYLESHEET_PROCESSING_INSTRUCTION

public static final java.lang.String XML_STYLESHEET_PROCESSING_INSTRUCTION

XML stylesheet processing text.

See Also:

Constant Field Values

XML_FILE_EXTENSION

public static final java.lang.String XML_FILE_EXTENSION

XML file extension.

See Also:

Constant Field Values

xmlBuilderObj

public static final SAXBuilder xmlBuilderObj

Static JDOM XML Document builder object (without validation).

xmlStrOutputterObj

public static final XMLOutputter xmlStrOutputterObj

Static JDOM XML text output formatter object (for string output).

xmlFileOutputterObj

public static final XMLOutputter xmlFileOutputterObj

Static JDOM XML text output formatter object (for file output).

xmlFixedStrOutputterObj

public static final XMLOutputter xmlFixedStrOutputterObj

Static text output formatter object (for "fixed" string output).

UTF_8_ENCODING_FORMAT

public static final java.lang.String UTF_8_ENCODING_FORMAT

UTF-8 encoding. May be used for the setEncoding() method.

See Also:

Constant Field Values

ISO_8859_1_ENCODING_FORMAT

public static final java.lang.String ISO_8859_1_ENCODING_FORMAT

ISO-8859-1 encoding. May be used for the setEncoding() method.

See Also:

Constant Field Values

Constructor Detail

IstiXmlUtils

public IstiXmlUtils()

Constructs a XML utilities object.

Method Detail

setDocumentStylesheet

public static void setDocumentStylesheet(Document documentObj,
                                         java.lang.String uri)

Sets the Document stylesheet.

Parameters:

documentObj - the 'Document' object.

uri - String URI of the stylesheet.

setFileOmitDeclaration

public static void setFileOmitDeclaration(boolean flgVal)

Sets whether the XML declaration will be omitted while outputting to files. The default value is 'false'.

Parameters:

flgVal - true to omit the XML declaration.

setFileOmitEncoding

public static void setFileOmitEncoding(boolean flgVal)

Sets whether the document encoding will be omitted while outputting to files. The default value is 'false'.

Parameters:

flgVal - true to omit the document encoding.

setFileOutNewlines

public static void setFileOutNewlines(boolean flgVal)

Sets whether newlines should be added while outputting to files. The default value is 'true'.

Parameters:

flgVal - true indicates new lines should be added for beautification.

setFileOutIndent

public static void setFileOutIndent(java.lang.String indentStr)

Sets the indent String to use while outputting to files. This is usually a String of empty spaces. If you pass null, or the empty string (""), then no indentation will happen. Default: none (null)

Parameters:

indentStr - String to use for indentation.

setFileOutTextTrim

public static void setFileOutTextTrim(boolean flgVal)

Sets whether the text has leading/trailing whitespace trimmed while outputting to files. Default: false

Parameters:

flgVal - true to trim the leading/trailing whitespace, false to use text verbatim.

setElementNamespace

public static void setElementNamespace(Element elementObj,
                                       java.lang.String prefix,
                                       java.lang.String uri)

Sets the element namespace.

Parameters:

elementObj - the 'Element' object.

prefix - String prefix to map to Namespace.

uri - String URI of new Namespace.

setElementNamespace

public static void setElementNamespace(Element elementObj,
                                       Namespace namespaceObj)

Sets the element namespace.

Parameters:

elementObj - the 'Element' object.

namespaceObj - the 'Namespace' object.

setFileLineSeparator

public static void setFileLineSeparator(java.lang.String lineSeparator)

This will set the newline separator (lineSeparator). The default is \r\n. Note that if the "newlines" property is false, this value is irrelevant.

Parameters:

lineSeparator - String line separator to use or null for the system default.

See Also:

setFileOutNewlines

setFileOutExpandEmptyElements

public static void setFileOutExpandEmptyElements(boolean flgVal)

Sets whether empty elements are expanded from <tagName/> to <tagName></tagName> while outputting to files. Default: false

Parameters:

flgVal - true to expand elements.

setStrOutNewlines

public static void setStrOutNewlines(boolean flgVal)

Sets whether newlines should be added while outputting to strings. The default value is 'true'.

Parameters:

flgVal - true indicates new lines should be added for beautification.

setStrOutIndent

public static void setStrOutIndent(java.lang.String indentStr)

Sets the indent String to use while outputting to strings. This is usually a String of empty spaces. If you pass null, or the empty string (""), then no indentation will happen. Default: none (null)

Parameters:

indentStr - String to use for indentation.

setStrOutTextTrim

public static void setStrOutTextTrim(boolean flgVal)

Sets whether the text has leading/trailing whitespace trimmed while outputting to strings. Default: false

Parameters:

flgVal - true to trim the leading/trailing whitespace, false to use text verbatim.

setStrOutExpandEmptyElements

public static void setStrOutExpandEmptyElements(boolean flgVal)

Sets whether empty elements are expanded from <tagName/> to <tagName></tagName> while outputting to strings. Default: false

Parameters:

flgVal - true to expand elements.

setLoadExternalDTDFeature

public static void setLoadExternalDTDFeature(boolean flgVal)

Sets the state of the load-external-DTD feature on the SAX parser. This determines if the parser will attempt to load exteral DTD files specified at the top of the XML file. The feature may not work with parser libraries other than Xerces. (If Internet access is not available when the parser attempts to load an external DTD then an exception will be thrown. Setting this feature to 'false' prevents the parser from attempting to load the external DTD file.)

Parameters:

flgVal - true to enable to loading of external DTD files; false to disable to loading of external DTD files.

addXmlFileExtension

public static java.lang.String addXmlFileExtension(java.lang.String fileName)

Adds the ".xml" file extension to a file name.

Parameters:

fileName - the file name to use.

Returns:

file name with XML file extension added if needed.

getComponentForClass

protected java.lang.Object getComponentForClass(java.lang.String className)

Creates a new instance of the class represented by the class or interface with the given string name. The class is instantiatied as if by a new expression with an empty argument list. The class is initialized if it has not already been initialized.

Parameters:

className - the fully qualified name of the desired class.

Returns:

a newly allocated instance of the class represented by this object.

findElement

protected Element findElement(java.lang.String attribute,
                              java.lang.String value)

Finds the element with the specified attribute value.

Parameters:

attribute - the attribute of the element to find.

value - the attribute value of the element to find.

Returns:

the element with the specified attribute value.

findElement

protected Element findElement(java.lang.String attribute,
                              java.lang.String value,
                              Element element)

Finds the element with the specified attribute value.

Parameters:

attribute - the attribute of the element to find.

value - the attribute value of the element to find.

element - the element to start with.

Returns:

the element with the specified attribute value.

getRootElement

public Element getRootElement()

Gets the root element that was loaded.

Returns:

the root element that was loaded, or null if none.

setRootElement

public void setRootElement(Element elemObj)

Sets the root element.

Parameters:

elemObj - the element object to use.

See Also:

createRootElement

loadFile

public boolean loadFile(java.lang.String fileName,
                        java.lang.String rootElementName)

Loads an XML file. Attempts to open the given name as a local file, as a URL, as a resource and as an entry in a 'jar' file (whichever works first).

Parameters:

fileName - the name of the XML file to load.

rootElementName - the expected name of the root element in the XML file, or null to accept any name.

Returns:

true if the file was loaded, false if an error occurred (in which case an error message may be fetched via the 'getErrorMessage()' method).

getLoadFileOpenedFlag

public boolean getLoadFileOpenedFlag()

Returns the flag indicator of whether or not the XML file was successfully opened in the last call to 'loadFile()'.

Returns:

true if the file was successfully opened, false if not.

loadStream

public boolean loadStream(java.io.Reader rdrObj,
                          java.lang.String rootElementName,
                          java.lang.String fileName)

Loads an XML data from an input stream.

Parameters:

rdrObj - input stream to use.

rootElementName - the expected name of the root element in the XML file, or null to accept any name.

fileName - filename string to use for error messages, or null for no filename.

Returns:

true if the file was loaded, false if an error occurred (in which case an error message may be fetched via the 'getErrorMessage()' method).

loadStream

public boolean loadStream(java.io.Reader rdrObj,
                          java.lang.String rootElementName)

Loads an XML data from an input stream.

Parameters:

rdrObj - input stream to use.

rootElementName - the expected name of the root element in the XML file, or null to accept any name.

Returns:

true if the file was loaded, false if an error occurred (in which case an error message may be fetched via the 'getErrorMessage()' method).

loadStream

public boolean loadStream(java.io.InputStream stmObj,
                          java.lang.String rootElementName,
                          java.lang.String fileName)

Loads an XML data from an input stream.

Parameters:

stmObj - input stream to use.

rootElementName - the expected name of the root element in the XML file, or null to accept any name.

fileName - filename string to use for error messages, or null for no filename.

Returns:

true if the file was loaded, false if an error occurred (in which case an error message may be fetched via the 'getErrorMessage()' method).

loadStream

public boolean loadStream(java.io.InputStream stmObj,
                          java.lang.String rootElementName)

Loads an XML data from an input stream.

Parameters:

stmObj - input stream to use.

rootElementName - the expected name of the root element in the XML file, or null to accept any name.

Returns:

true if the file was loaded, false if an error occurred (in which case an error message may be fetched via the 'getErrorMessage()' method).

saveToFile

public boolean saveToFile(java.lang.String fileName,
                          Element elemObj)

Saves an element to a file. Any needed directories above the file are created.

Parameters:

fileName - the name of the file to use.

elemObj - element object to be saved.

Returns:

true if the file was saved, false if an error occurred (in which case an error message may be fetched via the 'getErrorMessage()' method).

saveToFile

public boolean saveToFile(java.lang.String fileName)

Saves the "root" element loaded via 'loadFile()' to a file. Any needed directories above the file are created.

Parameters:

fileName - the name of the file to use.

Returns:

true if the file was saved, false if an error occurred (in which case an error message may be fetched via the 'getErrorMessage()' method).

getErrorFlag

public boolean getErrorFlag()

Returns true if an error was detected. The error message may be fetched via the 'getErrorMessage()' method.

Returns:

true if an error was detected.

getErrorMessage

public java.lang.String getErrorMessage()

Returns message string for last error (or 'No error' if none).

Returns:

the error message.

clearErrorMessage

public void clearErrorMessage()

Clears the error message string.

createRootElement

public Element createRootElement(java.lang.String name)

Creates the root element with the specified name.

Parameters:

name - String name of element.

Returns:

the root Element.

See Also:

setRootElement

setErrorMessage

protected void setErrorMessage(java.lang.String str)

Enters an error message (if none previously entered).

Parameters:

str - the error message.

elementToString

public static java.lang.String elementToString(Element xmlMsgObj,
                                               boolean normalizeFlag)
                                        throws java.io.IOException

Converts a JDOM 'Element' object to an XML-format string.

Parameters:

xmlMsgObj - the JDOM 'Element' object to use.

normalizeFlag - if true then the returned string is normalized by removing CR/LF characters (all surrounding whitespace is removed and internal whitespace is changed to a single space).

Returns:

The string version of the element (and its children).

Throws:

java.io.IOException - if an error occurs while converting.

elementToString

public static java.lang.String elementToString(Element xmlMsgObj)
                                        throws java.io.IOException

Converts a JDOM 'Element' object to an XML-format string.

Parameters:

xmlMsgObj - the JDOM 'Element' object to use.

Returns:

The string version of the element (and its children).

Throws:

java.io.IOException - if an error occurs while converting.

elementToFixedString

public static java.lang.String elementToFixedString(Element xmlMsgObj)
                                             throws java.io.IOException

Converts a JDOM 'Element' object to an XML-format string. Whitespace between elements is removed and control characters within elements are encoded to "&##;" strings. This allows linefeeds to be encoded and then decoded later.

Parameters:

xmlMsgObj - the JDOM 'Element' object to use.

Returns:

The string version of the element (and its children).

Throws:

java.io.IOException - if an error occurs while converting.

stringToElement

public static Element stringToElement(java.lang.String xmlStr)
                               throws JDOMException

Converts an XML-format string to a JDOM 'Element' object.

Parameters:

xmlStr - the XML-format string to use.

Returns:

a JDOM 'Element' object.

Throws:

JDOMException - if an error occurs while parsing.

saveToStream

public static void saveToStream(java.io.Writer wtrObj,
                                Element elemObj)
                         throws java.io.IOException

Saves an element to a stream.

Parameters:

wtrObj - output stream to use.

elemObj - element object to be saved.

Throws:

java.io.IOException - if an error occurs.

saveToStream

public static void saveToStream(java.io.OutputStream stmObj,
                                Element elemObj)
                         throws java.io.IOException

Saves an element to a stream.

Parameters:

stmObj - output stream to use.

elemObj - element object to be saved.

Throws:

java.io.IOException - if an error occurs.

getChildDataStr

protected static java.lang.String getChildDataStr(Element parentElementObj,
                                                  boolean normalizeFlag,
                                                  boolean fixStrFlag)

Converts all the child elements of the given element to strings and returns the concatenation of all the strings. Any textual content directly held under this element is also included.

Parameters:

parentElementObj - the element object to use.

normalizeFlag - if true then the returned string is normalized by removing CR/LF characters (all surrounding whitespace is removed and internal whitespace is changed to a single space).

fixStrFlag - true to "fix" string data (whitespace between elements removed and control characters within elements encoded to "&##;" strings); false to normalize string data.

Returns:

The string version of all the child data and elements.

getChildDataStr

public static java.lang.String getChildDataStr(Element parentElementObj,
                                               boolean normalizeFlag)

Converts all the child elements of the given element to strings and returns the concatenation of all the strings. Any textual content directly held under this element is also included.

Parameters:

parentElementObj - the element object to use.

normalizeFlag - if true then the returned string is normalized by removing CR/LF characters (all surrounding whitespace is removed and internal whitespace is changed to a single space).

Returns:

The string version of all the child data and elements.

getChildDataStr

public static java.lang.String getChildDataStr(Element parentElementObj)

Converts all the child elements of the given element to strings and returns the concatenation of all the strings. Any textual content directly held under this element is also included. The returned text is not normalized.

Parameters:

parentElementObj - the element object to use.

Returns:

The string version of all the child data and elements.

getChildDataFixedStr

public static java.lang.String getChildDataFixedStr(Element parentElementObj)

Converts all the child elements of the given element to strings and returns the concatenation of all the strings. Any textual content directly held under this element is also included. Whitespace between elements is removed and control characters within elements are encoded to "&##;" strings. This allows linefeeds to be encoded and then decoded later.

Parameters:

parentElementObj - the element object to use.

Returns:

The string version of all the child data and elements.

getAnyNSChild

public static Element getAnyNSChild(Element parentElem,
                                    java.lang.String childNameStr)

Returns the first child element within the given element with the given local name (regardless of namespace).

Parameters:

parentElem - element containing the child element.

childNameStr - name of child element to match, or null to match the first child element found.

Returns:

The first matching child element, or null if none found.

getEncodedString

public static java.lang.String getEncodedString(java.lang.String s,
                                                java.lang.String encoding)

Gets the encoded string.

Parameters:

s - the string to encode.

encoding - set encoding format. Use XML-style names like "UTF-8" or "ISO-8859-1" or "US-ASCII"

Returns:

the encoded string or the original string if an error occurs.

ctrlCharsToEscapedCodes

public static boolean ctrlCharsToEscapedCodes(java.lang.StringBuffer buff)

Converts control characters in the given data to "&##;" escape strings.

Parameters:

buff - data buffer to be read and modified.

Returns:

true if any control characters where converted; false if not.

ctrlCharsToEscapedCodes

public static java.lang.String ctrlCharsToEscapedCodes(java.lang.String srcStr)

Converts control characters in the given data to "&##;" escape strings.

Parameters:

srcStr - source string for data.

Returns:

The converted string, or the original string if no control characters were converted.

convertFromEscapedCodes

public static java.lang.String convertFromEscapedCodes(java.lang.String srcStr,
                                                       int maxEscVal)

Converts "&##;" escape strings in the given data to characters.

Parameters:

srcStr - source string for data.

maxEscVal - maximum value for "&##;" codes, or 0 for no maximum.

Returns:

The converted string, or the original string if no characters were converted.

ctrlCharsFromEscapedCodes

public static java.lang.String ctrlCharsFromEscapedCodes(java.lang.String srcStr)

Converts "&##;" escape strings in the given data to control characters. If the code value is greater than 31 then the escape string is not converted.

Parameters:

srcStr - source string for data.

Returns:

The converted string, or the original string if no characters were converted.