public class XMLBuilder extends Object
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.
Modifier | Constructor and Description |
---|---|
protected |
XMLBuilder(Document xmlDocument)
Construct a new builder object that wraps the given XML document.
|
protected |
XMLBuilder(Node myNode,
Node parentNode)
Construct a new builder object that wraps the given XML document and node.
|
Modifier and Type | Method and Description |
---|---|
XMLBuilder |
a(String name,
String value)
Synonym for
attribute(String, String) . |
protected void |
assertElementHasNoTextNodes(Node anXmlElement) |
String |
asString()
Serialize the XML document to a string excluding the XML declaration.
|
String |
asString(Properties outputProperties)
Serialize the XML document to a string by delegating to the
toWriter(Writer, Properties) method. |
XMLBuilder |
attr(String name,
String value)
Synonym for
attribute(String, String) . |
XMLBuilder |
attribute(String name,
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).
|
NamespaceContextImpl |
buildDocumentNamespaceContext() |
XMLBuilder |
c(String comment)
Synonym for
comment(String) . |
XMLBuilder |
cdata(byte[] data)
Add a CDATA node with Base64-encoded byte data content 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 |
cdata(String data)
Add a CDATA node with String content 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(String comment)
Synonym for
comment(String) . |
XMLBuilder |
comment(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(String name)
Construct a builder for new XML document.
|
static XMLBuilder |
create(String name,
String namespaceURI)
Construct a builder for new XML document with a default namespace.
|
XMLBuilder |
d(byte[] data)
Synonym for
cdata(byte[]) . |
XMLBuilder |
d(String data)
Synonym for
cdata(String) . |
XMLBuilder |
data(byte[] data)
Synonym for
cdata(byte[]) . |
XMLBuilder |
data(String data)
Synonym for
cdata(String) . |
XMLBuilder |
document()
BEWARE: The builder returned by this method respresents a Document node, not
an Element node as is usually the case, so attempts to use the attribute or
namespace methods on this builder will likely fail.
|
XMLBuilder |
e(String name)
Synonym for
element(String) . |
XMLBuilder |
elem(String name)
Synonym for
element(String) . |
XMLBuilder |
element(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.
|
XMLBuilder |
element(String name,
String namespaceURI)
Add a named and namespaced XML element to the document as a child of
this builder node, and return the builder node representing the new child.
|
String |
elementAsString()
Serialize the current XML Element and its descendants to a string
excluding the XML declaration.
|
String |
elementAsString(Properties outputProperties)
Serialize the current XML Element and its descendants to a string by
delegating to the
toWriter(Writer, Properties) method. |
XMLBuilder |
elementBefore(String name)
Add a named XML element to the document as a sibling element
that precedes the position of this builder node, and return the builder node
representing the new child.
|
XMLBuilder |
elementBefore(String name,
String namespaceURI)
Add a named and namespaced XML element to the document as a sibling element
that precedes the position of this builder node, and return the builder node
representing the new child.
|
boolean |
equals(Object obj) |
Document |
getDocument() |
Element |
getElement() |
protected String |
getPrefixFromQualifiedName(String qualifiedName) |
XMLBuilder |
i(String target,
String data)
Synonym for
instruction(String, String) . |
XMLBuilder |
importXMLBuilder(XMLBuilder builder)
Imports another XMLBuilder document into this document at the
current position.
|
XMLBuilder |
insertInstruction(String target,
String data)
Insert an instruction before the element represented by this builder node, and
return the node representing that same element
(not the new instruction node).
|
XMLBuilder |
inst(String target,
String data)
Synonym for
instruction(String, String) . |
XMLBuilder |
instruction(String target,
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).
|
XMLBuilder |
namespace(String namespaceURI)
Add an XML namespace attribute to this builder's element node
without a prefix.
|
XMLBuilder |
namespace(String prefix,
String namespaceURI)
Add an XML namespace attribute to this builder's element node.
|
XMLBuilder |
ns(String namespaceURI)
Synonym for
namespace(String) . |
XMLBuilder |
ns(String prefix,
String namespaceURI)
Synonym for
namespace(String, String) . |
static XMLBuilder |
parse(InputSource inputSource)
Construct a builder from an existing XML document.
|
XMLBuilder |
r(String name)
Synonym for
reference(String) . |
XMLBuilder |
ref(String name)
Synonym for
reference(String) . |
XMLBuilder |
reference(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(String value)
Synonym for
text(String) . |
XMLBuilder |
text(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).
|
XMLBuilder |
text(String value,
boolean replaceText)
Add or replace the text value of an 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(boolean wholeDocument,
Writer writer,
Properties outputProperties)
Serialize either the specific Element wrapped by this XMLBuilder, or its entire
XML document, to the given writer using the default
TransformerFactory
and Transformer classes. |
void |
toWriter(Writer writer,
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(String xpath)
Find the first element in the builder's DOM matching the given
XPath expression.
|
XMLBuilder |
xpathFind(String xpath,
NamespaceContext nsContext)
Find the first element in the builder's DOM matching the given
XPath expression, where the expression may include namespaces if
a
NamespaceContext is provided. |
Object |
xpathQuery(String xpath,
QName type)
Return the result of evaluating an XPath query on the builder's DOM.
|
Object |
xpathQuery(String xpath,
QName type,
NamespaceContext nsContext)
Return the result of evaluating an XPath query on the builder's DOM
using the given namespace.
|
protected XMLBuilder(Document xmlDocument)
xmlDocument
- an XML document that the builder will manage and manipulate.protected XMLBuilder(Node myNode, Node parentNode)
myNode
- the XML node that this builder node will wrap. This node may
be part of the XML document, or it may be a new element that is to be
added to the document.parentNode
- If not null, the given myElement will be appended as child node of the
parentNode node.public static XMLBuilder create(String name, String namespaceURI) throws ParserConfigurationException, FactoryConfigurationError
name
- the name of the document's root element.namespaceURI
- default namespace URI for document, ignored if null or empty.FactoryConfigurationError
ParserConfigurationException
public static XMLBuilder create(String name) throws ParserConfigurationException, FactoryConfigurationError
name
- the name of the document's root element.FactoryConfigurationError
ParserConfigurationException
public static XMLBuilder parse(InputSource inputSource) throws ParserConfigurationException, SAXException, IOException
inputSource
- an XML document input source that will be parsed into a DOM.ParserConfigurationException
FactoryConfigurationError
ParserConfigurationException
IOException
SAXException
public XMLBuilder importXMLBuilder(XMLBuilder builder)
builder
- the XMLBuilder document to be imported.public boolean equals(Object obj)
public Element getElement()
public XMLBuilder document()
public XMLBuilder root()
create(String)
or parse(InputSource)
method.public Document getDocument()
public Object xpathQuery(String xpath, QName type, NamespaceContext nsContext) throws XPathExpressionException
xpath
- an XPath expressiontype
- the type the XPath is expected to resolve to, e.g:
XPathConstants.NODE
, XPathConstants.NODESET
,
XPathConstants.STRING
.nsContext
- a mapping of prefixes to namespace URIs that allows the XPath expression
to use namespaces, or null for a non-namespaced document.XPathExpressionException
- If the XPath is invalid, or if does not resolve to at least one
Node.ELEMENT_NODE
.public Object xpathQuery(String xpath, QName type) throws XPathExpressionException
xpath
- an XPath expressiontype
- the type the XPath is expected to resolve to, e.g:
XPathConstants.NODE
, XPathConstants.NODESET
,
XPathConstants.STRING
XPathExpressionException
- If the XPath is invalid, or if does not resolve to at least one
Node.ELEMENT_NODE
.public XMLBuilder xpathFind(String xpath, NamespaceContext nsContext) throws XPathExpressionException
NamespaceContext
is provided.xpath
- An XPath expression that *must* resolve to an existing Element within
the document object model.nsContext
- a mapping of prefixes to namespace URIs that allows the XPath expression
to use namespaces.XPathExpressionException
- If the XPath is invalid, or if does not resolve to at least one
Node.ELEMENT_NODE
.public XMLBuilder xpathFind(String xpath) throws XPathExpressionException
xpath
- An XPath expression that *must* resolve to an existing Element within
the document object model.XPathExpressionException
- If the XPath is invalid, or if does not resolve to at least one
Node.ELEMENT_NODE
.public XMLBuilder element(String name)
name
- the name of the XML element.IllegalStateException
- if you attempt to add a child element to an XML node that already
contains a text node value.public XMLBuilder elem(String name)
element(String)
.name
- the name of the XML element.IllegalStateException
- if you attempt to add a child element to an XML node that already
contains a text node value.public XMLBuilder e(String name)
element(String)
.name
- the name of the XML element.IllegalStateException
- if you attempt to add a child element to an XML node that already
contains a text node value.public XMLBuilder element(String name, String namespaceURI)
name
- the name of the XML element.namespaceURI
- a namespace URIIllegalStateException
- if you attempt to add a child element to an XML node that already
contains a text node value.public XMLBuilder elementBefore(String name)
name
- the name of the XML element.IllegalStateException
- if you attempt to add a sibling element to a node where there are already
one or more siblings that are text nodes.public XMLBuilder elementBefore(String name, String namespaceURI)
name
- the name of the XML element.namespaceURI
- a namespace URIIllegalStateException
- if you attempt to add a sibling element to a node where there are already
one or more siblings that are text nodes.public XMLBuilder attribute(String name, String value)
name
- the attribute's name.value
- the attribute's value.public XMLBuilder attr(String name, String value)
attribute(String, String)
.name
- the attribute's name.value
- the attribute's value.public XMLBuilder a(String name, String value)
attribute(String, String)
.name
- the attribute's name.value
- the attribute's value.public XMLBuilder text(String value, boolean replaceText)
value
- the text value to set or add to the element.replaceText
- if True any existing text content of the node is replaced with the
given text value, if the given value is appended to any existing text.public XMLBuilder text(String value)
value
- the text value to add to the element.public XMLBuilder t(String value)
text(String)
.value
- the text value to add to the element.public XMLBuilder cdata(String data)
data
- the String value that will be added to a CDATA element.public XMLBuilder data(String data)
cdata(String)
.data
- the String value that will be added to a CDATA element.public XMLBuilder d(String data)
cdata(String)
.data
- the String value that will be added to a CDATA 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(byte[])
.data
- the data value that will be Base64-encoded and added to a CDATA element.public XMLBuilder d(byte[] data)
cdata(byte[])
.data
- the data value that will be Base64-encoded and added to a CDATA element.public XMLBuilder comment(String comment)
comment
- the comment to add to the element.public XMLBuilder cmnt(String comment)
comment(String)
.comment
- the comment to add to the element.public XMLBuilder c(String comment)
comment(String)
.comment
- the comment to add to the element.public XMLBuilder instruction(String target, String data)
target
- the target value for the instruction.data
- the data value for the instructionpublic XMLBuilder inst(String target, String data)
instruction(String, String)
.target
- the target value for the instruction.data
- the data value for the instructionpublic XMLBuilder i(String target, String data)
instruction(String, String)
.target
- the target value for the instruction.data
- the data value for the instructionpublic XMLBuilder insertInstruction(String target, String data)
target
- the target value for the instruction.data
- the data value for the instructionpublic XMLBuilder reference(String name)
name
- the name value for the reference.public XMLBuilder ref(String name)
reference(String)
.name
- the name value for the reference.public XMLBuilder r(String name)
reference(String)
.name
- the name value for the reference.public XMLBuilder namespace(String prefix, String namespaceURI)
prefix
- a prefix for the namespace URI within the document, may be null
or empty in which case a default "xmlns" attribute is created.namespaceURI
- a namespace uripublic XMLBuilder ns(String prefix, String namespaceURI)
namespace(String, String)
.prefix
- a prefix for the namespace URI within the document, may be null
or empty in which case a default xmlns attribute is created.namespaceURI
- a namespace uripublic XMLBuilder namespace(String namespaceURI)
namespaceURI
- a namespace uripublic XMLBuilder ns(String namespaceURI)
namespace(String)
.namespaceURI
- a namespace uripublic 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 assertElementHasNoTextNodes(Node anXmlElement)
IllegalStateException
- if the current element contains any child text nodes.public void toWriter(boolean wholeDocument, Writer writer, Properties outputProperties) throws TransformerException
TransformerFactory
and Transformer
classes.
If output options are provided, these options are provided to the
Transformer
serializer.wholeDocument
- if true the whole XML document (i.e. the document root) is serialized,
if false just the current Element and its descendants are serialized.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.TransformerException
public void toWriter(Writer writer, Properties outputProperties) throws 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.TransformerException
public String asString(Properties outputProperties) throws 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.TransformerException
public String elementAsString(Properties outputProperties) throws 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.TransformerException
public String asString() throws TransformerException
TransformerException
public String elementAsString() throws TransformerException
TransformerException
public NamespaceContextImpl buildDocumentNamespaceContext()
Copyright © 2013. All Rights Reserved.