fr.gael.drb
Interface DrbNode

All Known Subinterfaces:

DrbMutableNode, XsdNode

All Known Implementing Classes:

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

public interface DrbNode

Node interface. This interface represents a single node of a tree of data. Any node can have no, one or several children.This interface provides the primarily operations to browse an entire data structure. All implementations of the "Data Request Broker" shall be able to produce such nodes. Nodes are considered mutable when they provide an interface that enables to change their content or structure (i.e. attribute, name, children, etc.). All the following operations are supposed to fire the most accurate events according to their business. DrbNode 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

DrbNode	appendChild(DrbNode node) Appends a child at the end of the children list.
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.
DrbNode	insertChild(DrbNode node, int index) Inserts a child at a given position.
void	removeChild(int index) Removes an existing child.
DrbNode	replaceChild(int index, DrbNode new_node) Replaces a child of the current node.
void	setAttributes(DrbAttributeList attributes) Set the attribute list of a node.
void	setNamespaceURI(String namespace_uri) Sets a namespace resource identifier.
Value	setValue(Value value) Changes the value of the node.

Methods inherited from interface fr.gael.drb.DrbItem

getItemType, rename

Method Detail

setValue

Value setValue(Value value)
               throws NullPointerException,
                      ClassCastException,
                      UnsupportedOperationException

Changes the value of the node. This operation sets a new value of the current node.The value type of the node shall be compatible with the node implementation. If the type does not match exactly it is casted to a compatible one based on the the fr.gael.drb.value capabilities. A reference to the effectively assigned value is returned by the operation so it is possible to check if a cast has been performed and therefore assess the accuracy of the assignment. If the cast is not possible the operation raises an UnsupportedOperationException. If the assignment is possible and the node implementation has a physical representation the value is updated in the physical source in order to persist among sessions. It therefore possible that this operation consumes an variable time.

Important note: The implementation of the node is not supposed to accept value changes. For instance it may not be possible to change the value of a file directory that has no immediate signification.

Events: This operation fires a node changed event when the implementation is a node change producer. The node affected by the change is the current node as well as the source node. The called operation is the nodesChanged() of the listeners.

Parameters:

value - The new value of the node. This value shall not be null.

Returns:

The effectively assigned value.The type of this value may differ from the input one.

Throws:

NullPointerException - This exception is raised when the passed reference to the value is null. This exception may be overridden by an UnsupportedOperationException.

ClassCastException - This exception is raised when the implementation has not succeeded to cast the input value in a type compatible with the current node.

UnsupportedOperationException - This exception is raised when the implementation does not support the requested assignment for any reason.

setAttributes

void setAttributes(DrbAttributeList attributes)
                   throws NullPointerException,
                          UnsupportedOperationException

Set the attribute list of a node. If some attributes are already attached to the current node they are first removed and then replaced by the new ones. However the operation checks the compatibility of the passed attribute according to the current implementation. The operation does nothing if the compatibility check fails.

Warning: The input attributes may be duplicated or re-instanciated according to the targeted implementation. References to the effectively inserted attributes can be retrieved from the getAttributes() operation of the DrbNode. It is highly recommended to discard the references to the input attributes if not mandatory.

Important note: The implementation of the node is not supposed to accept attribute changes. For instance it may not be possible to change the size attribute of a file through this operation with would meant a effective file resize that is not really relevant without additional data.

Events: This operation fires a node change event when the implementation is a node change producer. The node affected by the change is the current node as well as the source node.The called operation is the nodesChanged() of the listeners.

Parameters:

attributes - A reference to the new attribute list.

Throws:

NullPointerException - This exception is raised when the passed reference to the attribute list is null. This exception may be overridden by an UnsupportedOperationException.

UnsupportedOperationException - This exception is raised when the implementation does not support the requested attribute changes for any reason.

setNamespaceURI

void setNamespaceURI(String namespace_uri)
                     throws NullPointerException,
                            UnsupportedOperationException

Sets a namespace resource identifier. The new namespace identifier shall not be null.

Important note: The implementation of the node is not supposed to accept namespace changes. For instance it may not be possible to change the namespace of a file that is basically fixed.

Events: This operation fires a node change event when the implementation is a node change producer. The node affected by the change is the current node as well as the source node.The called operation is the nodesChanged() of the listeners.

Parameters:

namespace_uri - A reference to the new namespace identifier.

Throws:

NullPointerException - This exception is raised when the passed reference to the new namespace identifier is null.

UnsupportedOperationException - This exception is raised when the implementation does not support the requested namespace change for any reason (e.g. by definition or in the specific case).

insertChild

DrbNode insertChild(DrbNode node,
                    int index)
                    throws NullPointerException,
                           UnsupportedOperationException,
                           IndexOutOfBoundsException

Inserts a child at a given position. The passed node is inserted in the list of children at the given position The position is the expected index of the node after insertion. All the previous children from the aimed position to the end of the list are shift to the end of the new children list (i.e. their indices are shifted up of 1). If the given index is out of the children bounds and therefore less than zero and greater or equal to the current number of children,the operation raises an exception. An index equal to the current number of children is allowed and the operation is therefore equivalent to appendChild().

If the node has been inserted within the children list, the next sibling indices are increased of one. In addition the associations between the inserted node and it previous and next siblings are updated (if any).

Warning: The inserted node may be duplicated or re-instanciated according to the targeted implementation. A reference to the effectively inserted node is returned by the operation. It is highly recommended to discard the reference to the input node if not mandatory and to reference the returned node.

Important note: The implementation of the node is not supposed to accept any kind of node For instance it may not be possible to insert a node wrapping a file in an XML document. The documentation of the implementation shall describe its specific strategy.

Case of unordered or specifically ordered implementations: If the implementation does not support ordered children or has specific ordering rules, the node is inserted without taking into account the requested index passed in parameter. For instance it may not be possible to impose the file order in a directory: it generally depends on the lexicographical order of the node names or their creation date.

Events: This operation fires a node change event when the implementation is a node change producer. The node affected by the change is the inserted node and the source is the current node. The called operation is the nodesInserted() of the listeners.

Parameters:

node - A reference to the node to be inserted.

index - The expected index of the node after the insertion.

Returns:

A reference to the effectively inserted node. This reference may differ from the input one.

Throws:

NullPointerException - This exception is raised when the passed node a null reference. This exception may be overridden by an UnsupportedOperationException.

IndexOutOfBoundsException - This exception is raised when the passe index is less than zero or if it is greater or equal to the number of children in the number of children prior the call

UnsupportedOperationException - This exception is raised when the implementation does not support the requested insertion for any reason (e.g. impossible in this current specific case or in general).

appendChild

DrbNode appendChild(DrbNode node)
                    throws NullPointerException,
                           UnsupportedOperationException

Appends a child at the end of the children list. The passed node is inserted in the list of children at the end of the current list.

Warning: The appended node may be duplicated or re-instanciated according to the targeted implementation. A reference to the effectively appended node is returned by the operation. It is highly recommended to discard the reference to the input node if not mandatory and to reference the returned node.

Important note: The implementation of the node is not supposed to accept any kind of node For instance it may not be possible to append a node wrapping a file in an XML document. The documentation of the implementation shall describe its specific strategy.

Case of unordered or specifically ordered implementations: If the implementation does not support ordered children or has specific ordering rules, the node may not be appended but only inserted according to these rules. For instance it may not be possible to impose the file order in a directory:it generally depends on the lexicographical order of the node names or their creation date.

Events: This operation fires a node change event when the implementation is a node change producer. The node affected by the change is the appended node and the source is the current node. The called operation is the nodesInserted() of the listeners.

Parameters:

node - A reference to the node to be appended.

Returns:

A reference to the effectively appended node. This reference may differ from the input one.

Throws:

NullPointerException - This exception is raised when the passed node a null reference.This exception may be overridden by an UnsupportedOperationException.

UnsupportedOperationException - This exception is raised when the implementation does not support the requested append for any reason (e.g. impossible in this current specific case or in general).

replaceChild

DrbNode replaceChild(int index,
                     DrbNode new_node)
                     throws NullPointerException,
                            IndexOutOfBoundsException,
                            UnsupportedOperationException

Replaces a child of the current node. This operation replaces a child in the current children list by a new one The operation aborts when the index is out of bound (index < 0 || index > size). In case of error, the implementation has to restore the initial situation. It is therefore recommended for any implementation to check the consistency prior to perform the replacement.

Warning: The replacing node may be duplicated or re-instanciated according to the targeted implementation.A reference to the effectively replacing node is returned by the operation. It is highly recommended to discard the reference to the input node if not mandatory and to reference the returned one.

Important note: The implementation of the node is not supposed to accept any kind of node For instance it may not be possible to insert a node wrapping a file in an XML document. The documentation of the implementation shall describe its specific strategy.

Events: This operation fires a node change event when the implementation is a node change producer. The node affected by the change is the new node and the source is the current node. The called operation is the structureChanged() of the listeners.

Parameters:

index - Index of the node to be replaced. This index starts at 0 and shall be less than the number of children.

new_node - A reference to the node that replaces the old one.

Returns:

A reference to the effectively replacing node.This reference may differ from the new_node parameter.

Throws:

NullPointerException - This exception is raised when the reference to the new node is null. This exception may be overridden by a UnsupportedOperationException.

IndexOutOfBoundsException - This exception is raised when the passed index is less than zero or greater or equal to the current number of children.

UnsupportedOperationException - This exception is raised when the implementation does not support the requested replace for any reason. In addition if the old_node is not retrieved in the current children list, this exception is also raised.

removeChild

void removeChild(int index)
                 throws IndexOutOfBoundsException,
                        UnsupportedOperationException

Removes an existing child. The child at the given index is removed from the children list of the current node. The child is not modified by this operation. At the child point of view it keeps the same parent or any common association depending on the implementation. However at the parent (i.e. the current node) point of view the removed node is completely dismissed and will never be re-instaciated from constructor operations (e.g. getFirstChild(), etc. ). The index of the child to be removed has to correspond to an existing children index. If the index is less than zero or greater or equal to the current number of children, an exception is thrown.

This operation takes into account the removal by updating the sibling associations of the children nodes prior and next to the removed one. The indices of the nodes next to the removed one are decreased of one. Their parents as well as their contents are left unchanged.

Events: This operation fires a node change event when the implementation is a node change producer. The node affected by the change is the removed node and the source is the current node.The called operation is the nodesRemoved() of the listeners.

Parameters:

index - Index of the child to be removed.

Throws:

IndexOutOfBoundsException - This exception is raised when the passed index is less than zero or greater or equal to the current number of children.

UnsupportedOperationException - This exception is raised when the implementation does not support the requested removal for any reason.

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.