fr.gael.drb
Class DrbDefaultMutableNode

java.lang.Object
  fr.gael.drb.DrbDefaultNodesChangeProducer
      fr.gael.drb.DrbAbstractNode
          fr.gael.drb.impl.DrbNodeImpl
              fr.gael.drb.DrbDefaultMutableNode

All Implemented Interfaces:

DrbMutableNode, DrbNode, DrbNodesChangeListener, DrbNodesChangeProducer, EventListener

public class DrbDefaultMutableNode
extends DrbNodeImpl

Simple mutable node implementation. This class is a simple means to build a DrbNode. It extends the DrbMutableNode interface instead of the DrbNode because it natively requires to be modifiable. This also enables to reduce the signature of the constructors are delay the settings to further calls. This class accepts attributes as well as value and namespace identifier. The class is also a node change producer so its possible to monitor the changed performed on each instance.

Important note: The DrbDefaultMutableNode has no physical representation. Its children and attributes are therefore not stored in a physical media that may imply an important memory footprint.

Field Summary

protected DrbAttributeList	attributes Node attributes.
protected DrbDefaultNodeList	children Chldren of the current node.
protected int	index Index of the node in its parent children list.
protected String	name Node name.
protected String	namespaceURI Node namespace identifier.
protected DrbNode	nextSibling Next sibling of the current node.
protected DrbNode	parent Parent of the current node.
protected DrbNode	previousSibling Previous sibling of the current node.
protected DrbNode	referenceNode Node reference.
protected String	rootPath The root node path.
protected Object	userObject User object.
protected Value	value Node avlue.

Fields inherited from interface fr.gael.drb.DrbItem

ATTRIBUTE_ITEM, NODE_ITEM, UNDEFINED_ITEM, VALUE_ITEM

Constructor Summary

DrbDefaultMutableNode(String name)
Builds a new instance of DrbDefaultMutableNode.

DrbDefaultMutableNode(String name, DrbNode parent, int index, DrbNode previous_sibling, DrbNode next_sibling)
Builds a new instance of DrbDefaultMutableNode with a specified parent.

Method Summary

DrbNode	appendChild(DrbNode node) Appends a child to the node.
DrbNode	appendReference(DrbNode node) Adopt a child at the end of the children list.
DrbAttributeList	getAttributes() The attributes of the nodes.
DrbNodeList	getChildren() The list of children of the current node.
Object	getImpl(Class api) Returns a specific implementation.
int	getIndex() Returns the index of the node.
String	getName() Name of the node.
Namespace	getNamespaceBindings() Get the namespace bindings.
String	getNamespaceURI() Get namespace URI.
DrbNode	getNextSibling() Next sibling of the current node.
DrbNode	getParent() The parent of this node.
DrbNode	getPreviousSibling() Previous sibling of the current node.
DrbNode	getRoot() Returns the root node.
String	getRootPath() Returns the root path.
Object	getUserObject() Returns the user object node.
Value	getValue() The value of the node.
int	getValueType() The value type of the node.
String	getXPathName() Name of the node.
boolean	hasImpl(Class api) Tests if a specific interface can be provided.
DrbNode	insertChild(DrbNode node, int index) Inserts a child to the node children list.
boolean	isSame(DrbNode node) Checks nodes sameness.
static void	main(String[] args) Makes this class runnable for testing.
void	removeChild(int index) Removes an existing child.
void	rename(String name) Changes the name of the node.
DrbNode	replaceChild(int index, DrbNode node) Replaces a child of the current node.
void	setAttributes(DrbAttributeList attributes) Sets the attribute list to the node.
void	setContent(DrbSequence sequence) Set the content of the node.
void	setIndex(int index) Sets the index of the node.
void	setNamespaceBindings(Namespace namespaces) Sets the namespace bindings.
void	setNamespaceURI(String namespace_uri) Sets the namespace URI.
void	setParent(DrbNode parent) Sets the parent of this node.
void	setRootPath(String root_path) Set the path of the root node.
void	setUserObject(Object user_object) Set the user object node.
Value	setValue(Value value) Changes the value of the node.
String	toString() Returns the node as a string.

Methods inherited from class fr.gael.drb.impl.DrbNodeImpl

close, createAttribute, createNode, flush, getProvider

Methods inherited from class fr.gael.drb.DrbAbstractNode

allowsMultiOccurrence, equals, getAttribute, getChildAt, getChildrenCount, getContent, getFirstChild, getItemType, getLastChild, getNamedChild, getOccurrence, getPath, getXPathName, hasChild

Methods inherited from class fr.gael.drb.DrbDefaultNodesChangeProducer

addNodesChangeListener, getListenerList, nodesChanged, nodesInserted, nodesRemoved, removeNodesChangeListener, setListenerList, structureChanged

Methods inherited from class java.lang.Object

clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

referenceNode

protected DrbNode referenceNode

Node reference. This reference may be null.

name

protected String name

Node name. This attribute is never null but may be an empty string.

namespaceURI

protected String namespaceURI

Node namespace identifier. This attribute may be null if no namespace identifier has already been set.

parent

protected DrbNode parent

Parent of the current node. This reference may be null if not parent has already been set.

attributes

protected DrbAttributeList attributes

Node attributes. The attribute list may be a null reference.

value

protected Value value

Node avlue. The value of the node may be a null reference.

index

protected int index

Index of the node in its parent children list. Because a node may have no parent, this index is defaulted to 0.

children

protected DrbDefaultNodeList children

Chldren of the current node. The children list is DrbDefaultNodeList in order to benefit by the insertion and removal operations inherited from the ArrayList.

previousSibling

protected DrbNode previousSibling

Previous sibling of the current node.

nextSibling

protected DrbNode nextSibling

Next sibling of the current node.

userObject

protected Object userObject

User object.

rootPath

protected String rootPath

The root node path.

Constructor Detail

DrbDefaultMutableNode

public DrbDefaultMutableNode(String name)

Builds a new instance of DrbDefaultMutableNode. In order to reduce the constructor signature only the name of the node is passed to this operation. this name shall never be null. The reference to the name is not duplicated. The name string shall never be modified without using the current class accessors.

Parameters:

name - A reference to the name of the node to be instancied.

DrbDefaultMutableNode

public DrbDefaultMutableNode(String name,
                             DrbNode parent,
                             int index,
                             DrbNode previous_sibling,
                             DrbNode next_sibling)

Builds a new instance of DrbDefaultMutableNode with a specified parent. This constructor enables to build a new instance specifying more parameters. Because in many cases it is not possible to create a node specifying both the previous and the next sibling, their corresponding parameters may be null references. The reference to the parent as well as to the parent may be references to any node implementations (e.g. XmlNodes).

Parameters:

name - A reference to the name of the node to be instancied.

parent - A reference to the parent of the node to be instanciated.

index - The index of the node in is parent children list.

previous_sibling - A reference to the previous_sibling or null.

next_sibling - A reference to the next_sibling or null.

Method Detail

getName

public String getName()

Name of the node. Read accessor to the previously set node name. The name is never null but may be an empty string.

Overrides:

getName in class DrbAbstractNode

Returns:

The name of the node.

getXPathName

public String getXPathName()

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 occurence 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).

Overrides:

getXPathName in class DrbAbstractNode

Returns:

The name of the node.

rename

public void rename(String name)
            throws NullPointerException,
                   UnsupportedOperationException

Changes the name of the node. Sets the passed name to the current node. After modification, a node change event is fired to the listeners as specified in the interface documentation.

Overrides:

rename in class DrbAbstractNode

Parameters:

name - A reference to the new name to assign.

Throws:

UnsupportedOperationException - This exception is never raised by the current implementation.

NullPointerException - This exception is raised when the passed name is a null reference.

setContent

public void setContent(DrbSequence sequence)

Set the content of the node. The content of the node is a sequence of nodes, either text nodes (represented by string) either element nodes.

Parameters:

sequence - The sequence to be set

getRoot

public DrbNode getRoot()

Returns the root node. The root node retreival is delegated to the parent node if any. If no parent has been declared for this node, the opreation returns therefore null.

Overrides:

getRoot in class DrbAbstractNode

Returns:

A reference to the root node or null.

getIndex

public int getIndex()

Returns the index of the node. The index is the sequential position of the current node in its parent children list.

Overrides:

getIndex in class DrbAbstractNode

Returns:

The index of the current node in its parent children list.

setIndex

public void setIndex(int index)

Sets the index of the node. Simple accessor to the index attribute.

Parameters:

index - the index to be set.

getNamespaceURI

public String getNamespaceURI()

Get namespace URI.

Overrides:

getNamespaceURI in class DrbAbstractNode

Returns:

The namspace URI previsouly set or null if unspecified.

setNamespaceURI

public void setNamespaceURI(String namespace_uri)
                     throws NullPointerException,
                            UnsupportedOperationException

Sets the namespace URI. This operation fires a node changed event on success as specified in the interface documentation. Any previous namespace URI is discarded.

Specified by:

setNamespaceURI in interface DrbNode

Overrides:

setNamespaceURI in class DrbAbstractNode

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 never raised because the operation is fully implemented and accept any namespace.

getNamespaceBindings

public Namespace getNamespaceBindings()

Get the namespace bindings.

Overrides:

getNamespaceBindings in class DrbAbstractNode

Returns:

The namespace bindings.

setNamespaceBindings

public void setNamespaceBindings(Namespace namespaces)

Sets the namespace bindings.

Overrides:

setNamespaceBindings in class DrbAbstractNode

Parameters:

namespaces - A reference to the new namespace bindings.

getValueType

public int getValueType()

The value type of the node. The value type is determined from the value previously assigned to the node. If no speficic value has been previsouly set, fr.gael.drb.value.Value.NULL_ID type is returned.

Overrides:

getValueType in class DrbAbstractNode

Returns:

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

getValue

public Value getValue()

The value of the node. The value is the one previously set.

Overrides:

getValue in class DrbAbstractNode

Returns:

A reference to the value of the node or null if no value has already been set.

setValue

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

Changes the value of the node. This operation supports any king of value due to the current implementation.The previous value (if any) is completely discraded by the change. A node changed event is fired to the listeners has specified in the interface documentation.

Specified by:

setValue in interface DrbNode

Overrides:

setValue in class DrbAbstractNode

Parameters:

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

Returns:

The value paremeter because it is the effectivelly assigned value

Throws:

NullPointerException - This exception is raised when the passed reference to the value is null.

ClassCastException - This exception is never raised because the value is immediatly adopted without cast.

UnsupportedOperationException - This exception is never raised because the operation is fully implemented and accept any value types.

getAttributes

public DrbAttributeList getAttributes()

The attributes of the nodes. This operation returns a list of attribute previously set (if any).

Overrides:

getAttributes in class DrbAbstractNode

Returns:

The list attributes of the current node or null if none.

setAttributes

public void setAttributes(DrbAttributeList attributes)
                   throws NullPointerException,
                          UnsupportedOperationException

Sets the attribute list to the node. This operation fires a node changed event on success as specified in the interface documentation. Any previous attribute list is discarded.

Warning: The attribute list is not duplicated and shall therefore not be modified by another means than the accessors provided by the current node.

Specified by:

setAttributes in interface DrbNode

Overrides:

setAttributes in class DrbAbstractNode

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.

UnsupportedOperationException - This exception is never raised because the operation is fully implemented and accept any attribute.

getParent

public DrbNode getParent()

The parent of this node. Returns a reference to the parent node set previously.

Specified by:

getParent in class DrbAbstractNode

Returns:

The parent of this node or null.

setParent

public void setParent(DrbNode parent)

Sets the parent of this node. This passed reference can be of any DrbNode type but the operation does not attaches the current node the parent (i.e. in order to become one of its children), does not check the parent is able to have any child and moreover does not try to attach any sibling. It is an simple accessor the the parent reference.

Parameters:

parent - the parent node

getChildren

public 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.

Specified by:

getChildren in class DrbAbstractNode

Returns:

The list of children if any null otherwise.

appendChild

public DrbNode appendChild(DrbNode node)
                    throws NullPointerException,
                           UnsupportedOperationException

Appends a child to the node. This operation depends on the class of the node to be appended:

Case of DrbDefaultMutableNode: The node is appended in the children list, the previous sibling of the passed node is set to the previous child and the next sibling to null.The parent of the appended node is set to the current node and the index fixed to the length of the children count minus 1.

Other cases: The input tree is entirely duplicated to become an homogeneous tree of DrbDefaultMutableNodes. After this operation, the resulting root node is appended to the children list of the current node as in the previous case The tree duplication is preformed with the duplicateTree() operation of the present class.

Warning: The duplication may have an important or non-applicable memory footprint. This operation shall therefore be used with caution.

Events: This operation fires a node change event when the operation succeeded.The called operation is nodesInserted() of the Listeners.

Specified by:

appendChild in interface DrbNode

Overrides:

appendChild in class DrbAbstractNode

Parameters:

node - A reference to the child to append.

Returns:

The input node if instance of DrbDefaultMutableNode or a new instance of DrbDefaultMutableNode.

Throws:

NullPointerException - This exception is raised when the passed reference to the value is null.

UnsupportedOperationException - This exception is thrown when the node to append is not a instance of DrbDefaultMutableNode and the duplication operation has failed.

See Also:

fr.gael.drb.DrbNodesChangeListener

insertChild

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

Inserts a child to the node children list. 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 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(). This operation depends on the class of the node to be inserted:

Case of DrbDefaultMutableNode: The node is inserted in the children list, the previous sibling of the passed node is set to the previous child as well as the next sibling. The parent of the appended node is set to the current node and the index fixed to the requested one.

Other cases: The input tree is entirely duplicated to become an homogeneous tree of DrbDefaultMutableNodes. After this operation, the resulting root node is inserted to the children list of the current node as in the previous case The tree duplication is preformed with the duplicateTree() operation of the present class.

Warning: The duplication may have an important or non-applicable memory footprint. This operation shall therefore be used with caution.

Events: This operation fires a node change event when the operation succeeded.The called operation is nodesInserted() of the Listeners.

Specified by:

insertChild in interface DrbNode

Overrides:

insertChild in class DrbAbstractNode

Parameters:

node - A reference to the child to be inserted.

index - the index of the nodo to insert

Returns:

The input node if instance of DrbDefaultMutableNode or a new instance of DrbDefaultMutableNode.

Throws:

NullPointerException - This exception is raised when the passed reference to the value is null.

UnsupportedOperationException - This exception is thrown when the node to append is not a instance of DrbDefaultMutableNode and the duplication operation has failed.

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

See Also:

fr.gael.drb.DrbNodesChangeListener

removeChild

public 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, associtation, value, etc. 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 indicies of the nodes next to the removed one are decresed of one. Their parents as well as their contents are left unchanged.

Events: This operation fires a node change event on successful removal. 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.

Specified by:

removeChild in interface DrbNode

Overrides:

removeChild in class DrbAbstractNode

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 never raised.

replaceChild

public DrbNode replaceChild(int index,
                            DrbNode 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). This operation first removes the children at the given index and then inserts the new node at the same index. These actions are delegated to the removeChild() and insertChild() operations. Please refer to the documentation of these operations for a best understanding of what actions are effectively performed.

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.

Specified by:

replaceChild in interface DrbNode

Overrides:

replaceChild in class DrbAbstractNode

Parameters:

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

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

Returns:

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

Throws:

NullPointerException - This exception is raised when the reference to the new node is null.

IndexOutOfBoundsException - This exception is raised when the passed index does not correspond to any effective child.

UnsupportedOperationException - This exception is raised if one of the calls to removeChild() and insertChild() operations has raised it. This case shall never appear because the children list is supposed to be a consistent collection of DrbDefaultMutableNodes.

appendReference

public DrbNode appendReference(DrbNode node)
                        throws NullPointerException,
                               UnsupportedOperationException

Adopt 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.

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.

Overrides:

appendReference in class DrbAbstractNode

Parameters:

node - A reference to the node to be adopted.

Returns:

nothing

Throws:

NullPointerException - This exception is raised when the passed node a null reference.This exception may be overriden 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).

getPreviousSibling

public DrbNode getPreviousSibling()

Previous sibling of the current node.

Overrides:

getPreviousSibling in class DrbAbstractNode

Returns:

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

getNextSibling

public DrbNode getNextSibling()

Next sibling of the current node.

Overrides:

getNextSibling in class DrbAbstractNode

Returns:

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

isSame

public boolean isSame(DrbNode node)

Checks nodes sameness. In the current implementation only the Java reference can be use to determine the sameness of the node. Actually the parent node provides an interesting isSame() operation but it is impossible to check the current nodes deals with the same object (in the general sense) that the passed one.

Parameters:

node - The node to test against to the current one.

Returns:

true if the node references the same object as the current node and false otherwise (i.e. including null reference to node).

getUserObject

public Object getUserObject()

Returns the user object node.

Returns:

the user object previously set.

getRootPath

public String getRootPath()

Returns the root path.

Returns:

the root path if any or an empty string

setUserObject

public void setUserObject(Object user_object)

Set the user object node.

Parameters:

user_object - The new user object.

setRootPath

public void setRootPath(String root_path)

Set the path of the root node.

Parameters:

root_path - The path of the root node.

hasImpl

public boolean hasImpl(Class api)

Tests if a specific interface can be provided. This operations tests with a minimum of time and memory consumption if the current implementation can provide a specific interface. It important to consider that hasImpl() provides information about the ability to provide such interface in general cases but not focused on the current instance. It may therefore be impossible to get a specific implementation from a node whereas hasImpl() operation returns true.

Overrides:

hasImpl in class DrbNodeImpl

Parameters:

api - The class type to test.

Returns:

true if an implementation of the interface can be provided and false otherwise.

getImpl

public Object getImpl(Class api)

Returns a specific implementation. This operation returns a reference to an object implementing a specific interface. This mean is useful to benefit by a specific and direct API instead of using the DrbNode interface. The provided object shall represent the current node such as it is possible after a call to this operation, to dismiss the reference to the node. For instance, a file is usually wrapped as a drb.imple.file.File class and thanks to this operation can be seen as a InputStream anabling direct access to the handled file.

Overrides:

getImpl in class DrbNodeImpl

Parameters:

api - The interface (or class) to be provided.

Returns:

A reference to the object implementing the interface or a null reference otherwise.

toString

public String toString()

Returns the node as a string. This operation only prints the node name.

Overrides:

toString in class DrbAbstractNode

Returns:

The string descibing the current node.

main

public static void main(String[] args)

Makes this class runnable for testing.

Parameters:

args - the main arguments