public final class XMLBuilder2 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 XMLBuilder2 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.
XMLBuilder2 has an feature set to the original XMLBuilder, but only ever
throws runtime exceptions (as opposed to checked exceptions). Any internal
checked exceptions are caught and wrapped in an
XMLBuilderRuntimeException
object.
Modifier | Constructor and Description |
---|---|
protected |
XMLBuilder2(Document xmlDocument)
Construct a new builder object that wraps the given XML document.
|
protected |
XMLBuilder2(Node myNode,
Node parentNode)
Construct a new builder object that wraps the given XML document and node.
|
Modifier and Type | Method and Description |
---|---|
XMLBuilder2 |
a(String name,
String value)
Synonym for
BaseXMLBuilder.attribute(String, String) . |
String |
asString()
Serialize the XML document to a string excluding the XML declaration.
|
String |
asString(Properties properties)
Serialize the XML document to a string by delegating to the
BaseXMLBuilder.toWriter(Writer, Properties) method. |
XMLBuilder2 |
attr(String name,
String value)
Synonym for
BaseXMLBuilder.attribute(String, String) . |
XMLBuilder2 |
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).
|
XMLBuilder2 |
c(String comment)
Synonym for
BaseXMLBuilder.comment(String) . |
XMLBuilder2 |
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).
|
XMLBuilder2 |
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).
|
XMLBuilder2 |
cmnt(String comment)
Synonym for
BaseXMLBuilder.comment(String) . |
XMLBuilder2 |
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 XMLBuilder2 |
create(String name)
Construct a builder for new XML document.
|
static XMLBuilder2 |
create(String name,
String namespaceURI)
Construct a builder for new XML document with a default namespace.
|
XMLBuilder2 |
d(byte[] data)
Synonym for
BaseXMLBuilder.cdata(byte[]) . |
XMLBuilder2 |
d(String data)
Synonym for
BaseXMLBuilder.cdata(String) . |
XMLBuilder2 |
data(byte[] data)
Synonym for
BaseXMLBuilder.cdata(byte[]) . |
XMLBuilder2 |
data(String data)
Synonym for
BaseXMLBuilder.cdata(String) . |
XMLBuilder2 |
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.
|
XMLBuilder2 |
e(String name)
Synonym for
BaseXMLBuilder.element(String) . |
XMLBuilder2 |
elem(String name)
Synonym for
BaseXMLBuilder.element(String) . |
XMLBuilder2 |
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.
|
XMLBuilder2 |
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
BaseXMLBuilder.toWriter(Writer, Properties) method. |
XMLBuilder2 |
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.
|
XMLBuilder2 |
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.
|
XMLBuilder2 |
i(String target,
String data)
Synonym for
BaseXMLBuilder.instruction(String, String) . |
XMLBuilder2 |
importXMLBuilder(BaseXMLBuilder builder)
Imports another XMLBuilder document into this document at the
current position.
|
XMLBuilder2 |
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).
|
XMLBuilder2 |
inst(String target,
String data)
Synonym for
BaseXMLBuilder.instruction(String, String) . |
XMLBuilder2 |
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).
|
XMLBuilder2 |
namespace(String namespaceURI)
Add an XML namespace attribute to this builder's element node
without a prefix.
|
XMLBuilder2 |
namespace(String prefix,
String namespaceURI)
Add an XML namespace attribute to this builder's element node.
|
XMLBuilder2 |
ns(String namespaceURI)
Synonym for
BaseXMLBuilder.namespace(String) . |
XMLBuilder2 |
ns(String prefix,
String namespaceURI)
Synonym for
BaseXMLBuilder.namespace(String, String) . |
static XMLBuilder2 |
parse(File xmlFile)
Construct a builder from an existing XML document file.
|
static XMLBuilder2 |
parse(InputSource inputSource)
Construct a builder from an existing XML document.
|
static XMLBuilder2 |
parse(String xmlString)
Construct a builder from an existing XML document string.
|
XMLBuilder2 |
r(String name)
Synonym for
BaseXMLBuilder.reference(String) . |
XMLBuilder2 |
ref(String name)
Synonym for
BaseXMLBuilder.reference(String) . |
XMLBuilder2 |
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).
|
XMLBuilder2 |
root() |
XMLBuilder2 |
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.
|
XMLBuilder2 |
t(String value)
Synonym for
BaseXMLBuilder.text(String) . |
XMLBuilder2 |
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).
|
XMLBuilder2 |
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 BaseXMLBuilder,
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. |
XMLBuilder2 |
up()
Return the builder node representing the parent of the current node.
|
XMLBuilder2 |
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.
|
XMLBuilder2 |
xpathFind(String xpath)
Find the first element in the builder's DOM matching the given
XPath expression.
|
XMLBuilder2 |
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.
|
assertElementContainsNoOrWhitespaceOnlyTextNodes, attributeImpl, buildDocumentNamespaceContext, cdataImpl, cdataImpl, commentImpl, createDocumentImpl, elementBeforeImpl, elementBeforeImpl, elementImpl, equals, getDocument, getElement, getPrefixFromQualifiedName, importXMLBuilderImpl, insertInstructionImpl, instructionImpl, lookupNamespaceURIImpl, namespaceImpl, namespaceImpl, parseDocumentImpl, referenceImpl, stripWhitespaceOnlyTextNodesImpl, textImpl, upImpl, xpathFindImpl
protected XMLBuilder2(Document xmlDocument)
xmlDocument
- an XML document that the builder will manage and manipulate.protected XMLBuilder2(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 XMLBuilder2 create(String name, String namespaceURI)
name
- the name of the document's root element.namespaceURI
- default namespace URI for document, ignored if null or empty.XMLBuilderRuntimeException
- to wrap ParserConfigurationException
public static XMLBuilder2 create(String name)
name
- the name of the document's root element.XMLBuilderRuntimeException
- to wrap ParserConfigurationException
public static XMLBuilder2 parse(InputSource inputSource)
inputSource
- an XML document input source that will be parsed into a DOM.XMLBuilderRuntimeException
- to wrap ParserConfigurationException
, SAXException
,
IOException
public static XMLBuilder2 parse(String xmlString)
xmlString
- an XML document string that will be parsed into a DOM.public static XMLBuilder2 parse(File xmlFile)
xmlFile
- an XML document file that will be parsed into a DOM.XMLBuilderRuntimeException
- to wrap ParserConfigurationException
, SAXException
,
IOException
, FileNotFoundException
public XMLBuilder2 stripWhitespaceOnlyTextNodes()
BaseXMLBuilder
stripWhitespaceOnlyTextNodes
in class BaseXMLBuilder
XMLBuilderRuntimeException
- to wrap XPathExpressionException
public XMLBuilder2 importXMLBuilder(BaseXMLBuilder builder)
BaseXMLBuilder
importXMLBuilder
in class BaseXMLBuilder
builder
- the XMLBuilder document to be imported.public XMLBuilder2 root()
root
in class BaseXMLBuilder
public XMLBuilder2 xpathFind(String xpath, NamespaceContext nsContext)
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.XMLBuilderRuntimeException
- to wrap XPathExpressionException
public XMLBuilder2 xpathFind(String xpath)
BaseXMLBuilder
xpathFind
in class BaseXMLBuilder
xpath
- An XPath expression that *must* resolve to an existing Element within
the document object model.public XMLBuilder2 element(String name)
BaseXMLBuilder
element
in class BaseXMLBuilder
name
- the name of the XML element.public XMLBuilder2 elem(String name)
BaseXMLBuilder
BaseXMLBuilder.element(String)
.elem
in class BaseXMLBuilder
name
- the name of the XML element.public XMLBuilder2 e(String name)
BaseXMLBuilder
BaseXMLBuilder.element(String)
.e
in class BaseXMLBuilder
name
- the name of the XML element.public XMLBuilder2 element(String name, String namespaceURI)
BaseXMLBuilder
element
in class BaseXMLBuilder
name
- the name of the XML element.namespaceURI
- a namespace URIpublic XMLBuilder2 elementBefore(String name)
BaseXMLBuilder
elementBefore
in class BaseXMLBuilder
name
- the name of the XML element.public XMLBuilder2 elementBefore(String name, String namespaceURI)
BaseXMLBuilder
elementBefore
in class BaseXMLBuilder
name
- the name of the XML element.namespaceURI
- a namespace URIpublic XMLBuilder2 attribute(String name, String value)
BaseXMLBuilder
attribute
in class BaseXMLBuilder
name
- the attribute's name.value
- the attribute's value.public XMLBuilder2 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 XMLBuilder2 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 XMLBuilder2 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 XMLBuilder2 text(String value)
BaseXMLBuilder
text
in class BaseXMLBuilder
value
- the text value to add to the element.public XMLBuilder2 t(String value)
BaseXMLBuilder
BaseXMLBuilder.text(String)
.t
in class BaseXMLBuilder
value
- the text value to add to the element.public XMLBuilder2 cdata(String data)
BaseXMLBuilder
cdata
in class BaseXMLBuilder
data
- the String value that will be added to a CDATA element.public XMLBuilder2 data(String data)
BaseXMLBuilder
BaseXMLBuilder.cdata(String)
.data
in class BaseXMLBuilder
data
- the String value that will be added to a CDATA element.public XMLBuilder2 d(String data)
BaseXMLBuilder
BaseXMLBuilder.cdata(String)
.d
in class BaseXMLBuilder
data
- the String value that will be added to a CDATA element.public XMLBuilder2 cdata(byte[] data)
BaseXMLBuilder
cdata
in class BaseXMLBuilder
data
- the data value that will be Base64-encoded and added to a CDATA element.public XMLBuilder2 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 XMLBuilder2 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 XMLBuilder2 comment(String comment)
BaseXMLBuilder
comment
in class BaseXMLBuilder
comment
- the comment to add to the element.public XMLBuilder2 cmnt(String comment)
BaseXMLBuilder
BaseXMLBuilder.comment(String)
.cmnt
in class BaseXMLBuilder
comment
- the comment to add to the element.public XMLBuilder2 c(String comment)
BaseXMLBuilder
BaseXMLBuilder.comment(String)
.c
in class BaseXMLBuilder
comment
- the comment to add to the element.public XMLBuilder2 instruction(String target, String data)
BaseXMLBuilder
instruction
in class BaseXMLBuilder
target
- the target value for the instruction.data
- the data value for the instructionpublic XMLBuilder2 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 XMLBuilder2 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 XMLBuilder2 insertInstruction(String target, String data)
BaseXMLBuilder
insertInstruction
in class BaseXMLBuilder
target
- the target value for the instruction.data
- the data value for the instructionpublic XMLBuilder2 reference(String name)
BaseXMLBuilder
reference
in class BaseXMLBuilder
name
- the name value for the reference.public XMLBuilder2 ref(String name)
BaseXMLBuilder
BaseXMLBuilder.reference(String)
.ref
in class BaseXMLBuilder
name
- the name value for the reference.public XMLBuilder2 r(String name)
BaseXMLBuilder
BaseXMLBuilder.reference(String)
.r
in class BaseXMLBuilder
name
- the name value for the reference.public XMLBuilder2 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 XMLBuilder2 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 XMLBuilder2 namespace(String namespaceURI)
BaseXMLBuilder
namespace
in class BaseXMLBuilder
namespaceURI
- a namespace uripublic XMLBuilder2 ns(String namespaceURI)
BaseXMLBuilder
BaseXMLBuilder.namespace(String)
.ns
in class BaseXMLBuilder
namespaceURI
- a namespace uripublic XMLBuilder2 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 XMLBuilder2 up()
BaseXMLBuilder
up
in class BaseXMLBuilder
public XMLBuilder2 document()
BaseXMLBuilder
document
in class BaseXMLBuilder
public String asString()
BaseXMLBuilder
asString
in class BaseXMLBuilder
XMLBuilderRuntimeException
- to wrap TransformerException
public String asString(Properties properties)
BaseXMLBuilder
BaseXMLBuilder.toWriter(Writer, Properties)
method. If output options are
provided, these options are provided to the Transformer
serializer.asString
in class BaseXMLBuilder
properties
- 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.XMLBuilderRuntimeException
- to wrap TransformerException
public String elementAsString()
BaseXMLBuilder
elementAsString
in class BaseXMLBuilder
XMLBuilderRuntimeException
- to wrap TransformerException
public String elementAsString(Properties outputProperties)
BaseXMLBuilder
BaseXMLBuilder.toWriter(Writer, Properties)
method.
If output options are provided, these options are provided to the
Transformer
serializer.elementAsString
in class BaseXMLBuilder
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.XMLBuilderRuntimeException
- to wrap TransformerException
public void toWriter(boolean wholeDocument, Writer writer, Properties outputProperties)
BaseXMLBuilder
TransformerFactory
and Transformer
classes.
If output options are provided, these options are provided to the
Transformer
serializer.toWriter
in class BaseXMLBuilder
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.XMLBuilderRuntimeException
- to wrap TransformerException
public void toWriter(Writer writer, Properties outputProperties)
BaseXMLBuilder
TransformerFactory
and Transformer
classes. If output
options are provided, these options are provided to the
Transformer
serializer.toWriter
in class BaseXMLBuilder
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.XMLBuilderRuntimeException
- to wrap TransformerException
public Object xpathQuery(String xpath, QName type, NamespaceContext nsContext)
BaseXMLBuilder
xpathQuery
in class BaseXMLBuilder
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.XMLBuilderRuntimeException
- to wrap XPathExpressionException
public Object xpathQuery(String xpath, QName type)
BaseXMLBuilder
xpathQuery
in class BaseXMLBuilder
xpath
- an XPath expressiontype
- the type the XPath is expected to resolve to, e.g:
XPathConstants.NODE
, XPathConstants.NODESET
,
XPathConstants.STRING
XMLBuilderRuntimeException
- to wrap XPathExpressionException
Copyright © 2018. All rights reserved.