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
List
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.
Modifier and Type | Class and Description |
---|---|
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 and Description |
---|
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
|
Modifier and Type | Method and Description |
---|---|
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.lang.String urlPath,
boolean isValidating,
java.lang.String schemaUrl)
Generate an XmlDataAdaptor from a urlPath, given dtd validating option, and given schemaUrl
|
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.List<DataAdaptor> |
childAdaptors()
Create a list of child adaptors (one adaptor for each non-null child node).
|
java.util.List<DataAdaptor> |
childAdaptors(java.lang.String label)
Create 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[] |
doubleArray(java.lang.String attribute)
Returns the value of an attribute as an array of doubles.
|
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
|
protected static javax.xml.parsers.DocumentBuilder |
newDocumentBuilder(boolean isValidating,
java.net.URL schemaUrl)
Create a new document builder with the given DTD validation, and schemaUrl
|
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,
double[] array)
Stores the value of the given
double[] object in the data adaptor backing store. |
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<? extends DataListener> nodes)
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
|
public XmlDataAdaptor(org.w3c.dom.Node newNode)
public XmlDataAdaptor(org.w3c.dom.Document newDocument)
public java.lang.String name()
name
in interface DataAdaptor
public org.w3c.dom.Document document()
public boolean hasAttribute(java.lang.String attribute)
hasAttribute
in interface DataAdaptor
protected final java.lang.String rawValue(java.lang.String attribute)
attribute
- The node attribute.public java.lang.String stringValue(java.lang.String attribute)
stringValue
in interface DataAdaptor
attribute
- The node attribute.public double doubleValue(java.lang.String attribute) throws java.lang.NumberFormatException
doubleValue
in interface DataAdaptor
java.lang.NumberFormatException
public long longValue(java.lang.String attribute) throws java.lang.NumberFormatException
longValue
in interface DataAdaptor
java.lang.NumberFormatException
public int intValue(java.lang.String attribute) throws java.lang.NumberFormatException
intValue
in interface DataAdaptor
java.lang.NumberFormatException
public boolean booleanValue(java.lang.String attribute) throws java.lang.NumberFormatException
booleanValue
in interface DataAdaptor
java.lang.NumberFormatException
public double[] doubleArray(java.lang.String attribute) throws java.lang.NumberFormatException
doubleArray
in interface DataAdaptor
attribute
- the attribute namenull
value is returned if the value string is empty.java.lang.NumberFormatException
protected final void setRawValue(java.lang.String attribute, java.lang.String value)
attribute
- The node attribute.value
- The string value to associate with the attribute.public void setValue(java.lang.String attribute, java.lang.String value)
setValue
in interface DataAdaptor
attribute
- The node attribute.value
- The string value to associate with the attribute.public void setValue(java.lang.String attribute, double doubleValue)
setValue
in interface DataAdaptor
public void setValue(java.lang.String attribute, long longValue)
setValue
in interface DataAdaptor
public void setValue(java.lang.String attribute, int intValue)
setValue
in interface DataAdaptor
public void setValue(java.lang.String attribute, boolean boolValue)
setValue
in interface DataAdaptor
public void setValue(java.lang.String attribute, java.lang.Object value)
setValue
in interface DataAdaptor
public void setValue(java.lang.String attribute, double[] array)
double[]
object in the data adaptor backing store.setValue
in interface DataAdaptor
attribute
- attribute namearray
- attribute valuepublic java.lang.String[] attributes()
attributes
in interface DataAdaptor
public int nodeCount()
public int rawNodeCount()
public java.util.List<DataAdaptor> childAdaptors()
childAdaptors
in interface DataAdaptor
public java.util.List<DataAdaptor> childAdaptors(java.lang.String label)
childAdaptors
in interface DataAdaptor
label
- the label for which to match the node's tagpublic DataAdaptor childAdaptor(java.lang.String label)
childAdaptor
in interface DataAdaptor
label
- the label which identifies the tag of the nodes to fetchpublic DataAdaptor createChild(java.lang.String tagName)
createChild
in interface DataAdaptor
public void writeNode(DataListener listener)
writeNode
in interface DataAdaptor
public void writeNodes(java.util.Collection<? extends DataListener> nodes)
writeNodes
in interface DataAdaptor
nodes
- the nodes to writepublic void writeToUrlSpec(java.lang.String urlSpec) throws XmlDataAdaptor.WriteException
XmlDataAdaptor.WriteException
public void writeToUrl(java.net.URL url) throws XmlDataAdaptor.WriteException
XmlDataAdaptor.WriteException
public void writeTo(java.io.Writer writer)
public void writeTo(java.io.File file) throws java.io.IOException
java.io.IOException
public static XmlDataAdaptor adaptorForUrl(java.lang.String urlPath, boolean isValidating) throws XmlDataAdaptor.ParseException, XmlDataAdaptor.ResourceNotFoundException
public static XmlDataAdaptor adaptorForUrl(java.lang.String urlPath, boolean isValidating, java.lang.String schemaUrl) throws XmlDataAdaptor.ParseException, XmlDataAdaptor.ResourceNotFoundException
public static XmlDataAdaptor adaptorForUrl(java.net.URL url, boolean isValidating) throws XmlDataAdaptor.ParseException, XmlDataAdaptor.ResourceNotFoundException
public static XmlDataAdaptor adaptorForFile(java.io.File file, boolean isValidating) throws java.net.MalformedURLException, XmlDataAdaptor.ParseException, XmlDataAdaptor.ResourceNotFoundException
java.net.MalformedURLException
XmlDataAdaptor.ParseException
XmlDataAdaptor.ResourceNotFoundException
public static XmlDataAdaptor adaptorForString(java.lang.String source, boolean isValidating) throws XmlDataAdaptor.ParseException, XmlDataAdaptor.ResourceNotFoundException
protected static javax.xml.parsers.DocumentBuilder newDocumentBuilder(boolean isValidating) throws java.lang.Exception
java.lang.Exception
protected static javax.xml.parsers.DocumentBuilder newDocumentBuilder(boolean isValidating, java.net.URL schemaUrl) throws java.lang.Exception
java.lang.Exception
public static XmlDataAdaptor newDocumentAdaptor(DataListener dataHandler, java.lang.String dtdUri) throws XmlDataAdaptor.CreationException
XmlDataAdaptor.CreationException
public static XmlDataAdaptor newEmptyDocumentAdaptor(java.lang.String docTag, java.lang.String dtdURI)
public static XmlDataAdaptor newEmptyDocumentAdaptor()