gov.sns.tools.xml
Class XmlDataAdaptor

java.lang.Object
  |
  +--gov.sns.tools.xml.XmlDataAdaptor

All Implemented Interfaces:

DataAdaptor

public class XmlDataAdaptor

extends java.lang.Object

implements DataAdaptor

XmlDataAdaptor is a DataAdaptor that specifically supports (reading/writing) (from/to) XML. While the DataAdaptor provides methods for getting and setting properties of nodes and getting and setting nodes in a tree of data, XmlDataAdaptor uses an XML backing store for the data. In particular, you can use the methods of DataAdaptor for all data manipulation. You need to specifically use XmlDataAdaptor when creating a new document, writing an XML document to a file or loading an XML document from a file. To create a new, empty XML document simply invoke: document_adaptor = XmlDataAdaptor.newEmptyDocumentAdaptor(); You can populate the document by adding child nodes. You can only add a single node to the top document node, but otherwise you can add and nest as many nodes as needed. Each such node is returned as a DataAdaptor. For example, to add a node to the top document node, invoke: childAdaptor = document_adaptor.createChild("nodeName") You can set attributes of nodes with some basic types such as boolean, integer, double and string where you supply the name of the attribute and the value. If you add an Object as a value, then toString() is invoked to fetch the value as a string. Some examples: adaptor.setValue("attribute", "some string"); adaptor.setValue("attr2", 3.14); You can write an XML document to a URL, a file or generally to a java.io.Writer. For example, to write an XML document to a file invoke: document_adaptor.writeTo( new File("file_path") ); You can read an XML document from a string of XML text, a URL or a file. You may specify whether or not to use DTD validation. For example, to read an XML document from a file invoke: document_adaptor = XmlDataAdaptor.adaptorForFile( new File("file_path"), false ); You can fetch named child nodes from a parent node. Some examples are: List xAdaptors = parentAdaptor.childAdaptors("X") List allAdaptors = parentAdaptor.childAdaptors() DataAdaptor yAdaptor = parentAdaptor.childAdaptor("Y") You can test if a node defines an attribute: boolean status = adaptor.hasAttribute("attribute"); You can read the value of an attribute: double value = adaptor.doubleValue("attr2"); There are several more methods available for DataAdaptor and XmlDataAdaptor, but the examples listed above should provide an overview and foundation.

Nested Class Summary

static class	XmlDataAdaptor.CreationException
static class	XmlDataAdaptor.ParseException
static class	XmlDataAdaptor.ResourceNotFoundException
static class	XmlDataAdaptor.WriteException Wrapper for exceptions that may be thrown while writing: java.io.IOException java.net.MalformedURLException

Constructor Summary

XmlDataAdaptor(org.w3c.dom.Document newDocument)
Creates a new XmlDataAdaptor from an XML Document

XmlDataAdaptor(org.w3c.dom.Node newNode)
Creates a new XmlDataAdaptor from an XML Node

Method Summary

static XmlDataAdaptor	adaptorForFile(java.io.File file, boolean isValidating) Generate an XmlDataAdaptor from a urlPath and given dtd validating option
static XmlDataAdaptor	adaptorForString(java.lang.String source, boolean isValidating) Generate an XmlDataAdaptor from an XML string and given dtd validating option
static XmlDataAdaptor	adaptorForUrl(java.lang.String urlPath, boolean isValidating) Generate an XmlDataAdaptor from a urlPath and given dtd validating option
static XmlDataAdaptor	adaptorForUrl(java.net.URL url, boolean isValidating) Generate an XmlDataAdaptor from a urlPath and given dtd validating option
java.lang.String[]	attributes() return an array of attribute names
boolean	booleanValue(java.lang.String attribute) return the boolean value associated with the attribute
DataAdaptor	childAdaptor(java.lang.String label) Convenience method to get a single child adaptor when only one is expected
java.util.Iterator	childAdaptorIterator() return an iterator for a list of child adaptors (one adaptor for each non-null child node).
java.util.Iterator	childAdaptorIterator(java.lang.String label) return an iterator for a list of child adaptors (one adaptor for each non-null child node whose tag equals the specified label).
java.util.List	childAdaptors() return a list of child adaptors (one adaptor for each non-null child node).
java.util.List	childAdaptors(java.lang.String label) return a list of child adaptors (one adaptor for each non-null child node whose tag name is equal to the specified label).
DataAdaptor	createChild(java.lang.String tagName) Create a new offspring DataAdaptor given the tagName
org.w3c.dom.Document	document() get the document associated with this XML adaptor
double	doubleValue(java.lang.String attribute) return the double value associated with the attribute
boolean	hasAttribute(java.lang.String attribute) check whether the main node has the specified attribute
int	intValue(java.lang.String attribute) return the integer value associated with the attribute
long	longValue(java.lang.String attribute) return the long value associated with the attribute
java.lang.String	name() get the tag name for the main node
static XmlDataAdaptor	newDocumentAdaptor(DataListener dataHandler, java.lang.String dtdUri) Create a new XmlDataAdaptor given a DataListener and a dtd URI
protected static javax.xml.parsers.DocumentBuilder	newDocumentBuilder(boolean isValidating) Create a new document builder with the given DTD validation
static XmlDataAdaptor	newEmptyDocumentAdaptor() Create an empty XML document
static XmlDataAdaptor	newEmptyDocumentAdaptor(java.lang.String docTag, java.lang.String dtdURI) Create an XML document with only the doc tag and DTD URI specified
int	nodeCount() return the count of non-null child nodes
int	rawNodeCount() return the count of all child nodes (including null child nodes)
protected java.lang.String	rawValue(java.lang.String attribute) Get the string value associated with the specified attribute allowing DOM to recover escaped characters as necessary.
protected void	setRawValue(java.lang.String attribute, java.lang.String value) Set the string value to associate with the attribute and allow DOM to escape special characters as necessary.
void	setValue(java.lang.String attribute, boolean boolValue) set the boolean value to be associated with the attribute
void	setValue(java.lang.String attribute, double doubleValue) set the double value to be associated with the attribute
void	setValue(java.lang.String attribute, int intValue) set the integer value to be associated with the attribute
void	setValue(java.lang.String attribute, long longValue) set the long value to be associated with the attribute
void	setValue(java.lang.String attribute, java.lang.Object value) set the value of the specified attribute to the specified value
void	setValue(java.lang.String attribute, java.lang.String value) Set the string value to be associated with the attribute and replace illegal XML attribute characters (less than and ampersand) with their legal XML attribute substitutions.
java.lang.String	stringValue(java.lang.String attribute) Get the string value associated with the specified attribute.
void	writeNode(DataListener listener) append a node associated with the listener
void	writeNodes(java.util.Collection listenerList) append a node for each listener in the listener list
void	writeTo(java.io.File file) Convenience method for writing an XML file
void	writeTo(java.io.Writer writer) Write XML to the specified url
void	writeToUrl(java.net.URL url) Write XML to the specified url
void	writeToUrlSpec(java.lang.String urlSpec) Write XML to the specified url

Methods inherited from class java.lang.Object

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

Constructor Detail

XmlDataAdaptor

public XmlDataAdaptor(org.w3c.dom.Node newNode)

Creates a new XmlDataAdaptor from an XML Node

XmlDataAdaptor

public XmlDataAdaptor(org.w3c.dom.Document newDocument)

Creates a new XmlDataAdaptor from an XML Document

Method Detail

name

public java.lang.String name()

get the tag name for the main node

Specified by:

name in interface DataAdaptor

document

public org.w3c.dom.Document document()

get the document associated with this XML adaptor

hasAttribute

public boolean hasAttribute(java.lang.String attribute)

check whether the main node has the specified attribute

Specified by:

hasAttribute in interface DataAdaptor

rawValue

protected final java.lang.String rawValue(java.lang.String attribute)

Get the string value associated with the specified attribute allowing DOM to recover escaped characters as necessary.

Parameters:

attribute - The node attribute.

Returns:

the raw string value associated with the attribute or null if the attribute does not exist

stringValue

public java.lang.String stringValue(java.lang.String attribute)

Get the string value associated with the specified attribute.

Specified by:

stringValue in interface DataAdaptor

Parameters:

attribute - The node attribute.

Returns:

the raw string value associated with the attribute

doubleValue

public double doubleValue(java.lang.String attribute)
                   throws java.lang.NumberFormatException

return the double value associated with the attribute

Specified by:

doubleValue in interface DataAdaptor

java.lang.NumberFormatException

longValue

public long longValue(java.lang.String attribute)
               throws java.lang.NumberFormatException

return the long value associated with the attribute

Specified by:

longValue in interface DataAdaptor

java.lang.NumberFormatException

intValue

public int intValue(java.lang.String attribute)
             throws java.lang.NumberFormatException

return the integer value associated with the attribute

Specified by:

intValue in interface DataAdaptor

java.lang.NumberFormatException

booleanValue

public boolean booleanValue(java.lang.String attribute)
                     throws java.lang.NumberFormatException

return the boolean value associated with the attribute

Specified by:

booleanValue in interface DataAdaptor

java.lang.NumberFormatException

setRawValue

protected final void setRawValue(java.lang.String attribute,
                                 java.lang.String value)

Set the string value to associate with the attribute and allow DOM to escape special characters as necessary.

Parameters:

attribute - The node attribute.

value - The string value to associate with the attribute.

setValue

public void setValue(java.lang.String attribute,
                     java.lang.String value)

Set the string value to be associated with the attribute and replace illegal XML attribute characters (less than and ampersand) with their legal XML attribute substitutions.

Specified by:

setValue in interface DataAdaptor

Parameters:

attribute - The node attribute.

value - The string value to associate with the attribute.

setValue

public void setValue(java.lang.String attribute,
                     double doubleValue)

set the double value to be associated with the attribute

Specified by:

setValue in interface DataAdaptor

setValue

public void setValue(java.lang.String attribute,
                     long longValue)

set the long value to be associated with the attribute

Specified by:

setValue in interface DataAdaptor

setValue

public void setValue(java.lang.String attribute,
                     int intValue)

set the integer value to be associated with the attribute

Specified by:

setValue in interface DataAdaptor

setValue

public void setValue(java.lang.String attribute,
                     boolean boolValue)

set the boolean value to be associated with the attribute

Specified by:

setValue in interface DataAdaptor

setValue

public void setValue(java.lang.String attribute,
                     java.lang.Object value)

set the value of the specified attribute to the specified value

Specified by:

setValue in interface DataAdaptor

attributes

public java.lang.String[] attributes()

return an array of attribute names

Specified by:

attributes in interface DataAdaptor

nodeCount

public int nodeCount()

return the count of non-null child nodes

Specified by:

nodeCount in interface DataAdaptor

rawNodeCount

public int rawNodeCount()

return the count of all child nodes (including null child nodes)

childAdaptors

public java.util.List childAdaptors()

return a list of child adaptors (one adaptor for each non-null child node).

Specified by:

childAdaptors in interface DataAdaptor

childAdaptorIterator

public java.util.Iterator childAdaptorIterator()

return an iterator for a list of child adaptors (one adaptor for each non-null child node).

Specified by:

childAdaptorIterator in interface DataAdaptor

childAdaptors

public java.util.List childAdaptors(java.lang.String label)

return a list of child adaptors (one adaptor for each non-null child node whose tag name is equal to the specified label).

Specified by:

childAdaptors in interface DataAdaptor

childAdaptorIterator

public java.util.Iterator childAdaptorIterator(java.lang.String label)

return an iterator for a list of child adaptors (one adaptor for each non-null child node whose tag equals the specified label).

Specified by:

childAdaptorIterator in interface DataAdaptor

childAdaptor

public DataAdaptor childAdaptor(java.lang.String label)

Description copied from interface: DataAdaptor

Convenience method to get a single child adaptor when only one is expected

Specified by:

childAdaptor in interface DataAdaptor

createChild

public DataAdaptor createChild(java.lang.String tagName)

Create a new offspring DataAdaptor given the tagName

Specified by:

createChild in interface DataAdaptor

writeNode

public void writeNode(DataListener listener)

append a node associated with the listener

Specified by:

writeNode in interface DataAdaptor

writeNodes

public void writeNodes(java.util.Collection listenerList)

append a node for each listener in the listener list

Specified by:

writeNodes in interface DataAdaptor

writeToUrlSpec

public void writeToUrlSpec(java.lang.String urlSpec)
                    throws XmlDataAdaptor.WriteException

Write XML to the specified url

XmlDataAdaptor.WriteException

writeToUrl

public void writeToUrl(java.net.URL url)
                throws XmlDataAdaptor.WriteException

Write XML to the specified url

XmlDataAdaptor.WriteException

writeTo

public void writeTo(java.io.Writer writer)

Write XML to the specified url

writeTo

public void writeTo(java.io.File file)
             throws java.io.IOException

Convenience method for writing an XML file

java.io.IOException

adaptorForUrl

public static XmlDataAdaptor adaptorForUrl(java.lang.String urlPath,
                                           boolean isValidating)
                                    throws XmlDataAdaptor.ParseException,
                                           XmlDataAdaptor.ResourceNotFoundException

Generate an XmlDataAdaptor from a urlPath and given dtd validating option

XmlDataAdaptor.ParseException

XmlDataAdaptor.ResourceNotFoundException

adaptorForUrl

public static XmlDataAdaptor adaptorForUrl(java.net.URL url,
                                           boolean isValidating)
                                    throws XmlDataAdaptor.ParseException,
                                           XmlDataAdaptor.ResourceNotFoundException

Generate an XmlDataAdaptor from a urlPath and given dtd validating option

XmlDataAdaptor.ParseException

XmlDataAdaptor.ResourceNotFoundException

adaptorForFile

public static XmlDataAdaptor adaptorForFile(java.io.File file,
                                            boolean isValidating)
                                     throws java.net.MalformedURLException,
                                            XmlDataAdaptor.ParseException,
                                            XmlDataAdaptor.ResourceNotFoundException

Generate an XmlDataAdaptor from a urlPath and given dtd validating option

java.net.MalformedURLException

XmlDataAdaptor.ParseException

XmlDataAdaptor.ResourceNotFoundException

adaptorForString

public static XmlDataAdaptor adaptorForString(java.lang.String source,
                                              boolean isValidating)
                                       throws XmlDataAdaptor.ParseException,
                                              XmlDataAdaptor.ResourceNotFoundException

Generate an XmlDataAdaptor from an XML string and given dtd validating option

XmlDataAdaptor.ParseException

XmlDataAdaptor.ResourceNotFoundException

newDocumentBuilder

protected static javax.xml.parsers.DocumentBuilder newDocumentBuilder(boolean isValidating)
                                                               throws java.lang.Exception

Create a new document builder with the given DTD validation

java.lang.Exception

newDocumentAdaptor

public static XmlDataAdaptor newDocumentAdaptor(DataListener dataHandler,
                                                java.lang.String dtdUri)
                                         throws XmlDataAdaptor.CreationException

Create a new XmlDataAdaptor given a DataListener and a dtd URI

XmlDataAdaptor.CreationException

newEmptyDocumentAdaptor

public static XmlDataAdaptor newEmptyDocumentAdaptor(java.lang.String docTag,
                                                     java.lang.String dtdURI)

Create an XML document with only the doc tag and DTD URI specified

newEmptyDocumentAdaptor

public static XmlDataAdaptor newEmptyDocumentAdaptor()

Create an empty XML document