fr.gael.drb.xsd
Class XsdNodeImpl

java.lang.Object
  fr.gael.drb.DrbDefaultNodesChangeProducer
      fr.gael.drb.DrbAbstractNode
          fr.gael.drb.impl.DrbNodeImpl
              fr.gael.drb.xsd.XsdNodeImpl

All Implemented Interfaces:

DrbMutableNode, DrbNode, DrbNodesChangeListener, DrbNodesChangeProducer, XsdNode, EventListener

public class XsdNodeImpl
extends DrbNodeImpl
implements XsdNode

A XML-Schema validator wrapper for DrbNodes.

Field Summary

protected DrbNode

baseNode The baseNode node.

Fields inherited from interface fr.gael.drb.DrbItem

ATTRIBUTE_ITEM, NODE_ITEM, UNDEFINED_ITEM, VALUE_ITEM

Constructor Summary

protected

XsdNodeImpl(XsdNodeImpl parent, DrbNode base, XsdType type) Build an DrbNodeFilter instance.

Method Summary

DrbNode	appendChild(DrbNode node) Appends a child at the end of the children list.
void	close(boolean deep) Closes this node and releases any system resources associated with the pointed file.
DrbAttribute	getAttribute(String name) Returns an attribute matching a specific name.
DrbAttributeList	getAttributes() The attributes of the nodes.
DrbNode	getBase() Returns the DrbNode baseNode.
DrbNode	getChildAt(int index) Reference to a specific child.
DrbNode	getChildAt(int index) Reference to a specific child of the current node (directory).
DrbNodeList	getChildren() The list of children of the current node.
DrbNodeList	getChildren() The list of children of the current node.
int	getChildrenCount() Number of children.
int	getChildrenCount() Number of files or directory hold by the current node (directory).
DrbSequence	getContent() The content of the current node.
DrbNode	getFirstChild() Reference to the first child of the current node.
DrbNode	getFirstChild() Reference to the first child of the current node (directory).
Object	getImpl(Class api) Returns a specific implementation.
int	getIndex() Index of the node.
int	getIndex() Index of the node.
protected fr.gael.drb.xsd.DrbNodeFilter	getInstance(DrbNode node) Builds a XSD implementation from a base node.
static XsdNode	getInstance(DrbNode base, XsdType type) Create an XsdNode instance.
DrbNode	getLastChild() Reference to the last child of the current node.
DrbNode	getLastChild() Reference to the last child of the current node (directory).
String	getName() Name of the node.
String	getName() Name of the node.
DrbNode	getNamedChild(String name, int occurence) Returns an occurrence of child matching a specific name.
DrbNode	getNamedChild(String name, int occurence) Returns an occurence of child matching a specific name.
Namespace	getNamespaceBindings() Get the namespace bindings.
String	getNamespaceURI() Get namespace URI.
String	getNamespaceURI() Get namespace URI.
DrbNode	getNextSibling() Next sibling of the current file or directory.
DrbNode	getParent() The parent of this node.
String	getPath() The full path of the node.
String	getPath() The full path of the node.
DrbNode	getPreviousSibling() Previous sibling of the current file or directory.
DrbNode	getRoot() Root node.
XsdType	getType() Returns the type of this node or null if it is unknown.
Value	getValue() The value of the node.
Value	getValue() The value of the node.
int	getValueType() The value type of the node.
int	getValueType() The value type of the node.
protected String	getXPathName() Name of the node.
boolean	hasChild() Checks if current node is parent of at least one child.
boolean	hasChild() Checks if any child exists.
boolean	hasImpl(Class api) Tests if a specific interface can be provided.
DrbNode	insertChild(DrbNode node, int index) Inserts a child at a given position.
XsdInvalid	isDeepValid() Check the conformance of a node and its children to its type.
XsdInvalid	isValid() Check the conformance of a node to its type.
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 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.
String	toString() This object (which is already a string!) is itself returned.

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

createAttribute, createNode, flush, getProvider

Methods inherited from class fr.gael.drb.DrbAbstractNode

allowsMultiOccurrence, appendReference, equals, getAttribute, getItemType, getOccurrence, getRoot, getXPathName, setNamespaceBindings

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

Methods inherited from interface fr.gael.drb.DrbNode

appendChild, insertChild, removeChild, replaceChild, setAttributes, setNamespaceURI

Methods inherited from interface fr.gael.drb.DrbItem

getItemType, rename

Field Detail

baseNode

protected DrbNode baseNode

The baseNode node.

Constructor Detail

XsdNodeImpl

protected XsdNodeImpl(XsdNodeImpl parent,
                      DrbNode base,
                      XsdType type)

Build an DrbNodeFilter instance.

Parameters:

parent - the parent node

base - the base node

type - XsdType

Method Detail

getInstance

public static XsdNode getInstance(DrbNode base,
                                  XsdType type)

Create an XsdNode instance.

Parameters:

base - the base node

type - XsdType

Returns:

XsdNode

getType

public XsdType getType()

Returns the type of this node or null if it is unknown.

Returns:

XsdType

isValid

public XsdInvalid isValid()

Check the conformance of a node to its type.

Specified by:

isValid in interface XsdNode

Returns:

an object describing the errors encoutered or null if there are no errors.

isDeepValid

public XsdInvalid isDeepValid()

Check the conformance of a node and its children to its type.

Returns:

an object describing the errors encoutered or null if there are no errors.

getAttributes

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

getParent

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

getInstance

protected fr.gael.drb.xsd.DrbNodeFilter getInstance(DrbNode node)

Builds a XSD implementation from a base node.

Parameters:

node - the node

Returns:

DrbNode

getPreviousSibling

public final DrbNode getPreviousSibling()

Previous sibling of the current file or directory. The sibling is retreived from the parent children list. The previous sibling may not exist if the current node is the root or if it is the first file or directory.

Returns:

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

getNextSibling

public final DrbNode getNextSibling()

Next sibling of the current file or directory. The sibling is retreived from the parent children list. The next sibling may not exist if the current node is the root or if it is the last file or directory.

Returns:

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

toString

public String toString()

This object (which is already a string!) is itself returned.

Overrides:

toString in class DrbAbstractNode

Returns:

String

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

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.

main

public static void main(String[] args)
                 throws Exception

Makes this class runnable for testing.

Parameters:

args - String[]

Throws:

Exception

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

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

public 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

public 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

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.

Specified by:

getNamespaceURI in interface DrbItem

Returns:

The namspace URI or null if unspecified.

getValueType

public 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

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

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.

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.

Returns:

The list of children if any null otherwise.

hasChild

public 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

public 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

public 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

public 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

public 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

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

getBase

public DrbNode getBase()

Returns the DrbNode baseNode.

Returns:

DrbNode

close

public void close(boolean deep)

Closes this node and releases any system resources associated with the pointed file. A closed node cannot perform input or output operations and cannot be reopened.

Overrides:

close in class DrbNodeImpl

Parameters:

deep - if this flag is disabled,the implementation shall not release the ressources shared with the descendants.

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

Overrides:

getName in class DrbAbstractNode

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

Overrides:

getXPathName in class DrbAbstractNode

Returns:

The name of the node.

getPath

public String getPath()

The full path of the node. The full path is the full path of the parent node to witch 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.

Overrides:

getPath in class DrbAbstractNode

Returns:

The absolute path of the current 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.

Overrides:

getIndex in class DrbAbstractNode

Returns:

The index of the node or negative value.

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.

Overrides:

getNamespaceURI in class DrbAbstractNode

Returns:

The namspace URI or null if unspecified.

getNamespaceBindings

public Namespace getNamespaceBindings()

Get the namespace bindings.

Overrides:

getNamespaceBindings in class DrbAbstractNode

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.

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.

hasChild

public final boolean hasChild()

Checks if any child exists. Returns wheter the current node has at least a child.

Overrides:

hasChild in class DrbAbstractNode

Returns:

true if this node has any children, false otherwise.

getNamedChild

public DrbNode getNamedChild(String name,
                             int occurence)

Returns an occurence of child matching a specific name. The occurence number starts from 1.

Overrides:

getNamedChild in class DrbAbstractNode

Parameters:

name - The name to match.

occurence - The occurence number of the desired child.

Returns:

A reference to the child or null is not found.

getFirstChild

public final DrbNode getFirstChild()

Reference to the first child of the current node (directory). If the current node has no child a null reference is returned.

Overrides:

getFirstChild in class DrbAbstractNode

Returns:

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

getLastChild

public final DrbNode getLastChild()

Reference to the last child of the current node (directory). If the current node has no child a null reference if returned.

Overrides:

getLastChild in class DrbAbstractNode

Returns:

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

getChildAt

public final DrbNode getChildAt(int index)

Reference to a specific child of the current node (directory). The child is identified by its position (i.e. index or sequence number) in the children list of this node.

Overrides:

getChildAt in class DrbAbstractNode

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.

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.

getContent

public DrbSequence getContent()

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

Overrides:

getContent in class DrbAbstractNode

Returns:

The content of this node.

getChildrenCount

public final int getChildrenCount()

Number of files or directory hold by the current node (directory). Returns the number of children belonging to the current node.

Overrides:

getChildrenCount in class DrbAbstractNode

Returns:

The number of children of the current node (directory).

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.

Overrides:

rename in class DrbAbstractNode

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.

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 may be 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

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

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

Overrides:

insertChild in class DrbAbstractNode

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

Overrides:

appendChild in class DrbAbstractNode

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

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

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 is raised when the implementation does not support the requested removal for any reason.

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.