fr.gael.drb
Interface DrbMutableNode

All Superinterfaces:

DrbNode

All Known Implementing Classes:

DrbAbstractNode, DrbDefaultMutableNode, DrbNodeImpl, fr.gael.drb.impl.spi.DrbNodeSpi, File, FileNode, FtpNode, URLNode, XmlDocument, XmlNode, XsdNodeImpl, ZipFileNode, ZipNode

public interface DrbMutableNode
extends DrbNode

Mutable node interface. Nodes are considered mutable when they provide an interface that enables to change their content or structure (i.e. attribute, name, children, etc.). This interface has been separated from the DrbNode because all the implementations are not supposed to provide a change interface. All the following operations are supposed to fire the most accurate events according to their business. DrbMutableNode interface has been designed on the basis of the MutableTreeNode provided by the Java API and by the DOM Event specifications of the W3C.

Important note: If the node has a physical representation (e.g. a file, an XML document) the any call of the operations defined in DrbMutableNode interface changes this physical representation. For instance renaming a node wrapping a file will effectively rename the file in the file system. The operations does not already support transactions supposed to store the changes until a commit. The changes may therefore take a variable amount of time according to the underlying implementation. For instance the insertion of a node as first child may require to copy a huge file even if the node value has small footprint in the final file.

Field Summary

Fields inherited from interface fr.gael.drb.DrbItem

ATTRIBUTE_ITEM, NODE_ITEM, UNDEFINED_ITEM, VALUE_ITEM

Method Summary

DrbAttribute	getAttribute(String name) Returns an attribute matching a specific name.
DrbAttributeList	getAttributes() The attributes of the nodes.
DrbNode	getChildAt(int index) Reference to a specific child.
DrbNodeList	getChildren() The list of children of the current node.
int	getChildrenCount() Number of children.
DrbNode	getFirstChild() Reference to the first child of the current node.
int	getIndex() Index of the node.
DrbNode	getLastChild() Reference to the last child of the current node.
String	getName() Name of the node.
DrbNode	getNamedChild(String name, int occurence) Returns an occurrence of child matching a specific name.
String	getNamespaceURI() Get namespace URI.
DrbNode	getNextSibling() Next sibling of the current node.
DrbNode	getParent() The parent of this node.
String	getPath() The full path of the node.
DrbNode	getPreviousSibling() Previous sibling of the current node.
DrbNode	getRoot() Root node.
Value	getValue() The value of the node.
int	getValueType() The value type of the node.
boolean	hasChild() Checks if current node is parent of at least one child.

Methods inherited from interface fr.gael.drb.DrbNode

appendChild, insertChild, removeChild, replaceChild, setAttributes, setNamespaceURI, setValue

Methods inherited from interface fr.gael.drb.DrbItem

getItemType, rename

Method Detail

getName

String getName()

Name of the node. Returns the name of the node. This name is the canonical name of the node It does not contains any prefix, path and location part.This name clearly identifies the node in its parent depending only from its occurrence number and its index. All nodes provided by an implementation is named. Therefore this operation never returns null value. An empty string is however allowed if the node is unique (e.g. non named root node).

Specified by:

getName in interface DrbItem

Returns:

The name of the node.

getIndex

int getIndex()

Index of the node. Returns the index of the node in its parent children list. This index starts from 0 and takes into account all occurrences of nodes disregarding the type of nodes. If the node has not parent the index may not be available: the operation returns therefore a negative value.

Returns:

The index of the node or negative value.

getRoot

DrbNode getRoot()

Root node. Returns the root node of the holding the current one. If the current node is already the root, the operation returns a reference to itself. The root corresponds to the top level node. If the node is not attached to a specific parent it has no root and therefore the current operation returns null.

Returns:

A reference to the root node or null.

getPath

String getPath()

The full path of the node. The full path of a node goes through the implementations. Each implementation is supposed to keep the URI (or an equivalent means)of its parent to fulfill this operation. The returned path is canonical so it does not necessarily correspond to the path that allowed the creation of the node. For instance the canonical path of a node created with the URI "/step1/../step2/node" is "/step2/node".The full path is an absolute path that begins with a "/". All steps are composed of the name of the node (i.e. returned by getName()) and a possible qualifier as defined in the XPath 2.0. For instance, if the implementation supports multi-occurrences of a node, the canonical step shall contain the occurrence number in a step qualifier (e.g "/step/node[2]/" ).

Returns:

The absolute path of the current node.

getNamespaceURI

String getNamespaceURI()

Get namespace URI. The namespace URI of this node, or null if it is unspecified. This is not a computed value that is the result of a namespace lookup based on an examination of the namespace declarations in scope. It is merely the namespace URI given at creation time.

Specified by:

getNamespaceURI in interface DrbItem

Returns:

The namspace URI or null if unspecified.

getValueType

int getValueType()

The value type of the node. The node can embedded a particular value according to the fr.gael.drb.value package. This operation returns the type identifier of the content of the current node. The value of the node depends on the implementation as well as on the node itself. If the node does not contain any value, it shall return fr.gael.drb.value.Value.NULL_ID identifier.

Returns:

NULL_ID if the node does not provide value or any other valid type identifier otherwise.

getValue

Value getValue()

The value of the node. The value of the node means its content. The value is expressed according to one of the types supported by the fr.gael.drb.value package. Generally these types correspond to primitive types (e.g. integer, floating points etc.) or very low level types (e.g. string, date, etc.).

Specified by:

getValue in interface DrbItem

Returns:

A reference to the value of the node or null if the node does not contains any value.

getAttributes

DrbAttributeList getAttributes()

The attributes of the nodes. This operation returns a list of attribute owned by the current node is any.

Returns:

The list attributes of the current node.

getAttribute

DrbAttribute getAttribute(String name)

Returns an attribute matching a specific name.

Parameters:

name - The name to match.

Returns:

A reference to the attribute or null is not found.

getParent

DrbNode getParent()

The parent of this node. Returns a reference to the parent node of the current node according to the current implementation. Most of the nodes have a parent except root nodes or if they have just been removed, etc. If the node has no parent the operation returns null.

Returns:

The parent of this node or null.

getChildren

DrbNodeList getChildren()

The list of children of the current node. Returns a list of references to the children of the current node. The current node may have no child and the operation returns therefore a null reference.

Returns:

The list of children if any null otherwise.

hasChild

boolean hasChild()

Checks if current node is parent of at least one child.

Returns:

true if current node has at least one child, false otherwise.

getNamedChild

DrbNode getNamedChild(String name,
                      int occurence)

Returns an occurrence of child matching a specific name. The occurrence number starts from 1. The name is a local name without any prefix.

Parameters:

name - The name to match.

occurence - The occurrence number of the desired child.

Returns:

A reference to the child or null if not found.

getFirstChild

DrbNode getFirstChild()

Reference to the first child of the current node. If the current node has no child a null reference if returned. The children order depends on the implementation. This operation time performance depends therefore from the implementation. However, the implementations shall try to prefer the firstChild() performances against the lastChild() as far as possible.

Returns:

A reference to the first child or null if no such node.

getLastChild

DrbNode getLastChild()

Reference to the last child of the current node. If the current node has no child a null reference if returned. The children order depends on the implementation. This operation time performance depends therefore from the implementation. However, the implementations shall try to prefer the firstChild() performances against the lastChild() as far as possible.

Returns:

A reference to the last child or null if no such node.

getChildAt

DrbNode getChildAt(int index)

Reference to a specific child. The child is identified by its position (i.e. index or sequence number) in the children list of this node. The children order depends on the implementation. This operation time performance depends therefore of this implementation.The provided index start from 0 and shall not be greater or equal to the number of children. If the current node has no child a null reference is returned.

Parameters:

index - The position of the node to retrieve starting from 0 and not greater or equal to the number of children.

Returns:

A reference to specified child or null if no such node.

getChildrenCount

int getChildrenCount()

Number of children. Returns the number of children belonging to the current node. According to the implementation the computation of children number may require more or less time. The number of children may actually require to parse a big file if it is not constant among document instances. It is therefore recommended to use this operation only if required. It is preferable to browse the tree from first children to last using getFirstChild() and getNextSibling() operations. If the current node has no child, 0 is returned.

Returns:

The number of children of the current node.

getPreviousSibling

DrbNode getPreviousSibling()

Previous sibling of the current node. Returns a reference to the previous node in the children list of current node parent. This reference may be null if the current node has no parent or if it is the first child of its parent. The reference may be null if the current node has no previous sibling.

Returns:

A reference to the previous sibling or null if no such node.

getNextSibling

DrbNode getNextSibling()

Next sibling of the current node. Returns a reference to the next node in the children list of current node parent. This reference may be null if the current node has no parent or if it is the last child of its parent. The reference may be null if the current node has no next sibling.

Returns:

A reference to the next sibling or null if no such node.