Press on the image to return to the main documentation page.

---

XMLBuilder

Written by James Murty

List of types:

XMLBuilder

Internally, XML Builder uses JAXP to build a standard W3C
{@link org.w3c.dom.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 {@link org.w3c.dom.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 {@link DocumentBuilderFactory} and
{@link DocumentBuilder} classes are used to build the document.

Events:

Members:

an style="color: #000000; ">a (name As String, value As String) As XMLBuilder

  asString As String

  asString2 (outputProperties As java.util.Map) As String

  attr (name As String, value As String) As XMLBuilder

  attribute (name As String, value As String) As XMLBuilder

  buildDocumentNamespaceContext As com.jamesmurty.utils.NamespaceContextImpl

  c (comment As String) As XMLBuilder

  cdata (data As String) As XMLBuilder

  cmnt (comment As String) As XMLBuilder

  comment (comment As String) As XMLBuilder

  create (name As String) As XMLBuilder

  create2 (name As String, namespaceURI As String) As XMLBuilder

  d (data As String) As XMLBuilder

  data (data As String) As XMLBuilder

  Document As org.w3c.dom.Document [read only]

  e="color: #000000; ">e (name As String) As XMLBuilder

  elem (name As String) As XMLBuilder

  element (name As String) As XMLBuilder

  element2 (name As String, namespaceURI As String) As XMLBuilder

  elementAsString (outputProperties As java.util.Map) As String

  elementBefore (name As String) As XMLBuilder

  elementBefore2 (name As String, namespaceURI As String) As XMLBuilder

  equals (obj As Object) As Boolean

  GetElement As org.w3c.dom.Element

  i (target As String, data As String) As XMLBuilder

  importXMLBuilder (builder As XMLBuilder) As XMLBuilder

  inst (target As String, data As String) As XMLBuilder

  instruction (target As String, data As String) As XMLBuilder

  namespace (namespaceURI As String) As XMLBuilder

  namespace2 (prefix As String, namespaceURI As String) As XMLBuilder

  ns (namespaceURI As String) As XMLBuilder

  ns2 (prefix As String, namespaceURI As String) As XMLBuilder

  parse (inputSource As org.xml.sax.InputSource) As XMLBuilder

  r (name As String) As XMLBuilder

  ref (name As String) As XMLBuilder

  reference (name As String) As XMLBuilder

  root As XMLBuilder

  tyle="color: #000000; ">t (value As String) As XMLBuilder

  text (value As String) As XMLBuilder

  toWriter (wholeDocument As Boolean, writer As java.io.Writer, outputProperties As java.util.Map)

  toWriter2 (writer As java.io.Writer, outputProperties As java.util.Map)

  up As XMLBuilder

  up2 (steps As Int) As XMLBuilder

  xpathFind (xpath As String) As XMLBuilder

  xpathFind2 (xpath As String, nsContext As javax.xml.namespace.NamespaceContext) As XMLBuilder

  xpathQuery (xpath As String, type As javax.xml.namespace.QName) As Object

  xpathQuery2 (xpath As String, type As javax.xml.namespace.QName, nsContext As javax.xml.namespace.NamespaceContext) As Object

Members description:

a (name As String, value As String) As XMLBuilder

Synonym for {@link #attribute(String, String)}.
name: the attribute's name.
value: the attribute's value.
Return type: @return:the builder node representing the element to which the attribute was
added.

asString As String

Serialize the XML document to a string excluding the XML declaration.
Return type: @return:the XML document as a string without the XML declaration at the
beginning of the output.

asString2 (outputProperties As java.util.Map) As String

Serialize the XML document to a string by delegating to the
{@link #toWriter(Writer, Properties)} method. If output options are
provided, these options are provided to the {@link Transformer}
serializer.
outputProperties: settings for the {@link Transformer} serializer. This parameter may be
null or an empty Properties object, in which case the default output
properties will be applied.
Return type: @return:the XML document as a string

attr (name As String, value As String) As XMLBuilder

Synonym for {@link #attribute(String, String)}.
name: the attribute's name.
value: the attribute's value.
Return type: @return:the builder node representing the element to which the attribute was
added.

attribute (name As String, value As String) As XMLBuilder

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).
name: the attribute's name.
value: the attribute's value.
Return type: @return:the builder node representing the element to which the attribute was
added.

buildDocumentNamespaceContext As com.jamesmurty.utils.NamespaceContextImpl

Return type: @return:a namespace context containing the prefixes and namespace URI's used
within this builder's document, to assist in running namespace-aware
XPath queries against the document.

c (comment As String) As XMLBuilder

Synonym for {@link #comment(String)}.
comment: the comment to add to the element.
Return type: @return:the builder node representing the element to which the comment was added.

cdata (data As String) As XMLBuilder

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).
data: the String value that will be added to a CDATA element.
Return type: @return:the builder node representing the element to which the data was added.

cmnt (comment As String) As XMLBuilder

Synonym for {@link #comment(String)}.
comment: the comment to add to the element.
Return type: @return:the builder node representing the element to which the comment was added.

comment (comment As String) As XMLBuilder

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).
comment: the comment to add to the element.
Return type: @return:the builder node representing the element to which the comment was added.

create (name As String) As XMLBuilder

Construct a builder for new XML document. The document will be created
with the given root element, and the builder returned by this method
will serve as the starting-point for any further document additions.
name: the name of the document's root element.
Return type: @return:a builder node that can be used to add more nodes to the XML document.

create2 (name As String, namespaceURI As String) As XMLBuilder

Construct a builder for new XML document with a default namespace.
The document will be created with the given root element, and the builder
returned by this method will serve as the starting-point for any further
document additions.
name: the name of the document's root element.
namespaceURI: default namespace URI for document, ignored if null or empty.
Return type: @return:a builder node that can be used to add more nodes to the XML document.

d (data As String) As XMLBuilder

Synonym for {@link #cdata(String)}.
data: the String value that will be added to a CDATA element.
Return type: @return:the builder node representing the element to which the data was added.

data (data As String) As XMLBuilder

Synonym for {@link #cdata(String)}.
data: the String value that will be added to a CDATA element.
Return type: @return:the builder node representing the element to which the data was added.

Document As org.w3c.dom.Document [read only]

e (name As String) As XMLBuilder

Synonym for {@link #element(String)}.
name: the name of the XML element.
Return type: @return:a builder node representing the new child.

elem (name As String) As XMLBuilder

Synonym for {@link #element(String)}.
name: the name of the XML element.
Return type: @return:a builder node representing the new child.

element (name As String) As XMLBuilder

Add a named XML element to the document as a child of this builder node,
and return the builder node representing the new child.

When adding an element to a namespaced document, the new node will be
assigned a namespace matching it's qualified name prefix (if any) or
the document's default namespace. NOTE: If the element has a prefix that
does not match any known namespaces, the element will be created
without any namespace.
name: the name of the XML element.
Return type: @return:a builder node representing the new child.

element2 (name As String, namespaceURI As String) As XMLBuilder

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.
name: the name of the XML element.
namespaceURI: a namespace URI
Return type: @return:a builder node representing the new child.

elementAsString (outputProperties As java.util.Map) As String

Serialize the current XML Element and its descendants to a string by
delegating to the {@link #toWriter(Writer, Properties)} method.
If output options are provided, these options are provided to the
{@link Transformer} serializer.
outputProperties: settings for the {@link Transformer} serializer. This parameter may be
null or an empty Properties object, in which case the default output
properties will be applied.
Return type: @return:the XML document as a string

elementBefore (name As String) As XMLBuilder

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.

When adding an element to a namespaced document, the new node will be
assigned a namespace matching it's qualified name prefix (if any) or
the document's default namespace. NOTE: If the element has a prefix that
does not match any known namespaces, the element will be created
without any namespace.
name: the name of the XML element.
Return type: @return:a builder node representing the new child.

elementBefore2 (name As String, namespaceURI As String) As XMLBuilder

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.
name: the name of the XML element.
namespaceURI: a namespace URI
Return type: @return:a builder node representing the new child.

equals (obj As Object) As Boolean

Return type: @return:true if the XML Document and Element objects wrapped by this
builder are equal to the other's wrapped objects.

GetElement As org.w3c.dom.Element

Return type: @return:the XML element wrapped by this builder node.

i (target As String, data As String) As XMLBuilder

Synonym for {@link #instruction(String, String)}.
target: the target value for the instruction.
data: the data value for the instruction
Return type: @return:the builder node representing the element to which the instruction was
added.

importXMLBuilder (builder As XMLBuilder) As XMLBuilder

Imports another XMLBuilder document into this document at the
current position. The entire document provided is imported.
builder: the XMLBuilder document to be imported.
Return type: @return:a builder node at the same location as before the import, but
now containing the entire document tree provided.

inst (target As String, data As String) As XMLBuilder

Synonym for {@link #instruction(String, String)}.
target: the target value for the instruction.
data: the data value for the instruction
Return type: @return:the builder node representing the element to which the instruction was
added.

instruction (target As String, data As String) As XMLBuilder

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).
target: the target value for the instruction.
data: the data value for the instruction
Return type: @return:the builder node representing the element to which the instruction was
added.

namespace (namespaceURI As String) As XMLBuilder

Add an XML namespace attribute to this builder's element node
without a prefix.
namespaceURI: a namespace uri
Return type: @return:the builder node representing the element to which the attribute was added.

namespace2 (prefix As String, namespaceURI As String) As XMLBuilder

Add an XML namespace attribute to this builder's element node.
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 uri
Return type: @return:the builder node representing the element to which the attribute was added.

ns (namespaceURI As String) As XMLBuilder

Synonym for {@link #namespace(String)}.
namespaceURI: a namespace uri
Return type: @return:the builder node representing the element to which the attribute was added.

ns2 (prefix As String, namespaceURI As String) As XMLBuilder

Synonym for {@link #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 uri
Return type: @return:the builder node representing the element to which the attribute was added.

parse (inputSource As org.xml.sax.InputSource) As XMLBuilder

Construct a builder from an existing XML document. The provided XML
document will be parsed and an XMLBuilder object referencing the
document's root element will be returned.
inputSource: an XML document input source that will be parsed into a DOM.
Return type: @return:a builder node that can be used to add more nodes to the XML document.

r (name As String) As XMLBuilder

Synonym for {@link #reference(String)}.
name: the name value for the reference.
Return type: @return:the builder node representing the element to which the reference was
added.

ref (name As String) As XMLBuilder

Synonym for {@link #reference(String)}.
name: the name value for the reference.
Return type: @return:the builder node representing the element to which the reference was
added.

reference (name As String) As XMLBuilder

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).
name: the name value for the reference.
Return type: @return:the builder node representing the element to which the reference was
added.

root As XMLBuilder

Return type: @return:the builder node representing the root element of the XML document.
In other words, the same builder node returned by the initial
{@link #create(String)} or {@link #parse(InputSource)} method.

t (value As String) As XMLBuilder

Synonmy for {@link #text(String)}.
value: the text value to add to the element.
Return type: @return:the builder node representing the element to which the text was added.

text (value As String) As XMLBuilder

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).
value: the text value to add to the element.
Return type: @return:the builder node representing the element to which the text was added.

toWriter (wholeDocument As Boolean, writer As java.io.Writer, outputProperties As java.util.Map)

Serialize either the specific Element wrapped by this XMLBuilder, or its entire
XML document, to the given writer using the default {@link TransformerFactory}
and {@link Transformer} classes.
If output options are provided, these options are provided to the
{@link 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 {@link Transformer} serializer. This parameter may be
null or an empty Properties object, in which case the default output
properties will be applied.

toWriter2 (writer As java.io.Writer, outputProperties As java.util.Map)

Serialize the XML document to the given writer using the default
{@link TransformerFactory} and {@link Transformer} classes. If output
options are provided, these options are provided to the
{@link Transformer} serializer.
writer: a writer to which the serialized document is written.
outputProperties: settings for the {@link Transformer} serializer. This parameter may be
null or an empty Properties object, in which case the default output
properties will be applied.

up As XMLBuilder

Return the builder node representing the parent of the current node.
Return type: @return:the parent of this node, or the root node if this method is called on the
root node.

up2 (steps As Int) As XMLBuilder

Return the builder node representing the nth ancestor element
of this node, or the root node if n exceeds the document's depth.
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.
Return type: @return:the nth ancestor of this node, or the root node if this is
reached before the nth parent is found.

xpathFind (xpath As String) As XMLBuilder

Find the first element in the builder's DOM matching the given
XPath expression.
xpath: An XPath expression that *must* resolve to an existing Element within
the document object model.
Return type: @return:a builder node representing the first Element that matches the
XPath expression.

xpathFind2 (xpath As String, nsContext As javax.xml.namespace.NamespaceContext) As XMLBuilder

Find the first element in the builder's DOM matching the given
XPath expression, where the expression may include namespaces if
a {@link 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.
Return type: @return:a builder node representing the first Element that matches the
XPath expression.

xpathQuery (xpath As String, type As javax.xml.namespace.QName) As Object

Return the result of evaluating an XPath query on the builder's DOM.
Returns null if the query finds nothing,
or finds a node that does not match the type specified by returnType.
xpath: an XPath expression
type: the type the XPath is expected to resolve to, e.g:
{@link XPathConstants#NODE}, {@link XPathConstants#NODESET},
{@link XPathConstants#STRING}
Return type: @return:a builder node representing the first Element that matches the
XPath expression.

xpathQuery2 (xpath As String, type As javax.xml.namespace.QName, nsContext As javax.xml.namespace.NamespaceContext) As Object

Return the result of evaluating an XPath query on the builder's DOM
using the given namespace. Returns null if the query finds nothing,
or finds a node that does not match the type specified by returnType.
xpath: an XPath expression
type: the type the XPath is expected to resolve to, e.g:
{@link XPathConstants#NODE}, {@link XPathConstants#NODESET},
{@link 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.
Return type: @return:a builder node representing the first Element that matches the
XPath expression.

---

Top