public final class XMLBuilder extends BaseXMLBuilder
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
BaseXMLBuilder.attribute(String, String) . |
XMLBuilder |
attr(String name,
String value)
Synonym for
BaseXMLBuilder.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).
|
XMLBuilder |
c(String comment)
Synonym for
BaseXMLBuilder.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
BaseXMLBuilder.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
BaseXMLBuilder.cdata(byte[]) . |
XMLBuilder |
d(String data)
Synonym for
BaseXMLBuilder.cdata(String) . |
XMLBuilder |
data(byte[] data)
Synonym for
BaseXMLBuilder.cdata(byte[]) . |
XMLBuilder |
data(String data)
Synonym for
BaseXMLBuilder.cdata(String) . |
XMLBuilder |
document()
BEWARE: The builder returned by this method represents 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
BaseXMLBuilder.element(String) . |
XMLBuilder |
elem(String name)
Synonym for
BaseXMLBuilder.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.
|
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.
|
XMLBuilder |
i(String target,
String data)
Synonym for
BaseXMLBuilder.instruction(String, String) . |
XMLBuilder |
importXMLBuilder(BaseXMLBuilder 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
BaseXMLBuilder.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
BaseXMLBuilder.namespace(String) . |
XMLBuilder |
ns(String prefix,
String namespaceURI)
Synonym for
BaseXMLBuilder.namespace(String, String) . |
static XMLBuilder |
parse(File xmlFile)
Construct a builder from an existing XML document file.
|
static XMLBuilder |
parse(InputSource inputSource)
Construct a builder from an existing XML document.
|
static XMLBuilder |
parse(String xmlString)
Construct a builder from an existing XML document string.
|
XMLBuilder |
r(String name)
Synonym for
BaseXMLBuilder.reference(String) . |
XMLBuilder |
ref(String name)
Synonym for
BaseXMLBuilder.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 |
stripWhitespaceOnlyTextNodes()
Find and delete from the underlying Document any text nodes that
contain nothing but whitespace, such as newlines and tab or space
characters used to indent or pretty-print an XML document.
|
XMLBuilder |
t(String value)
Synonym for
BaseXMLBuilder.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).
|
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. |
assertElementContainsNoOrWhitespaceOnlyTextNodes, asString, asString, attributeImpl, buildDocumentNamespaceContext, cdataImpl, cdataImpl, commentImpl, createDocumentImpl, elementAsString, elementAsString, elementBeforeImpl, elementBeforeImpl, elementImpl, equals, getDocument, getElement, getPrefixFromQualifiedName, importXMLBuilderImpl, insertInstructionImpl, instructionImpl, lookupNamespaceURIImpl, namespaceImpl, namespaceImpl, parseDocumentImpl, referenceImpl, stripWhitespaceOnlyTextNodesImpl, textImpl, toWriter, toWriter, upImpl, xpathFindImpl, xpathQuery, xpathQuery
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 static XMLBuilder parse(String xmlString) throws ParserConfigurationException, SAXException, IOException
xmlString
- an XML document string that will be parsed into a DOM.ParserConfigurationException
FactoryConfigurationError
ParserConfigurationException
IOException
SAXException
public static XMLBuilder parse(File xmlFile) throws ParserConfigurationException, SAXException, IOException
xmlFile
- an XML document file that will be parsed into a DOM.ParserConfigurationException
FactoryConfigurationError
ParserConfigurationException
IOException
SAXException
public XMLBuilder stripWhitespaceOnlyTextNodes() throws XPathExpressionException
BaseXMLBuilder
stripWhitespaceOnlyTextNodes
in class BaseXMLBuilder
XPathExpressionException
public XMLBuilder importXMLBuilder(BaseXMLBuilder builder)
BaseXMLBuilder
importXMLBuilder
in class BaseXMLBuilder
builder
- the XMLBuilder document to be imported.public XMLBuilder root()
root
in class BaseXMLBuilder
public XMLBuilder xpathFind(String xpath, NamespaceContext nsContext) throws XPathExpressionException
BaseXMLBuilder
NamespaceContext
is provided.xpathFind
in class BaseXMLBuilder
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
BaseXMLBuilder
xpathFind
in class BaseXMLBuilder
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)
BaseXMLBuilder
element
in class BaseXMLBuilder
name
- the name of the XML element.public XMLBuilder elem(String name)
BaseXMLBuilder
BaseXMLBuilder.element(String)
.elem
in class BaseXMLBuilder
name
- the name of the XML element.public XMLBuilder e(String name)
BaseXMLBuilder
BaseXMLBuilder.element(String)
.e
in class BaseXMLBuilder
name
- the name of the XML element.public XMLBuilder element(String name, String namespaceURI)
BaseXMLBuilder
element
in class BaseXMLBuilder
name
- the name of the XML element.namespaceURI
- a namespace URIpublic XMLBuilder elementBefore(String name)
BaseXMLBuilder
elementBefore
in class BaseXMLBuilder
name
- the name of the XML element.public XMLBuilder elementBefore(String name, String namespaceURI)
BaseXMLBuilder
elementBefore
in class BaseXMLBuilder
name
- the name of the XML element.namespaceURI
- a namespace URIpublic XMLBuilder attribute(String name, String value)
BaseXMLBuilder
attribute
in class BaseXMLBuilder
name
- the attribute's name.value
- the attribute's value.public XMLBuilder attr(String name, String value)
BaseXMLBuilder
BaseXMLBuilder.attribute(String, String)
.attr
in class BaseXMLBuilder
name
- the attribute's name.value
- the attribute's value.public XMLBuilder a(String name, String value)
BaseXMLBuilder
BaseXMLBuilder.attribute(String, String)
.a
in class BaseXMLBuilder
name
- the attribute's name.value
- the attribute's value.public XMLBuilder text(String value, boolean replaceText)
BaseXMLBuilder
text
in class BaseXMLBuilder
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)
BaseXMLBuilder
text
in class BaseXMLBuilder
value
- the text value to add to the element.public XMLBuilder t(String value)
BaseXMLBuilder
BaseXMLBuilder.text(String)
.t
in class BaseXMLBuilder
value
- the text value to add to the element.public XMLBuilder cdata(String data)
BaseXMLBuilder
cdata
in class BaseXMLBuilder
data
- the String value that will be added to a CDATA element.public XMLBuilder data(String data)
BaseXMLBuilder
BaseXMLBuilder.cdata(String)
.data
in class BaseXMLBuilder
data
- the String value that will be added to a CDATA element.public XMLBuilder d(String data)
BaseXMLBuilder
BaseXMLBuilder.cdata(String)
.d
in class BaseXMLBuilder
data
- the String value that will be added to a CDATA element.public XMLBuilder cdata(byte[] data)
BaseXMLBuilder
cdata
in class BaseXMLBuilder
data
- the data value that will be Base64-encoded and added to a CDATA element.public XMLBuilder data(byte[] data)
BaseXMLBuilder
BaseXMLBuilder.cdata(byte[])
.data
in class BaseXMLBuilder
data
- the data value that will be Base64-encoded and added to a CDATA element.public XMLBuilder d(byte[] data)
BaseXMLBuilder
BaseXMLBuilder.cdata(byte[])
.d
in class BaseXMLBuilder
data
- the data value that will be Base64-encoded and added to a CDATA element.public XMLBuilder comment(String comment)
BaseXMLBuilder
comment
in class BaseXMLBuilder
comment
- the comment to add to the element.public XMLBuilder cmnt(String comment)
BaseXMLBuilder
BaseXMLBuilder.comment(String)
.cmnt
in class BaseXMLBuilder
comment
- the comment to add to the element.public XMLBuilder c(String comment)
BaseXMLBuilder
BaseXMLBuilder.comment(String)
.c
in class BaseXMLBuilder
comment
- the comment to add to the element.public XMLBuilder instruction(String target, String data)
BaseXMLBuilder
instruction
in class BaseXMLBuilder
target
- the target value for the instruction.data
- the data value for the instructionpublic XMLBuilder inst(String target, String data)
BaseXMLBuilder
BaseXMLBuilder.instruction(String, String)
.inst
in class BaseXMLBuilder
target
- the target value for the instruction.data
- the data value for the instructionpublic XMLBuilder i(String target, String data)
BaseXMLBuilder
BaseXMLBuilder.instruction(String, String)
.i
in class BaseXMLBuilder
target
- the target value for the instruction.data
- the data value for the instructionpublic XMLBuilder insertInstruction(String target, String data)
BaseXMLBuilder
insertInstruction
in class BaseXMLBuilder
target
- the target value for the instruction.data
- the data value for the instructionpublic XMLBuilder reference(String name)
BaseXMLBuilder
reference
in class BaseXMLBuilder
name
- the name value for the reference.public XMLBuilder ref(String name)
BaseXMLBuilder
BaseXMLBuilder.reference(String)
.ref
in class BaseXMLBuilder
name
- the name value for the reference.public XMLBuilder r(String name)
BaseXMLBuilder
BaseXMLBuilder.reference(String)
.r
in class BaseXMLBuilder
name
- the name value for the reference.public XMLBuilder namespace(String prefix, String namespaceURI)
BaseXMLBuilder
namespace
in class BaseXMLBuilder
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)
BaseXMLBuilder
BaseXMLBuilder.namespace(String, String)
.ns
in class BaseXMLBuilder
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)
BaseXMLBuilder
namespace
in class BaseXMLBuilder
namespaceURI
- a namespace uripublic XMLBuilder ns(String namespaceURI)
BaseXMLBuilder
BaseXMLBuilder.namespace(String)
.ns
in class BaseXMLBuilder
namespaceURI
- a namespace uripublic XMLBuilder up(int steps)
BaseXMLBuilder
up
in class BaseXMLBuilder
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()
BaseXMLBuilder
up
in class BaseXMLBuilder
public XMLBuilder document()
BaseXMLBuilder
document
in class BaseXMLBuilder
Copyright © 2024. All rights reserved.