net.charlesames.utility.xml
Class Xml

java.lang.Object
  net.charlesames.utility.xml.Xml

public class Xml
extends java.lang.Object

Singleton class wrapping functionality for XML input and output.

Author:

Charles Ames

Nested Class Summary

static class

Xml.XmlTags

Field Summary

static java.text.SimpleDateFormat	dateFormat Standard XML date format.
static java.lang.String	FILE_EXTENSION The standard extension for files containing text in XML format.
static java.text.SimpleDateFormat	timeFormat Standard XML time format.
static java.lang.String	XSI_NAMESPACE Namespace for XML node names prefixed with xsi, which stands for XML Schema Instance.

Method Summary

static org.w3c.dom.Element	appendAttributeElement(org.w3c.dom.Element parentElement, java.lang.String tagName, java.lang.String attributeName, java.lang.String value) Creates a child element with the indicated tag name and adds an attribute to the child.
static org.w3c.dom.Element	appendContentElement(org.w3c.dom.Element parentElement, java.lang.String tagName, java.lang.String value) Adds CDATA content to a node within a org.w3c.dom document.
static org.w3c.dom.Element	appendValueElement(org.w3c.dom.Element parentElement, java.lang.String tagName, java.lang.String value) Creates a child element with the indicated tag name and adds text content to the child.
static java.lang.String	cdataDecode(java.lang.String text) Decode a CDATA text stream from an XML data element.
static java.lang.String	cdataEncode(java.lang.String text) Encode a text string so it can be written as CDATA into an XML data element.
org.w3c.dom.Document	createDocument() Creates an org.w3c.dom document element.
org.w3c.dom.DocumentType	createDocumentType(java.lang.String qualifiedName, java.lang.String publicID, java.lang.String systemID) Creates an org.w3c.dom document type element.
org.w3c.dom.Document	createXmlDoc()
java.lang.String	documentToPrettyText(org.w3c.dom.Document document, int tabsize, org.w3c.dom.DocumentType documentType, java.lang.String encoding) Convert XML document into pretty-formatted text.
static org.w3c.dom.Element	findChildByAttribute(org.w3c.dom.Element parentElement, java.lang.String elementName, java.lang.String attributeName, java.lang.String attributeValue) Given a parent element, finds the first child element whose node name matches the elementName parameter AND whose value for a specified attribute matches the attributeValue parameter.
static java.lang.String	getAttributeElement(org.w3c.dom.Element parent, java.lang.String tagName, java.lang.String attributeName) Deprecated.
static org.w3c.dom.Element	getChildElement(org.w3c.dom.Element parent, java.lang.String tagName) Locates the child element with the indicated tag name.
static java.lang.String	getContentElement(org.w3c.dom.Element parentElement, java.lang.String tagName) Finds a child element with the given tagName and returns the text content.
static org.w3c.dom.Document	getDocument(org.w3c.dom.Node node) Get the document containing the indicated node.
static java.lang.Long	getLongContent(org.w3c.dom.Element element)
static java.lang.String	getNodePath(org.w3c.dom.Node node) Get the node-name path down to the indicated node.
static java.lang.String	getNodeTypeName(int nodeType) Convert numerical org.w3c.dom node types into words.
static Xml	getSingleton() Creates XML singleton on first invocation.
static java.lang.String	getValueElement(org.w3c.dom.Element parent, java.lang.String tagName) Extracts the text content of a child element with the indicated tag name.
org.w3c.dom.Document	readXmlDoc(java.io.File file) Parses an input text file into an org.w3c.dom Document object.
static void	setCDataText(org.w3c.dom.Node parent, java.lang.String text) Adds CDATA content to a node within a org.w3c.dom document.
void	writeXmlDoc(java.io.File file, org.w3c.dom.Document document, int tabsize, org.w3c.dom.DocumentType documentType, java.lang.String encoding)

Methods inherited from class java.lang.Object

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

Field Detail

FILE_EXTENSION

public static final java.lang.String FILE_EXTENSION

The standard extension for files containing text in XML format.

See Also:

Constant Field Values

XSI_NAMESPACE

public static final java.lang.String XSI_NAMESPACE

Namespace for XML node names prefixed with xsi, which stands for XML Schema Instance.

See Also:

Constant Field Values

dateFormat

public static final java.text.SimpleDateFormat dateFormat

Standard XML date format.

timeFormat

public static final java.text.SimpleDateFormat timeFormat

Standard XML time format.

Method Detail

getSingleton

public static Xml getSingleton()

Creates XML singleton on first invocation. Returns this singleton always.

Returns:

The XML singleton.

getDocument

public static org.w3c.dom.Document getDocument(org.w3c.dom.Node node)

Get the document containing the indicated node.

Parameters:

node - The indicated node.

Returns:

The node itself if the node is a Document; otherwise, the node's owner document.

createDocument

public org.w3c.dom.Document createDocument()

Creates an org.w3c.dom document element.

Returns:

The newly created document element.

createDocumentType

public org.w3c.dom.DocumentType createDocumentType(java.lang.String qualifiedName,
                                                   java.lang.String publicID,
                                                   java.lang.String systemID)

Creates an org.w3c.dom document type element. The parameters are passed directly through to org.w3c.dom.domimplementation.createDocumentType():

Parameters:

qualifiedName - The qualified name of the document type to be created.

publicID - The external subset public identifier.

systemID - The external subset system identifier.

Returns:

The newly created document type.

readXmlDoc

public org.w3c.dom.Document readXmlDoc(java.io.File file)

Parses an input text file into an org.w3c.dom Document object.

Parameters:

file - A File object specifying the input file.

Returns:

The newly created org.w3c.dom Document object.

createXmlDoc

public org.w3c.dom.Document createXmlDoc()

Returns:

A newly created, and empty, org.w3c.dom Document object.

documentToPrettyText

public java.lang.String documentToPrettyText(org.w3c.dom.Document document,
                                             int tabsize,
                                             org.w3c.dom.DocumentType documentType,
                                             java.lang.String encoding)

Convert XML document into pretty-formatted text.

Parameters:

document - The source document.

tabsize - Tab size

documentType - org.w3c.dom.DocumentType instance (null if no document type).

encoding -

Returns:

XML-formatted text string.

writeXmlDoc

public void writeXmlDoc(java.io.File file,
                        org.w3c.dom.Document document,
                        int tabsize,
                        org.w3c.dom.DocumentType documentType,
                        java.lang.String encoding)

Parameters:

file - A File object specifying the output file.

document - An org.w3c.dom Document object holding the data which is to be written out to the file.

tabsize - Number of characters to intent for each element-embedding level.

documentType - Document type (DTS declaration). Null if no document type.

encoding - Character encoding. Must be UTF-8, UTF-16, or null (defaults to UTF-8).

setCDataText

public static void setCDataText(org.w3c.dom.Node parent,
                                java.lang.String text)

Adds CDATA content to a node within a org.w3c.dom document.

Parameters:

parent - The org.w3c.dom element which is to receive the text data.

text - The text content which is to be added to the parent node.

findChildByAttribute

public static org.w3c.dom.Element findChildByAttribute(org.w3c.dom.Element parentElement,
                                                       java.lang.String elementName,
                                                       java.lang.String attributeName,
                                                       java.lang.String attributeValue)

Given a parent element, finds the first child element whose node name matches the elementName parameter AND whose value for a specified attribute matches the attributeValue parameter.

Parameters:

parentElement - The org.w3c.dom element whose child elements are to be scanned.

elementName - The desired element name.

attributeName - The name of the attribute to be checked.

attributeValue - The desired element value.

Returns:

The first child element whose node name matches the elementName parameter (null if not found).

appendContentElement

public static org.w3c.dom.Element appendContentElement(org.w3c.dom.Element parentElement,
                                                       java.lang.String tagName,
                                                       java.lang.String value)

Adds CDATA content to a node within a org.w3c.dom document.

Parameters:

parentElement - The org.w3c.dom element which is to receive the text data.

tagName - The name of the new child element which will contain the text data

value - The text content which will become the content of the new child node.

Returns:

The newly created child node.

getContentElement

public static java.lang.String getContentElement(org.w3c.dom.Element parentElement,
                                                 java.lang.String tagName)

Finds a child element with the given tagName and returns the text content.

Parameters:

parentElement - The org.w3c.dom element whose children are to be scanned.

tagName - The desired child node name.

Returns:

The text content of the located child node (null if not found).

getLongContent

public static java.lang.Long getLongContent(org.w3c.dom.Element element)

Parameters:

element - The org.w3c.dom element whose text content is to be parsed.

Returns:

A long parsed from the element's text content.

appendAttributeElement

public static org.w3c.dom.Element appendAttributeElement(org.w3c.dom.Element parentElement,
                                                         java.lang.String tagName,
                                                         java.lang.String attributeName,
                                                         java.lang.String value)

Creates a child element with the indicated tag name and adds an attribute to the child.

Parameters:

parentElement - An existing org.w3c.dom element to which the new node is to be appended.

tagName - The node name to be applied when creating the child node.

attributeName - The attribute name.

value - The attribute value.

Returns:

The newly created child node.

getAttributeElement

public static java.lang.String getAttributeElement(org.w3c.dom.Element parent,
                                                   java.lang.String tagName,
                                                   java.lang.String attributeName)

Deprecated.

Finds the first child node with the indicated tag name and extracts the value of the indicated attribute.

Parameters:

parent - The org.w3c.dom element whose children are to be scanned.

tagName - The desired child node name.

attributeName - The name of the attribute whose value is desired.

Returns:

The value of the indicated attribute for the indicated child. Blank if not found.

appendValueElement

public static org.w3c.dom.Element appendValueElement(org.w3c.dom.Element parentElement,
                                                     java.lang.String tagName,
                                                     java.lang.String value)

Creates a child element with the indicated tag name and adds text content to the child.

Parameters:

parentElement - An existing org.w3c.dom element to which the new node is to be appended.

tagName - The node name to be applied when creating the child node.

value - The text which is to become the new node's content.

Returns:

The newly created child node.

getValueElement

public static java.lang.String getValueElement(org.w3c.dom.Element parent,
                                               java.lang.String tagName)

Extracts the text content of a child element with the indicated tag name.

Parameters:

parent - An org.w3c.dom element whose children are to be scanned.

tagName - The desired child element's node name.

Returns:

The text content of the child element (blank if not found).

getChildElement

public static org.w3c.dom.Element getChildElement(org.w3c.dom.Element parent,
                                                  java.lang.String tagName)

Locates the child element with the indicated tag name.

Parameters:

parent - An org.w3c.dom element whose children are to be scanned.

tagName - The desired child element's node name.

Returns:

The desired child element (null if not found).

cdataEncode

public static java.lang.String cdataEncode(java.lang.String text)

Encode a text string so it can be written as CDATA into an XML data element.

Parameters:

text - The unencoded text.

Returns:

The encoded text.

cdataDecode

public static java.lang.String cdataDecode(java.lang.String text)

Decode a CDATA text stream from an XML data element.

Parameters:

text - The encoded text.

Returns:

The decoded text.

getNodePath

public static java.lang.String getNodePath(org.w3c.dom.Node node)

Get the node-name path down to the indicated node.

Parameters:

node - The indicated node.

Returns:

The node-name path down to the indicated node.

getNodeTypeName

public static java.lang.String getNodeTypeName(int nodeType)

Convert numerical org.w3c.dom node types into words.

Parameters:

nodeType - The org.w3c.dom node type, which is an integer.

Returns:

A text equivalent to the node type.