fr.gael.drb
Class DrbAbstractNode

java.lang.Object
  fr.gael.drb.DrbDefaultNodesChangeProducer
      fr.gael.drb.DrbAbstractNode

All Implemented Interfaces:

DrbMutableNode, DrbNode, DrbNodesChangeListener, DrbNodesChangeProducer, EventListener

Direct Known Subclasses:

DrbNodeImpl

public abstract class DrbAbstractNode
extends DrbDefaultNodesChangeProducer
implements DrbNode, DrbMutableNode

This class provides a skeletal implementation of the DrbNode interface, to minimize the effort required to implement this interface. The class is also a node change producer so its possible to monitor the changed performed on each instance.

Field Summary

Fields inherited from interface fr.gael.drb.DrbItem

ATTRIBUTE_ITEM, NODE_ITEM, UNDEFINED_ITEM, VALUE_ITEM

Constructor Summary

DrbAbstractNode()

Method Summary

boolean	allowsMultiOccurrence() Check if this node may have multiple occurrence
DrbNode	appendChild(DrbNode node) Appends a child at the end of the children list.
DrbNode	appendReference(DrbNode node) Append a child reference at the end of the children list.
boolean	equals(Object obj) Indicates whether this node is "equal to" to another node.
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.
abstract DrbNodeList	getChildren() The list of children of the current node.
int	getChildrenCount() Number of children.
DrbSequence	getContent() The content of the current node.
DrbNode	getFirstChild() Reference to the first child of the current node.
int	getIndex() Index of the node.
int	getItemType() A code representing the type of the underlying object, as defined above.
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 occurence of the node matching the specified name.
Namespace	getNamespaceBindings() Get the namespace bindings.
String	getNamespaceURI() Get namespace URI.
DrbNode	getNextSibling() Next sibling of the current node.
int	getOccurrence() Occurrence of the node.
abstract 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() Returns the root node.
Value	getValue() The value of the node.
int	getValueType() The value type of the node.
protected String	getXPathName() Name of the node.
protected String	getXPathName(DrbAbstractNode node) Name of the node.
boolean	hasChild() Checks if child any child exists.
DrbNode	insertChild(DrbNode node, int index) Inserts a child at a given position.
void	removeChild(int index) Removes an existing child.
void	rename(String name) Changes the name of the node.
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	setNamespaceBindings(Namespace bindings) Set the namespace bindings.
void	setNamespaceURI(String namespace_uri) Sets a namespace resource identifier.
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.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

Constructor Detail

DrbAbstractNode

public DrbAbstractNode()

Method Detail

equals

public boolean equals(Object obj)

Indicates whether this node is "equal to" to another node. See Object.equals() for the general contract of this method.

Overrides:

equals in class Object

Parameters:

obj - another value.

Returns:

true if this object is the same as the obj argument

getItemType

public int getItemType()

A code representing the type of the underlying object, as defined above.

Returns:

The code of this item.

getName

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

Returns:

The name of the node.

getXPathName

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

Returns:

The name of the node.

getXPathName

protected final String getXPathName(DrbAbstractNode node)

Name of the node. This method is provided to implement filtering operations. It's simply call getXPathName() of the input node.

Parameters:

node - node

Returns:

The name of the node.

getIndex

public 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 occurences of nodes disregrading 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.

getOccurrence

public int getOccurrence()

Occurrence of the node. Returns the occurrence of the node in its parent children list. If the node has not parent the occurrence may not be available: the operation returns therefore a negative value.

Returns:

The index of the node or negative value.

allowsMultiOccurrence

public boolean allowsMultiOccurrence()

Check if this node may have multiple occurrence

Returns:

true if the children may have a multiple occurrence and false otherwise.

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 operation returns therefore null.

Returns:

A reference to the root node or null.

getPath

public String getPath()

The full path of the node. The full path is the full path of the parent node to which is appended the name of the current node.

Warning: Because the occurence number of the current node is not known in the parent, the occurence qualifier is not support by the current implementation.A possible algorithm shall be to search a reference to the current node in the list of children of the parent.

If no parent have already been set no absolute path is considered. A path considering the current node has a root node is not valid for the factory and is therefore not significant in the current implementation.

Returns:

The absolute path of the current node.

getNamespaceURI

public 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. The Namespaces on an attribute does not inherit its namespace from the element it is attached to. If an attribute is not explicitly given a namespace, it simply has no namespace

Returns:

The namspace URI or null if unspecified.

getNamespaceBindings

public Namespace getNamespaceBindings()

Get the namespace bindings.

Returns:

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

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.

Returns:

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

getAttributes

public DrbAttributeList getAttributes()

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

Returns:

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

getAttribute

public 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

public abstract DrbNode getParent()

The parent of this node. Returns a reference to the parent node of the current node according to the curren implementation. Most of the nodes have a parent exept 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

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

getContent

public DrbSequence getContent()

The content of the current node. Returns a sequence of nodes and atomic values.

Returns:

The content of this node.

hasChild

public boolean hasChild()

Checks if child any child exists. Returns wheter the current node has at least a child. This check is performed on the list set previously (if any). The list reference as well as the effective number of children are checked.

Returns:

true if this node has any children, false otherwise.

getNamedChild

public DrbNode getNamedChild(String name,
                             int occurence)

Returns an occurence of the node matching the specified name.

Parameters:

name - the String

occurence - int

Returns:

DrbNode

getFirstChild

public DrbNode getFirstChild()

Reference to the first child of the current node. The reference to the first child is retreived from the children list previously set.

Returns:

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

getLastChild

public DrbNode getLastChild()

Reference to the last child of the current node. The reference to the last child is retreived from the children list previously set.

Returns:

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

getChildAt

public DrbNode getChildAt(int index)

Reference to a specific child. The child is extracted from the children list previously set.

Parameters:

index - The position of the node to retreive 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

public int getChildrenCount()

Number of children. The number of children is retreived from the children list previously set If the children list has not already been set, 0 is returned.

Returns:

The number of children of the current node.

getPreviousSibling

public 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

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

rename

public void rename(String name)
            throws NullPointerException,
                   UnsupportedOperationException

Changes the name of the node. The passed name may be an empty string but never a null reference. The change is persistant such as further instance of a same node (even in different sessions) will have this new name. If the implementation does not suppot the rename operation it is supposerd to throw a UnsupportedOperationException.

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 standing also as the source of the event. The called opetation is the nodesChanged() of the listeners.

Parameters:

name - Reference to the new name.

Throws:

UnsupportedOperationException - This exception is raised when the implementation does not support the requested rename for any reason (e.g. specific case or general incapability).

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

setValue

public 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 effectivelly 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 assignement. 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 consumses 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.

Specified by:

setValue in interface DrbNode

Parameters:

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

Returns:

The effectivelly 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 overriden 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

public 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 maybe duplicated or re-instanciated according to the targetted implementation. References to the effectively inserted attributes can be reteived from the getAttributes() operation of the DrbNode. It is highly recommended to discard the references to the input attribuets 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.

Specified by:

setAttributes in interface DrbNode

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 overriden by an UnsupportedOperationException.

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

setNamespaceURI

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

Specified by:

setNamespaceURI in interface DrbNode

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

setNamespaceBindings

public void setNamespaceBindings(Namespace bindings)
                          throws UnsupportedOperationException

Set the namespace bindings.

Parameters:

bindings - The namespace bindings.

Throws:

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

public 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 indicies are increased of one. In addition the assiociations 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 targetted 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.

Specified by:

insertChild in interface DrbNode

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 overriden by an UnsupportedOperationException.

IndexOutOfBoundsException - This exception is raised when the passed 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

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

Specified by:

appendChild in interface DrbNode

Parameters:

node - A reference to the node to be appended.

Returns:

A reference to the effectivelly 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 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).

replaceChild

public 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 targetted 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() structureChanged() of the listeners.

Specified by:

replaceChild in interface DrbNode

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 effectivelly 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 overriden 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 retreived in the current children list, this exception is also raised.

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

Specified by:

removeChild in interface DrbNode

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.

appendReference

public DrbNode appendReference(DrbNode node)
                        throws NullPointerException,
                               UnsupportedOperationException

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

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 a node.

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

toString

public String toString()

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

Overrides:

toString in class Object

Returns:

The string descibing the current node.