com.ibm.portal.state.dom
Interface DocumentController

All Superinterfaces:

Disposable, DocumentModel

public interface DocumentController
extends DocumentModel

Controller interface on the document model. You may change the model's topology and the nodes' values only via this model facade.
There are three different types of possible modification:

• Modification of the topology: all references to affected lists of children become invalid after such a modification
• Modification of the content of a node: all references to lists of children and to the node that has been modified become invalid after such a modification
• Modification of the attributes of a node: all references to lists of children and to the node that has been modified and to the affected attributed list become invalid after such a modification

Each method describes to which modification category it belongs to

• HIER: modification of the hierarchy
• NODE: modification of the node's content
• ATTR: modification of the attribute or attribute list

Since:

5.1

Method Summary

Node	addAttribute(Node node, java.lang.String name, java.lang.String value) Modifies the content of the attribute of a node.
Node	clearAttributes(Node node) Removes all attributes from a node, so the getAttributes method will return null or an empty attributes set.
Node	create(java.lang.String url, java.lang.String name) Creates a new node without adding it to the document's topology.
Node	insert(Node newNode, Node nextNode, Node parent) Inserts a node into the list of children of another node.
Node	remove(Node node) Removes this node as the child of its current parent.
Node	removeAttribute(Node node, java.lang.String name) Removes an attribute from a node.
Node	resolve(Node node) Resolves a node of the document model to the reference of this very node that is the least recent.
Node	setAttributes(Node node, org.xml.sax.Attributes attrs) Overrides all attributes of a node with new values
Node	setValue(Node node, java.lang.String value) Modifies the content of a node.

Methods inherited from interface com.ibm.portal.state.dom.DocumentModel

getAttributes, getChildren, getParent, getRoot, hasAttributes, hasChildren

Methods inherited from interface com.ibm.portal.Disposable

dispose

Method Detail

setValue

Node setValue(Node node,
              java.lang.String value)

Modifies the content of a node. The reference to the original node is not guaranteed to be valid after a call to this method. Instead, the new reference will be returned.
NODE

Parameters:

node - Node from this model (must not be null)

value - new value (may be null)

Returns:

reference to the modified node (can be the same as the incoming node, but may also be differnt)

addAttribute

Node addAttribute(Node node,
                  java.lang.String name,
                  java.lang.String value)

Modifies the content of the attribute of a node. The reference to the original node is not guaranteed to be valid after a call to this method. Instead, the new reference will be returned.
ATTR

Parameters:

node - Node from this model (must not be null)

name - name of the attribute to add

value - new value (may be null)

Returns:

reference to the modified node (can be the same as the incoming node, but may also be differnt)

setAttributes

Node setAttributes(Node node,
                   org.xml.sax.Attributes attrs)

Overrides all attributes of a node with new values

Parameters:

node - node to overwrite the parameters of

attrs - new set of parameters (may be null)

Returns:

reference to the modified node (can be the same as the incoming node, but may also be differnt)

create

Node create(java.lang.String url,
            java.lang.String name)

Creates a new node without adding it to the document's topology.

Parameters:

url - Namespace URI of the node

name - Name of the node (must not be null)

Returns:

reference to the new node (not null)

insert

Node insert(Node newNode,
            Node nextNode,
            Node parent)

Inserts a node into the list of children of another node. The node may be inserted BEFORE a specifc element or added to the end of the list. If a node is inserted that already has a parent, then the old parent-child relationship will be removed before the node is insered. This is equivalent to moving the node from one position to another position.
HIER

Parameters:

newNode - Node to be inserted (must not be null)

nextNode - Node that will be shifted by one position to the right (i.e. the new node will be inserted before nextNode. If nextNode is null then the new node will be inserted as the last element of the child list.

parent - Node that acts as the NEW parent. The nextNode must already be a child of this new parent (if it is not null). The parent itself must not be null.

Returns:

Returns the parent node or a clone if the implementation decides to clone the parent node to fulfil this operation. Callers MUST use the resulting parent node for subsequent operations on the parent or query the parent node again.

remove

Node remove(Node node)

Removes this node as the child of its current parent. If there is no such parent, nothing happends. Even after removal the node stays part of the document model (but not part of the model's hierarchy). It is not possible to completely delete a node, once created the model will always keep a reference.
HIER

Parameters:

node - Node to be removed (must not be null)

Returns:

Returns the parent node or a clone if the implementation decides to clone the parent node to fulfil this operation. Callers MUST use the resulting parent node for subsequent operations on the parent or query the parent node again.

removeAttribute

Node removeAttribute(Node node,
                     java.lang.String name)

Removes an attribute from a node. The attributes stays part of the document model event after removing it from a node. It is not possible to completely remove an attribute from a model. The attribute can only be removed if is has been associated with a node node.

Parameters:

node - node to remove the attribute from

name - Attribute name to be removed (must not be null)

Returns:

Node the attribute has been attached to (cannot be null by contract above). This value invalidates all references to the parent node that have been obtained earlier.

clearAttributes

Node clearAttributes(Node node)

Removes all attributes from a node, so the getAttributes method will return null or an empty attributes set.

Parameters:

node - node to remove the attributes from (must not be null)

Returns:

The resolved node

resolve

Node resolve(Node node)

Resolves a node of the document model to the reference of this very node that is the least recent.

Parameters:

node - node to be resolved

Returns:

the resolved node, i.e. either the most recent instance or the input node itself