org.exist.fluent
Class ElementBuilder<K>

java.lang.Object
  org.exist.fluent.ElementBuilder<K>

Type Parameters:

K - the type of object returned upon completion of the builder, depends on the context in which the builder is used

public class ElementBuilder<K>
extends Object

A builder of DOM trees, meant to be either stand alone or be inserted into pre-existing ones. Cannot remove nodes from the base tree. You must commit() the builder to persist the recorded changes in the database. All the nodes in the tree being built must be from the same implementation. If you attempt to add foreign nodes -- for example, persistent nodes from the database -- using the node(org.exist.fluent.Node) or nodes(org.exist.fluent.ItemList.NodesFacet) methods to a builder that already has temporary nodes built using its other methods, they'll be imported. Importing nodes will usually make a deep copy of the tree in memory, which could cause problems if you're trying to add a big stored node tree.

Version:

$Revision: 1.18 $ ($Date: 2006/04/13 19:12:16 $)

Author:

Piotr Kaminski

Method Summary

ElementBuilder<K>	attr(String name, Object value) Add an attribute to the currently open element.
ElementBuilder<K>	attrIf(boolean condition, String name, Object value) Add an attribute to the currently open element if the given condition holds.
K	commit() Commit this element builder, persisting the recorded elements into the database.
static ElementBuilder<Node>	createScratch(NamespaceMap namespaceBindings) Create a new element builder that creates an in-memory DOM tree and returns the top node (possibly a fragment node) upon commit.
ElementBuilder<K>	elem(String tag) Open a new element with the given tag.
ElementBuilder<K>	end(String... tags) Close the currently open element, matching it to one of the given tags.
ElementBuilder<K>	end(String tag) Close the currently open element, matching it to the given tag.
ElementBuilder<K>	namespace(String key, String uri) Insert a namespace binding scoped to this builder only.
ElementBuilder<K>	node(Node node) Insert a copy of the given node.
ElementBuilder<K>	node(Node node) Insert a copy of the given node.
ElementBuilder<K>	nodes(ItemList.NodesFacet nodes) Insert copies of the given nodes.
ElementBuilder<K>	text(Object text) Insert text into the currenly open element.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

createScratch

public static ElementBuilder<Node> createScratch(NamespaceMap namespaceBindings)

Create a new element builder that creates an in-memory DOM tree and returns the top node (possibly a fragment node) upon commit.

Parameters:

namespaceBindings - the namespace bindings to use, or null for none

Returns:

a scratch in-memory builder

namespace

public ElementBuilder<K> namespace(String key,
                                   String uri)

Insert a namespace binding scoped to this builder only.

Parameters:

key - the prefix to bind

uri - the namespace uri

Returns:

this element builder, for chaining calls

node

public ElementBuilder<K> node(Node node)

Insert a copy of the given node.

Parameters:

node - the node to insert

Returns:

this element builder, for chaining calls

nodes

public ElementBuilder<K> nodes(ItemList.NodesFacet nodes)

Insert copies of the given nodes.

Parameters:

nodes - the nodes to insert

Returns:

this element builder, for chaining calls

node

public ElementBuilder<K> node(Node node)

Insert a copy of the given node. The node can be an element node, a text node, a document node or a fragment node. In the case of the latter two, their children are inserted instead.

Parameters:

node - the node to insert

Returns:

this element builder, for chaining calls

elem

public ElementBuilder<K> elem(String tag)

Open a new element with the given tag. The tag should be in the same format as in XML files (i.e. "prefix:localName") and is parsed into a QName according to the namespace bindings in effect for this builder. The element must be closed with end(String) before the builder is committed.

Parameters:

tag - the tag of the element to insert

Returns:

this element builder, for chaining calls

end

public ElementBuilder<K> end(String tag)

Close the currently open element, matching it to the given tag.

Parameters:

tag - the tag of the element to be ended

Returns:

this element builder, for chaining calls

end

public ElementBuilder<K> end(String... tags)

Close the currently open element, matching it to one of the given tags. Use this method when the element could be one of many, but it's not convenient to remember precisely which element name was used. This is still safer than just popping the top element off arbitrarily.

Parameters:

tags - the possible tags of the element to be ended

Returns:

this element builder, for chaining calls

attr

public ElementBuilder<K> attr(String name,
                              Object value)

Add an attribute to the currently open element. If an attribute with the same name was previously added to the element, overwrite its value.

Parameters:

name - the name of the attribute to add

value - the value of the attribute, will be converted to a string using DataUtils.toXMLString(Object)

Returns:

this element builder, for chaining calls

attrIf

public ElementBuilder<K> attrIf(boolean condition,
                                String name,
                                Object value)

Add an attribute to the currently open element if the given condition holds. If condition is true, this behaves as attr(String, Object), otherwise it does nothing.

Parameters:

condition - the condition to satisfy before adding the attribute

name - the name of the attribute to add

value - the value of the attribute

Returns:

the element builder, for chaining calls

text

public ElementBuilder<K> text(Object text)

Insert text into the currenly open element.

Parameters:

text - the text to insert

Returns:

this element builder, for chaining calls

commit

public K commit()

Commit this element builder, persisting the recorded elements into the database.

Returns:

the newly created resource, as appropriate