|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.jamesmurty.utils.XMLBuilder
public class XMLBuilder
XML Builder is a utility that creates simple XML documents using relatively sparse Java code. It is intended to allow for quick and painless creation of XML documents where you might otherwise be tempted to use concatenated strings, rather than face the tedium and verbosity of coding with JAXP (http://jaxp.dev.java.net/).
Internally, XML Builder uses JAXP to build a standard W3C
Document
model (DOM) that you can easily export as a
string, or access and manipulate further if you have special requirements.
The XMLBuilder class serves as a wrapper of Element
nodes,
and provides a number of utility methods that make it simple to
manipulate the underlying element and the document to which it belongs.
In essence, this class performs dual roles: it represents a specific XML
node, and also allows manipulation of the entire underlying XML document.
The platform's default DocumentBuilderFactory
and
DocumentBuilder
classes are used to build the document.
Constructor Summary | |
---|---|
protected |
XMLBuilder(org.w3c.dom.Document xmlDocument)
Construct a new builder object that wraps the given XML document. |
protected |
XMLBuilder(org.w3c.dom.Element myElement,
org.w3c.dom.Element parentElement)
Construct a new builder object that wraps the given XML document and element element. |
Method Summary | |
---|---|
XMLBuilder |
a(java.lang.String name,
java.lang.String value)
Synonym for attribute(String, String) . |
protected void |
assertCurrentElementHasNoTextNodes()
|
java.lang.String |
asString()
Serialize the XML document to a string excluding the XML declaration. |
java.lang.String |
asString(java.util.Properties outputProperties)
Serialize the XML document to a string by delegating to the toWriter(Writer, Properties) method. |
XMLBuilder |
attr(java.lang.String name,
java.lang.String value)
Synonym for attribute(String, String) . |
XMLBuilder |
attribute(java.lang.String name,
java.lang.String value)
Add a named attribute value to the element represented by this builder node, and return the node representing the element to which the attribute was added (not the new attribute node). |
XMLBuilder |
c(java.lang.String comment)
Synonym for comment(String) . |
XMLBuilder |
cdata(byte[] data)
Add a CDATA value to the element represented by this builder node, and return the node representing the element to which the data was added (not the new CDATA node). |
XMLBuilder |
cmnt(java.lang.String comment)
Synonym for comment(String) . |
XMLBuilder |
comment(java.lang.String comment)
Add a comment to the element represented by this builder node, and return the node representing the element to which the comment was added (not the new comment node). |
static XMLBuilder |
create(java.lang.String name)
Construct a builder for new XML document. |
XMLBuilder |
d(byte[] data)
Synonym for #cdata(String) . |
XMLBuilder |
data(byte[] data)
Synonym for #cdata(String) . |
XMLBuilder |
e(java.lang.String name)
Synonym for element(String) . |
XMLBuilder |
elem(java.lang.String name)
Synonym for element(String) . |
XMLBuilder |
element(java.lang.String name)
Add a named XML element to the document as a child of this builder node, and return the builder node representing the new child. |
boolean |
equals(java.lang.Object obj)
|
org.w3c.dom.Document |
getDocument()
|
org.w3c.dom.Element |
getElement()
|
XMLBuilder |
i(java.lang.String target,
java.lang.String data)
Synonym for instruction(String, String) . |
XMLBuilder |
importXMLBuilder(XMLBuilder builder)
Imports another XMLBuilder document into this document at the current position. |
XMLBuilder |
inst(java.lang.String target,
java.lang.String data)
Synonym for instruction(String, String) . |
XMLBuilder |
instruction(java.lang.String target,
java.lang.String data)
Add an instruction to the element represented by this builder node, and return the node representing the element to which the instruction was added (not the new instruction node). |
static XMLBuilder |
parse(org.xml.sax.InputSource inputSource)
Construct a builder from an existing XML document. |
XMLBuilder |
r(java.lang.String name)
Synonym for reference(String) . |
XMLBuilder |
ref(java.lang.String name)
Synonym for reference(String) . |
XMLBuilder |
reference(java.lang.String name)
Add a reference to the element represented by this builder node, and return the node representing the element to which the reference was added (not the new reference node). |
XMLBuilder |
root()
|
XMLBuilder |
t(java.lang.String value)
Synonmy for text(String) . |
XMLBuilder |
text(java.lang.String value)
Add a text value to the element represented by this builder node, and return the node representing the element to which the text was added (not the new text node). |
void |
toWriter(java.io.Writer writer,
java.util.Properties outputProperties)
Serialize the XML document to the given writer using the default TransformerFactory and Transformer classes. |
XMLBuilder |
up()
Return the builder node representing the parent of the current node. |
XMLBuilder |
up(int steps)
Return the builder node representing the nth ancestor element of this node, or the root node if n exceeds the document's depth. |
XMLBuilder |
xpathFind(java.lang.String xpath)
Find the first element in the builder's DOM matching the given XPath expression. |
Methods inherited from class java.lang.Object |
---|
clone, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Constructor Detail |
---|
protected XMLBuilder(org.w3c.dom.Document xmlDocument)
xmlDocument
- an XML document that the builder will manage and manipulate.protected XMLBuilder(org.w3c.dom.Element myElement, org.w3c.dom.Element parentElement)
myElement
- the XML element that this builder node will wrap. This element may
be part of the XML document, or it may be a new element that is to be
added to the document.parentElement
- If not null, the given myElement will be appended as child node of the
parentElement node.Method Detail |
---|
public static XMLBuilder create(java.lang.String name) throws javax.xml.parsers.ParserConfigurationException, javax.xml.parsers.FactoryConfigurationError
name
- the name of the document's root element.
javax.xml.parsers.FactoryConfigurationError
javax.xml.parsers.ParserConfigurationException
public static XMLBuilder parse(org.xml.sax.InputSource inputSource) throws javax.xml.parsers.ParserConfigurationException, org.xml.sax.SAXException, java.io.IOException
inputSource
- an XML document input source that will be parsed into a DOM.
javax.xml.parsers.ParserConfigurationException
javax.xml.parsers.FactoryConfigurationError
javax.xml.parsers.ParserConfigurationException
java.io.IOException
org.xml.sax.SAXException
public XMLBuilder importXMLBuilder(XMLBuilder builder)
builder
- the XMLBuilder document to be imported.
public boolean equals(java.lang.Object obj)
equals
in class java.lang.Object
public org.w3c.dom.Element getElement()
public XMLBuilder root()
create(String)
or parse(InputSource)
method.public org.w3c.dom.Document getDocument()
public XMLBuilder xpathFind(java.lang.String xpath) throws javax.xml.xpath.XPathExpressionException
xpath
- An XPath expression that *must* resolve to an existing Element within
the document object model.
javax.xml.xpath.XPathExpressionException
- If the XPath is invalid, or if does not resolve to at least one
Node.ELEMENT_NODE
.public XMLBuilder element(java.lang.String name)
name
- the name of the XML element.
java.lang.IllegalStateException
- if you attempt to add a child element to an XML node that already
contains a text node value.public XMLBuilder elem(java.lang.String name)
element(String)
.
name
- the name of the XML element.
java.lang.IllegalStateException
- if you attempt to add a child element to an XML node that already
contains a text node value.public XMLBuilder e(java.lang.String name)
element(String)
.
name
- the name of the XML element.
java.lang.IllegalStateException
- if you attempt to add a child element to an XML node that already
contains a text node value.public XMLBuilder attribute(java.lang.String name, java.lang.String value)
name
- the attribute's name.value
- the attribute's value.
public XMLBuilder attr(java.lang.String name, java.lang.String value)
attribute(String, String)
.
name
- the attribute's name.value
- the attribute's value.
public XMLBuilder a(java.lang.String name, java.lang.String value)
attribute(String, String)
.
name
- the attribute's name.value
- the attribute's value.
public XMLBuilder text(java.lang.String value)
value
- the text value to add to the element.
public XMLBuilder t(java.lang.String value)
text(String)
.
value
- the text value to add to the element.
public XMLBuilder cdata(byte[] data)
data
- the data value that will be Base64-encoded and added to a CDATA element.
public XMLBuilder data(byte[] data)
#cdata(String)
.
data
- the data value to add to the element.
public XMLBuilder d(byte[] data)
#cdata(String)
.
data
- the data value to add to the element.
public XMLBuilder comment(java.lang.String comment)
comment
- the comment to add to the element.
public XMLBuilder cmnt(java.lang.String comment)
comment(String)
.
comment
- the comment to add to the element.
public XMLBuilder c(java.lang.String comment)
comment(String)
.
comment
- the comment to add to the element.
public XMLBuilder instruction(java.lang.String target, java.lang.String data)
target
- the target value for the instruction.data
- the data value for the instruction
public XMLBuilder inst(java.lang.String target, java.lang.String data)
instruction(String, String)
.
target
- the target value for the instruction.data
- the data value for the instruction
public XMLBuilder i(java.lang.String target, java.lang.String data)
instruction(String, String)
.
target
- the target value for the instruction.data
- the data value for the instruction
public XMLBuilder reference(java.lang.String name)
name
- the name value for the reference.
public XMLBuilder ref(java.lang.String name)
reference(String)
.
name
- the name value for the reference.
public XMLBuilder r(java.lang.String name)
reference(String)
.
name
- the name value for the reference.
public XMLBuilder up(int steps)
steps
- the number of parent elements to step over while navigating up the chain
of node ancestors. A steps value of 1 will find a node's parent, 2 will
find its grandparent etc.
public XMLBuilder up()
protected void assertCurrentElementHasNoTextNodes()
java.lang.IllegalStateException
- if the current element contains any child text nodes.public void toWriter(java.io.Writer writer, java.util.Properties outputProperties) throws javax.xml.transform.TransformerException
TransformerFactory
and Transformer
classes. If output
options are provided, these options are provided to the
Transformer
serializer.
writer
- a writer to which the serialized document is written.outputProperties
- settings for the Transformer
serializer. This parameter may be
null or an empty Properties object, in which case the default output
properties will be applied.
javax.xml.transform.TransformerException
public java.lang.String asString(java.util.Properties outputProperties) throws javax.xml.transform.TransformerException
toWriter(Writer, Properties)
method. If output options are
provided, these options are provided to the Transformer
serializer.
outputProperties
- settings for the Transformer
serializer. This parameter may be
null or an empty Properties object, in which case the default output
properties will be applied.
javax.xml.transform.TransformerException
public java.lang.String asString() throws javax.xml.transform.TransformerException
javax.xml.transform.TransformerException
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |