org.jaxup

Interface Updater

All Known Implementing Classes:

Dom4JDocumentUpdater, DOMDocumentUpdater, JDOMDocumentUpdater

public interface Updater

XML document updating and creating functionality, with an interface based on the XPath data model. The interface is intended to be sufficiently high-level, that implementations for different concrete document object models can be implemented.

Author:

Erwin Bolwidt

Method Summary

Modifier and Type	Method and Description
void	appendChild(java.lang.Object parent, java.lang.Object child, int position) Inserts a node into the document by appending it to the children of the parent, or if the position parameter isn't -1, by inserting it at that position in the list of children of the parent.
java.lang.Object	createAttribute(java.lang.Object contextNode, java.lang.String uri, java.lang.String qname, java.lang.String value) Creates an attribute node.
java.lang.Object	createComment(java.lang.Object contextNode, java.lang.String comment) Creates a comment node with the given text as the comment.
java.lang.Object	createDocument() Creates an empty XML document.
java.lang.Object	createElement(java.lang.Object contextNode, java.lang.String uri, java.lang.String qname) Creates an element node.
java.lang.Object	createNamespace(java.lang.Object contextNode, java.lang.String prefix, java.lang.String uri) Creates a namespace node.
java.lang.Object	createProcessingInstruction(java.lang.Object contextNode, java.lang.String target, java.lang.String data) Creates a processing-instruction node of the given target and data.
java.lang.Object	createText(java.lang.Object contextNode, java.lang.String text) Creates a text node of the given text.
Navigator	getNavigator() Returns a jaxen Navigator instance that can be used to navigate the document that is being updated by this Updater.
void	insertAfter(java.lang.Object refNode, java.lang.Object node) Inserts a node into the document after the refNode, as a sibling of the ref Node.
void	insertBefore(java.lang.Object refNode, java.lang.Object node) Inserts a node into the document before the refNode, as a sibling of the ref Node.
void	remove(java.lang.Object node) Removes a node from the document that it is in.
void	setAttribute(java.lang.Object element, java.lang.Object attribute) Sets an attribute on an element node, replacing an existing attribute with the same name.
void	setAttributeValue(java.lang.Object attribute, java.lang.String value) Changes the value of an existing attribute.
void	setNamespace(java.lang.Object element, java.lang.Object namespace) Binds a namespace node to an element node.

Method Detail

createDocument

java.lang.Object createDocument()
                         throws UpdateException

Creates an empty XML document.

Throws:

UpdateException - A document could not be created.

createComment

java.lang.Object createComment(java.lang.Object contextNode,
                               java.lang.String comment)
                        throws InvalidContextException

Creates a comment node with the given text as the comment.

Parameters:

contextNode - A node in the document in which the comment will be used.

comment - The text of the comment to create.

Returns:

A comment node that can be used in the same document as the contextNode.

Throws:

InvalidContextException - The contextNode parameter is not of a class or interface that the document model recognizes for a node.

createText

java.lang.Object createText(java.lang.Object contextNode,
                            java.lang.String text)
                     throws InvalidContextException

Creates a text node of the given text.

Parameters:

contextNode - A node in the document in which the text will be used.

comment - The text to create.

Returns:

A text node that can be used in the same document as the contextNode.

Throws:

InvalidContextException - The contextNode parameter is not of a class or interface that the document model recognizes for a node.

createElement

java.lang.Object createElement(java.lang.Object contextNode,
                               java.lang.String uri,
                               java.lang.String qname)
                        throws InvalidContextException

Creates an element node. Note that the namespace declaration attributes that would bind the prefix of the qname to the namespace uri are not automatically created. If they are not created separately, the document cannot be serialized in to a valid xml document that has the same meaning as the document tree that is in memory.

Parameters:

contextNode - A node in the document in which the element will be used.

uri - The namespace uri of the new element, or null

qname - The qualified name (prefix, semicolon, localname) of the new element.

Returns:

An element node that can be used in the same document as the contextNode.

Throws:

InvalidContextException - The contextNode parameter is not of a class or interface that the document model recognizes for a node.

createNamespace

java.lang.Object createNamespace(java.lang.Object contextNode,
                                 java.lang.String prefix,
                                 java.lang.String uri)
                          throws InvalidContextException

Creates a namespace node. A namespace node is a virtual node that is used in XPath and in XML Infoset. It has no equivalent in a serialized XML document, but is instead derived from the namespace declaration attributes in the serialized XML document. Care needs to be taken to create the namespace declaration attributes when creating namespace nodes, otherwise the serialized XML document may not be a valid representation of the in-memory document.

Parameters:

contextNode - A node in the document in which the namespace will be used.

prefix - The namespace prefix that will be bound to the namespace uri.

uri - The namespace uri of the new namespace node.

Returns:

A namespace node that can be used in the same document as the contextNode.

Throws:

InvalidContextException - The contextNode parameter is not of a class or interface that the document model recognizes for a node.

createAttribute

java.lang.Object createAttribute(java.lang.Object contextNode,
                                 java.lang.String uri,
                                 java.lang.String qname,
                                 java.lang.String value)
                          throws InvalidContextException

Creates an attribute node. Note that the namespace declaration attributes that would bind the prefix of the qname to the namespace uri are not automatically created. If they are not created separately, the document cannot be serialized in to a valid xml document that has the same meaning as the document tree that is in memory.

Parameters:

contextNode - A node in the document in which the attribute will be used.

uri - The namespace uri of the new attribute, or null to indicate that the attribute will not be in a namespace.

qname - The qualified name (prefix, semicolon, localname) of the new attribute.

value - The value of the new attribute.

Returns:

An attribute node that can be used in the same document as the contextNode.

Throws:

InvalidContextException - The contextNode parameter is not of a class or interface that the document model recognizes for a node.

createProcessingInstruction

java.lang.Object createProcessingInstruction(java.lang.Object contextNode,
                                             java.lang.String target,
                                             java.lang.String data)
                                      throws InvalidContextException

Creates a processing-instruction node of the given target and data. Format: <?target data?>

Parameters:

contextNode - A node in the document in which the text will be used.

target - The target for the processing instruction to create.

data - The data for the processing instruction to create. The format of the data depends on the syntax defined by the target; many targets define a syntax simular to the attribute list of an element node.

Returns:

A processing-instruction node that can be used in the same document as the contextNode.

Throws:

InvalidContextException - The contextNode parameter is not of a class or interface that the document model recognizes for a node.

insertBefore

void insertBefore(java.lang.Object refNode,
                  java.lang.Object node)
           throws UpdateException

Inserts a node into the document before the refNode, as a sibling of the ref Node.

Parameters:

refNode - The reference node, before which the new node will be inserted as a sibling.

node - The node that will be inserted.

Throws:

InvalidNodeException - A parameter that represents a node is not of a class or interface that the document model recognizes for the expected type of node.

UpdateException - Another exception occurred during update.

insertAfter

void insertAfter(java.lang.Object refNode,
                 java.lang.Object node)
          throws UpdateException

Inserts a node into the document after the refNode, as a sibling of the ref Node.

Parameters:

refNode - The reference node, after which the new node will be inserted as a sibling.

node - The node that will be inserted.

Throws:

InvalidNodeException - A parameter that represents a node is not of a class or interface that the document model recognizes for the expected type of node.

UpdateException - Another exception occurred during update.

appendChild

void appendChild(java.lang.Object parent,
                 java.lang.Object child,
                 int position)
          throws UpdateException

Inserts a node into the document by appending it to the children of the parent, or if the position parameter isn't -1, by inserting it at that position in the list of children of the parent.

Parameters:

parent - The parent node, which must be either a document or element node.

child - The node that will be appended / inserted.

position - The position in the child list where the child node will be inserted, or -1 to append the new child to the list of children.

Throws:

InvalidNodeException - A parameter that represents a node is not of a class or interface that the document model recognizes for the expected type of node.

UpdateException - Another exception occurred during update.

remove

void remove(java.lang.Object node)
     throws UpdateException

Removes a node from the document that it is in.

Parameters:

node - The node to remove.

Throws:

InvalidNodeException - A parameter that represents a node is not of a class or interface that the document model recognizes for the expected type of node.

UpdateException - Another exception occurred during update.

setAttribute

void setAttribute(java.lang.Object element,
                  java.lang.Object attribute)
           throws UpdateException

Sets an attribute on an element node, replacing an existing attribute with the same name.

Parameters:

element - The element node to set the attribute on.

attribute - The attribute node to set on the element.

Throws:

InvalidNodeException - A parameter that represents a node is not of a class or interface that the document model recognizes for the expected type of node.

UpdateException - Another exception occurred during update.

setAttributeValue

void setAttributeValue(java.lang.Object attribute,
                       java.lang.String value)
                throws UpdateException

Changes the value of an existing attribute.

Throws:

UpdateException

setNamespace

void setNamespace(java.lang.Object element,
                  java.lang.Object namespace)
           throws UpdateException

Binds a namespace node to an element node.

Parameters:

element - The element node to bind the namespace node to.

namespace - The namespace node to bind to the element node.

Throws:

InvalidNodeException - A parameter that represents a node is not of a class or interface that the document model recognizes for the expected type of node.

UpdateException - Another exception occurred during update.

getNavigator

Navigator getNavigator()

Returns a jaxen Navigator instance that can be used to navigate the document that is being updated by this Updater.

Returns:

A Navigator instance for the same document object model as this updater.

See Also:

Navigator