fr.gael.drb.impl.file
Class FileNode

java.lang.Object
  fr.gael.drb.DrbDefaultNodesChangeProducer
      fr.gael.drb.DrbAbstractNode
          fr.gael.drb.impl.DrbNodeImpl
              fr.gael.drb.impl.file.FileNode

All Implemented Interfaces:

DrbMutableNode, DrbNode, DrbNodesChangeListener, DrbNodesChangeProducer, EventListener

public final class FileNode
extends DrbNodeImpl

File or Directory of a local file system. This implementation breaks down the local file system into file and directories. It is useful to browse the local file system as a file manager. The file nodes have no specific attribute.

Thread safe strategy: This class is thread safe. The strategy to prevent access collisions between two or more treads, all the writting accesses to the ressources (i.e. attributes of this class) that may be changed by a thread are synchronised. Only the accesses occurring after the constructor are affected by this rule.

Field Summary

Fields inherited from interface fr.gael.drb.DrbItem

ATTRIBUTE_ITEM, NODE_ITEM, UNDEFINED_ITEM, VALUE_ITEM

Method Summary

boolean	allowsMultiOccurrence() Check if this node may have multiple occurrence
DrbNode	appendChild(DrbNode node) Appends a child to the current node.
void	close(boolean deep) Closes this node and releases any system resources associated with the implementation.
protected FileNode	createNewFile(String file_name) Creates a new file as children of the current directory.
DrbNode	createNode(String name) Create a node with the specified name.
boolean	equals(Object obj) Indicates whether this node is "equal to" to another node.
DrbAttributeList	getAttributes() The attributes of the node.
DrbNode	getChildAt(int index) Reference to a specific child.
DrbNodeList	getChildren() Returns the children list of the current directory.
int	getChildrenCount() Number of files or directory hold by the current node (directory).
Object	getImpl(Class api) Returns a specific implementation of the node.
int	getIndex() Returns the index of the file in the parent children list.
String	getName() Returns the name of the wrapped file.
DrbNode	getNamedChild(String name, int occurence) Returns an occurence of child matching a specific name.
String	getNamespaceURI() The file namespace.
DrbNode	getParent() Returns the parent file.
String	getPath() Returns the absolute path of the file.
DrbProvider	getProvider() Returns the provider of this file.
DrbNode	getRoot() Returns the root node of the current node.
Value	getValue() The value of the node.
int	getValueType() The value type of the file.
boolean	hasChild() Checks if any child exists.
boolean	hasImpl(Class api) Tests if a specific implementation is supported.
DrbNode	insertChild(DrbNode node, int index) Inserts a child to the current node children list.
void	removeChild(int index) Removes a file from the children list.
void	rename(String name) Changes the name of the node.
DrbNode	replaceChild(int index, DrbNode node) Replaces a child of the current node.
void	setNamespaceURI(String namespace_uri) The namespace of a file cannot be changed.
Value	setValue(Value value) Sets the value pf a file.
String	toString() Overrides the default string representation.

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

createAttribute, flush

Methods inherited from class fr.gael.drb.DrbAbstractNode

appendReference, getAttribute, getContent, getFirstChild, getItemType, getLastChild, getNamespaceBindings, getNextSibling, getOccurrence, getPreviousSibling, getXPathName, getXPathName, setAttributes, 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

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 DrbAbstractNode

Parameters:

obj - another value.

Returns:

true if this object is the same as the obj argument

allowsMultiOccurrence

public boolean allowsMultiOccurrence()

Check if this node may have multiple occurrence

Overrides:

allowsMultiOccurrence in class DrbAbstractNode

Returns:

Always return true since filenames shall be unique within a directory.

close

public void close(boolean deep)

Closes this node and releases any system resources associated with the implementation. 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. WARNING: This parameter is not fully supported.

getProvider

public DrbProvider getProvider()

Returns the provider of this file.

Overrides:

getProvider in class DrbNodeImpl

Returns:

DrbProvider

getName

public final String getName()

Returns the name of the wrapped file. This name is the basename of the file without absolute or relative component of the path. This operation wraps the java.io.File.getName() operation. The returned reference cannot be null but the string may be empty (i.e. ""). This may occur for UNIX root nodes that have no specific name.

Synchronisation note: no synchronisation performed.

Overrides:

getName in class DrbAbstractNode

Returns:

The file name in the local file system.

getIndex

public final int getIndex()

Returns the index of the file in the parent children list. If the current node is a root node it has no parent and its index is 0. This consideration (i.e. index = 0) may not be true for Windows or DOS file systems that have several root nodes.

Synchronisation note: The accesses to the cache of parent children are synchronized.

Overrides:

getIndex in class DrbAbstractNode

Returns:

Index of the file within is parent children list or -1 in case of node inconsitcency.

getRoot

public final DrbNode getRoot()

Returns the root node of the current node. The root node determination is performed by looking recursively for the parents from the current node. This strategy has been selected because some file system such as Windows or DOS have several root nodes. It was necessary to retreive the root node holding the current node.

Synchronisation note: no synchronisation performed.

Overrides:

getRoot in class DrbAbstractNode

Returns:

A reference to the root node of the current one.

getPath

public final String getPath()

Returns the absolute path of the file. Because file implementation relies directly on the file system, this operation delegates the path generation to the wrapped file. The returned path is a canonical path (unique for with for instance removal redundant names such as "." or ".." from the path). Because file system queries are required to process the path and because that queries may fail (for example because of permissions). In such case the operation returns null without exception.

Synchronisation note: the entire operation is synchronized.

Overrides:

getPath in class DrbAbstractNode

Returns:

The canonical path of the wrapped file.

getNamespaceURI

public final String getNamespaceURI()

The file namespace. Basically, until a schema has not been affected to the files tree, no namespace is attached to its nodes. Thus, because the support of schema definition attached to the node is not supported, null is returned systematically.

Overrides:

getNamespaceURI in class DrbAbstractNode

Returns:

null.

getValueType

public final int getValueType()

The value type of the file. The files have a binary content while directories have child nodes only.

Overrides:

getValueType in class DrbAbstractNode

Returns:

NULL_ID for directories and BINARY_ID for files.

getValue

public final Value getValue()

The value of the node. The content of the file is always represented by a binary value.

Overrides:

getValue in class DrbAbstractNode

Returns:

the content of the file as a binary value or null for directories.

getAttributes

public final DrbAttributeList getAttributes()

The attributes of the node. The file nodes have no specific attribute and this operation returns therefore a null value at each call. The attributes are:

The following table specifies the attributes that are available for a file. No atribute is provided optionally. The type of the attribute are expressed using the type identifer of the fr.gael.drb.value.Value class.

Name	Description	Value Type
size	the length of the file in bytes. If the file is a directory, the size is equal to 0.	UNSIGNED_LONG_ID
modified	the date the file was last modified.	DATE_ID
readable	true whether the application can read the file. false otherwise.	BOOLEAN_ID
writable	true whether the application can write the file. false otherwise.	BOOLEAN_ID
hidden	true whether the file is hidden. false otherwise.	BOOLEAN_ID

Synchronisation note: the accesses to the file are synchronized.

Overrides:

getAttributes in class DrbAbstractNode

Returns:

the lsit of attributes of the file.

getParent

public final DrbNode getParent()

Returns the parent file. A file or directory of a file system has a parent but the apart the root node.

Specified by:

getParent in class DrbAbstractNode

Returns:

A reference to the parent file if any or null otherwise.

getChildren

public final DrbNodeList getChildren()

Returns the children list of the current directory. If the current node does not wrap a directory or if it has no child, the returned reference may be null. This implementation returns a reference to a DrbDefaultNodeList.

Specified by:

getChildren in class DrbAbstractNode

Returns:

The list of children or null otherwise.

hasChild

public final boolean hasChild()

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

Overrides:

hasChild in class DrbAbstractNode

Returns:

true if this node has any children, false otherwise.

getChildAt

public DrbNode getChildAt(int index)

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

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.

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.

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

hasImpl

public final boolean hasImpl(Class api)

Tests if a specific implementation is supported. The current implementation supports : FileInputStream, FileOutputStream, RandomAccessFile and java.io.File implementation.

Overrides:

hasImpl in class DrbNodeImpl

Parameters:

api - The requested implementation.

Returns:

true if the implementation is supported and false otherwise.

See Also:

FileInputStream, FileOutputStream, RandomAccessFile, File

getImpl

public final Object getImpl(Class api)

Returns a specific implementation of the node. Only regular file (i.e. difference from directory) have specific implementations. The possible implementations are FileInputStream, FileOutputStream, RandomAccessFile or java.io.File. The returned implementation are instanciated from the Java File embedded in the current node implementation. They are completely disconnected from the current node and can be considered has effective Java implementation and any reference to the current node can be dismissed. The RandomAccessFile is opened in read and write mode.

Overrides:

getImpl in class DrbNodeImpl

Parameters:

api - The requested implmentation.

Returns:

A reference to the reqested implementation is supported or null otherwise.

See Also:

FileInputStream, FileOutputStream, RandomAccessFile, File

toString

public final String toString()

Overrides the default string representation. This operation wraps the getName() to the toString(). It is not part of the DrbNode implementation but easethe use of the file nodes in standard Java API such as printing, persistency, etc.

Overrides:

toString in class DrbAbstractNode

Returns:

The name of the file node.

appendChild

public DrbNode appendChild(DrbNode node)
                    throws UnsupportedOperationException

Appends a child to the current node. Because the children of the filesystem has its self operdering strategy, (i.e. lexicographical order of files and directories first), this operation is a wrapper to the addChild() operation. The index of the resulting children may therefore not be inserted at the end of the children list.

Please refer to the addChild operation to known which events are fired and in which cases exceptions are thrown.

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 always differs from the inpt one.

Throws:

UnsupportedOperationException - This exception is raised when the current node is not a directory or if it does not allows to remove the file for security reasons (e.g. file permissions).

insertChild

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

Inserts a child to the current node children list. Because the children of the filesystem has its self operdering strategy, (i.e. lexicographical order of files and directories first), this operation is a wrapper to the addChild() operation. The index of the resulting children may therefore be different from the requested one.

Please refer to the addChild operation to known which events are fired and in which cases exceptions are thrown.

Specified by:

insertChild in interface DrbNode

Overrides:

insertChild in class DrbAbstractNode

Parameters:

node - A reference to the node to be inserted.

index - Has no effect in this implementation.

Returns:

A reference to the effectively inserted node. This reference always differs from the input one in this implementation.

Throws:

UnsupportedOperationException - This exception is raised when the current node is not a directory or if it does not allows to remove the file for security reasons (e.g. file permissions).

removeChild

public void removeChild(int index)
                 throws IndexOutOfBoundsException,
                        UnsupportedOperationException

Removes a file from the children list. This operation removes the file or directory located at the given index. It fails when the current node is not writable or if the index is out of bound.

Events: This operation fires a node change even. 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.

Warning: The reference to the removed child in the fired event enable to re-create the same file, but its contents is definitely lost.

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 current node is not a directory or if it does not allows to remove the file for security reasons (e.g. file permissions).

rename

public void rename(String name)
            throws NullPointerException,
                   UnsupportedOperationException

Changes the name of the node. This operation is allowed only if the wrapped file can be renamed. See the java.io.File class for more information about right persmissions.

Events: his operation fires a node change event. 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 wrapped file cannot be renamed.

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

replaceChild

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

Replaces a child of the current node. This operation removes first the child at the given index and replace it by the new one. These actions are performed by the removeChild() and addChild() actions of the present class.

Please refer to the addChild() and removeChild() operations to known which events are fired and in which cases exceptions are thrown.

Warning: Event if a minimal checking is performed before removing the child (i.e. shall be a regular file because other addings are not supported), the corresponding file may be lost if the addChild() aborts.

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

node - A reference to the node to be appended.

index - the index of the node

Returns:

A reference to the effectivelly appended node. This reference always differs from the inpt one.

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 addChild() operations has raised it.

setNamespaceURI

public void setNamespaceURI(String namespace_uri)
                     throws NullPointerException,
                            UnsupportedOperationException

The namespace of a file cannot be changed.

Specified by:

setNamespaceURI in interface DrbNode

Overrides:

setNamespaceURI in class DrbAbstractNode

Parameters:

namespace_uri - the uri name

Throws:

UnsupportedOperationException - Always raised.

NullPointerException - This exception is raised when the name is null

setValue

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

Sets the value pf a file. The file contents is replaced by the passed value. This is possible only if the file is a regular file.

Specified by:

setValue in interface DrbNode

Overrides:

setValue in class DrbAbstractNode

Parameters:

value - A reference to the value to write.

Returns:

The input value.

Throws:

NullPointerException - This exception is raised when the value parameter is null.

ClassCastException - This exception is never raised.

UnsupportedOperationException - This exception is raised when the file is not a regular file or if an error occurs because of security reasons.

createNode

public DrbNode createNode(String name)
                   throws NullPointerException,
                          UnsupportedOperationException

Create a node with the specified name.

Overrides:

createNode in class DrbNodeImpl

Parameters:

name - The expected name of the node.

Returns:

A reference to the new file node.

Throws:

NullPointerException - This exception is raised when the name provided in parameter is null.

UnsupportedOperationException - This exception is raised when the implementation is not able to create a node.

createNewFile

protected FileNode createNewFile(String file_name)
                          throws NullPointerException,
                                 UnsupportedOperationException,
                                 IOException,
                                 SecurityException

Creates a new file as children of the current directory. A new file is created with the passed file name. This operation is possible only if the current node wraps a directory and if it has the correcte write permissions. The provided name shall not already be used as name of an existing file in the current directory.

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

Parameters:

file_name - The expected name of the file.

Returns:

A reference to the new file node.

Throws:

NullPointerException - This exception is raised when the name provided in parameter is null.

UnsupportedOperationException - This exception is raised when the current node is node a directory.

IOException - This exception is raised when the new file cannot be created in the current directory.

SecurityException - This exception is raised when a security manager exists and its SecurityManager.checkWrite (java.io.FileDescriptor) method denies write access to the file be created in the current directory.