org.sape.carbon.core.config.node
Class AbstractNode

java.lang.Object
  |
  +--org.sape.carbon.core.config.node.AbstractNode

All Implemented Interfaces:

Node

Direct Known Subclasses:

AbstractConfigurationDocument, AbstractFolder

public abstract class AbstractNode

extends Object

implements Node

Abstract implementation of the Node interface. This implementation is designed to be extended with the logic specific to the backing data store placed in the destroyBackingData method. Copyright 2002 Sapient

Since:

carbon 1.0

Version:

$Revision: 1.29 $($Author: dvoet $ / $Date: 2003/12/11 18:43:31 $)

Author:

Douglas Voet, February 2002

Field Summary

private Object	addOrLoadChildLock This lock is used to ensure that nodes are not added or loaded concurrently.
protected Map	childNodes Map of child Nodes keyed by the Node's name (String).
private org.apache.commons.logging.Log	log Provides a handle to Apache-commons logger
private String	name this Node's name
protected Set	nodeListeners Contains the list of node listeners for this node.
private Node	parent link to the Node's parent
private Object	readOrAlterNodeLock This object is syncrhonized upon whenever this node's state is read or altered.
private boolean	removed this node's removed status

Fields inherited from interface org.sape.carbon.core.config.node.Node

DELIMITER

Constructor Summary

AbstractNode(Node parent, String name)
Constructor

AbstractNode(Node parent, String name, Object readOrAlterNodeLock, Object addOrLoadChildLock)
Constructor

Method Summary

void	addNodeListener(ConfigurationEventListener listener) Method addNodeListener.
void	addNodeListener(EventListener listener)
void	addNodeListener(NodeEventListener listener) Method addNodeListener.
protected abstract boolean	backingDataExists() Method called from the refresh method to see if the backing data still exists.
boolean	containsChild(String childName) Checks if this Folder contains the child specified by childName
protected abstract void	destroyBackingData() This method is called by remove to destroy the data backing this node in the data source.
Node	fetchChild(String childName) synchronized to ensure no one is adding or removing children while childName is being fetched
Node[]	fetchChildren() Returns an array of all children nodes, including standard ConfigurationDocuments and Folder.
String	getAbsoluteName() This implementation is recursive.
protected Object	getAddOrLoadChildLock() Gets the lock object to synchronized upon when creating new children or loading existing children.
protected abstract Set	getAllChildNames() Called by fetchChildren to get the names of all the children from the backing data store.
boolean	getAllowsChildren() Allows determination of whether or not this node supports children
String	getName() Returns the name of this node.
Node	getParent() Gets the parent folder of the node.
protected Object	getReadOrAlterNodeLock() Gets the lock object to synchronize upon when reading or altering the removed flag or the childNodes Map.
boolean	isRemoved() Used to tell whether or not the backing data of a node has been removed.
protected void	issueChildLoadedEvent(Node child) Notifies all listenters that a child of this node has been loaded.
protected void	issueNodeRemovedEvent() Notifies all listenters that this node has been removed.
protected abstract Node	loadChild(String nodeName) Loads the child specified by nodeName from the backing data store.
void	refresh() This implementation refreshes all children and toggles the isRemoved flag depending on the return value of the backingDataExists method.
int	remove() Permanently deletes the node and all of its child nodes from the backing store returning the total number of nodes deleted.
protected void	removeRemovedChildren() Removes all nodes from this.childNodes for which isRemoved returns true.
protected void	setRemoved() Sets the node state to be removed.
String	toString() Returns the name of the node.

Methods inherited from class java.lang.Object

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

Field Detail

log

private org.apache.commons.logging.Log log

Provides a handle to Apache-commons logger

name

private final String name

this Node's name

parent

private final Node parent

link to the Node's parent

removed

private boolean removed

this node's removed status

addOrLoadChildLock

private final Object addOrLoadChildLock

This lock is used to ensure that nodes are not added or loaded concurrently. Any time a node is put into childNodes, this lock guarantees that the node is constructed once and only once. addOrLoadChildLock is usually used in conjunction with a lock on this. A lock on addOrLoadChildLock keeps other threads from loading or adding new nodes while a lock on this ensures that access to childNodes is thread-safe.

readOrAlterNodeLock

private final Object readOrAlterNodeLock

This object is syncrhonized upon whenever this node's state is read or altered. The state of this node includes the removed flag and the childNodes map, but not children themselves. State does not include this node's name or parent as these references are final. State also does not include the nodeListeners set as it synchronizes itself.

childNodes

protected final Map childNodes

Map of child Nodes keyed by the Node's name (String). Final because the reference to the map should never change for this node.

nodeListeners

protected final Set nodeListeners

Contains the list of node listeners for this node.

Constructor Detail

AbstractNode

public AbstractNode(Node parent,
                    String name)

Constructor

Parameters:

parent - the node's parent

name - the node's name

Throws:

InvalidParameterException - if name is null

AbstractNode

public AbstractNode(Node parent,
                    String name,
                    Object readOrAlterNodeLock,
                    Object addOrLoadChildLock)

Constructor

Parameters:

parent - the node's parent

name - the node's name

readOrAlterNodeLock - the lock object that will be synchronized upon for all operations that access or modify this node's state

Throws:

InvalidParameterException - if name is null or readOrAlterNodeLock is null

Method Detail

getName

public String getName()

Description copied from interface: Node

Returns the name of this node. The name should not include the node's relation to the node heirarchy. The name can not contain a '/'. The name of the root node is an empty String("").

Specified by:

getName in interface Node

Returns:

name of the node

See Also:

Node.getName()

getParent

public Node getParent()

Description copied from interface: Node

Gets the parent folder of the node.

Specified by:

getParent in interface Node

Returns:

Folder the parent folder, null if this node is the root

See Also:

Node.getParent()

getAbsoluteName

public String getAbsoluteName()

This implementation is recursive. If the parent is not null, it returns the parent's absolute name followed by Node.DELIMITER and this node's name

Specified by:

getAbsoluteName in interface Node

Returns:

Absolute name of the node.

See Also:

Node.getAbsoluteName()

getAllowsChildren

public boolean getAllowsChildren()

Description copied from interface: Node

Allows determination of whether or not this node supports children

Specified by:

getAllowsChildren in interface Node

Returns:

true if the node can support children, false otherwise

See Also:

Node.getAllowsChildren()

remove

public int remove()
           throws NodeRemovalException

Description copied from interface: Node

Permanently deletes the node and all of its child nodes from the backing store returning the total number of nodes deleted.

Specified by:

remove in interface Node

Returns:

The total number of nodes deleted. This number should always be at least '1' when the operation completed successfully.

Throws:

NodeRemovalException - when the node or one of its children can not be deleted. When this exception is thrown, some nodes may have been deleted while other may have not.

See Also:

synchronized to ensure no one is fetching or adding children while this method is removing them

toString

public String toString()

Returns the name of the node.

Overrides:

toString in class Object

Returns:

the name of the node

isRemoved

public boolean isRemoved()

Description copied from interface: Node

Used to tell whether or not the backing data of a node has been removed.

Specified by:

isRemoved in interface Node

Returns:

true if the backing data of a node has been removed

See Also:

Node.isRemoved()

refresh

public void refresh()

This implementation refreshes all children and toggles the isRemoved flag depending on the return value of the backingDataExists method.

Specified by:

refresh in interface Node

See Also:

Node.refresh()

fetchChild

public Node fetchChild(String childName)
                throws NodeNotFoundException

synchronized to ensure no one is adding or removing children while childName is being fetched

Specified by:

fetchChild in interface Node

Parameters:

childName - The name of the child node to be returned.

Returns:

A child Node of the current node.

Throws:

NodeNotFoundException - when childName does not exist in the backing data store

See Also:

Node.fetchChild(String)

fetchChildren

public Node[] fetchChildren()

Description copied from interface: Node

Returns an array of all children nodes, including standard ConfigurationDocuments and Folder. If this particular node does not have any children, an array of length zero is be returned.

Specified by:

fetchChildren in interface Node

Returns:

Array of child Nodes. Never null.

See Also:

Node.fetchChildren()

containsChild

public boolean containsChild(String childName)

Description copied from interface: Node

Checks if this Folder contains the child specified by childName

Specified by:

containsChild in interface Node

Parameters:

childName - the name of the child Node

Returns:

boolean true if the child exists, false otherwise.

See Also:

synchronized to ensure no one is adding or removing children while childName is being checking to see if childName exists

addNodeListener

public void addNodeListener(EventListener listener)

See Also:

Node.addNodeListener(NodeEventListener)

addNodeListener

public void addNodeListener(NodeEventListener listener)

Description copied from interface: Node

Method addNodeListener.

Specified by:

addNodeListener in interface Node

Parameters:

listener - lister for the node

See Also:

Node.addNodeListener(NodeEventListener)

addNodeListener

public void addNodeListener(ConfigurationEventListener listener)

Description copied from interface: Node

Method addNodeListener.

Specified by:

addNodeListener in interface Node

Parameters:

listener - lister for the node

See Also:

Node.addNodeListener(ConfigurationEventListener)

destroyBackingData

protected abstract void destroyBackingData()
                                    throws NodeRemovalException

This method is called by remove to destroy the data backing this node in the data source. Implementations of this method should remove all traces of the Node's existence

Throws:

NodeRemovalException - indicates an error removing the node

getAllChildNames

protected abstract Set getAllChildNames()

Called by fetchChildren to get the names of all the children from the backing data store. If a name appears in the returned Set, calling fetchChild with the name can not result in a NodeNotFoundException being thrown.

Returns:

Set of Strings, the names of all the children

loadChild

protected abstract Node loadChild(String nodeName)
                           throws NodeNotFoundException

Loads the child specified by nodeName from the backing data store. Called by fetchChild when the child has not yet been cached.

Parameters:

nodeName - the name of the node to load

Returns:

Node the loaded node

Throws:

NodeNotFoundException - if the backing data for the specifed node could not be found in the data store.

backingDataExists

protected abstract boolean backingDataExists()

Method called from the refresh method to see if the backing data still exists. If it exists, the isRemoved flag is set to false, if it does not, the isRemoved flag is set to true.

Returns:

boolean true if the backing date exists, false otherwise

removeRemovedChildren

protected void removeRemovedChildren()

Removes all nodes from this.childNodes for which isRemoved returns true.

setRemoved

protected void setRemoved()

Sets the node state to be removed. Note that this method is not synchronized but must be called from section of code synchronized on getReadOrAlterNodeLock() object.

issueChildLoadedEvent

protected void issueChildLoadedEvent(Node child)

Notifies all listenters that a child of this node has been loaded. Note that this should be not be called from a synchronized context.

Since:

carbon 2.2

issueNodeRemovedEvent

protected void issueNodeRemovedEvent()

Notifies all listenters that this node has been removed. Note that this should be not be called from a synchronized context.

Since:

carbon 1.1

getReadOrAlterNodeLock

protected final Object getReadOrAlterNodeLock()

Gets the lock object to synchronize upon when reading or altering the removed flag or the childNodes Map.

This method is final because the design of the abstract node implementations requires that the return value of this method never change once this object is constructed. The return value can be set in one of the constructors.

Returns:

the lock object

Since:

carbon 2.1

See Also:

AbstractNode(Node, String, Object, Object)

getAddOrLoadChildLock

protected final Object getAddOrLoadChildLock()

Gets the lock object to synchronized upon when creating new children or loading existing children. This lock ensures that child nodes are created only once.

This method is final because the design of the abstract node implementations requires that the return value of this method never change once this object is constructed. The return value can be set in one of the constructors.

Returns:

the lock object

Since:

carbon 2.1

See Also:

AbstractNode(Node, String, Object, Object)