net.sourceforge.esw.graph
Class Node

java.lang.Object
  |
  +--net.sourceforge.esw.util.SupportObject
        |
        +--net.sourceforge.esw.graph.Node

All Implemented Interfaces:

java.lang.Cloneable, ICloneable, INode, ISupportObject, java.io.Serializable

Direct Known Subclasses:

DefaultPropertySource, MetaCollection

public class Node

extends SupportObject

implements INode

Provides a universal, graph based, generic data structure.

This is the default implementation of the INode interface within the ESW framework.

This is a Node within the graph data structure.

An INode instance contains an identifer and value. It also provides a named, ordered list of children that can be accessed by either identifer or index. The index of the children is 0 based. An INode instance also contains a list of its parents within the graph structure.

The clone, equals, hashCode, and iterator methods all operate shallowly. That is, they only look to this INode instance for their operations. For deep operations on an INode instance and its children, see the net.sourceforge.esw.graph.decorators package.

Since INode inhereits ISupportObject abilities, INode methods that change any value of an INode instance must fire a PropertyChangeEvent with a property name of the property being changed.

When creating an INode implementor, you must also provide an equals and hashCode methods per the java.lang.Object's equals and hashCode method contracts. The default Object implementations do not provide a rich enough definition for equality among INode instances. It also provides a property scratchpad to store information related to this INode instance. Properties are name/value pairs.

To create an instance of this INode, see NodeFactory.createNode().

Examples:

    INode node = NodeFactory.createNode();
 

See Also:

IGraphVisitor, ISupportObject, NodeFactory, Object.equals(java.lang.Object), Object.hashCode(), Serialized Form

Field Summary

protected java.util.List	list The List instance containing this INode instance's children, in insertion order.
protected java.util.Map	map The Map instance containing this INode instance's children.
protected java.util.List	parents The List instancecontaining this INode instance's parents, in insertion order.
protected java.lang.Object	value The value of this INode instance.

Fields inherited from class net.sourceforge.esw.util.SupportObject

id, properties, propertyChildren, propertyListeners, vetoableChildren, vetoableListeners

Constructor Summary

protected

Node() Creates a new Node instance.

Method Summary

void	acceptVisitor(IGraphVisitor aVisitor) Requests that this INode instance accept the specified IGraphVisitor instance and that visiting of this INode struture begin.
void	add(INode aNode) Appends the specified INode child instance to the end of this INode instances child collection.
void	add(INode aNode, boolean bAddParent) Appends the specified INode child instance to the end of this INode instance's child collection.
void	addParent(INode aParent) Sets the parent INode instance for this INode instance.
void	clear() Removes the children from this INode instance.
java.lang.Object	clone() Creates and returns a shallow copy of this INode instance.
boolean	containsID(java.lang.Object aId) Indicates whether this INode instance contains the specified identifer as a child of this INode instance.
boolean	equals(java.lang.Object aObject) Checks for equality between this INode instance and the specified Object.
INode	get(int aIndex) Returns the INode child instance at the specified index.
INode	get(java.lang.Object aId) Returns the first INode child instance that contains specified identifer.
java.util.List	getList(java.lang.Object aId) Returns the List of INode child instances with the specified identifer.
java.util.Iterator	getParents() Returns an Iterator over the INode parent instances of this INode instance.
java.lang.Object	getValue() Returns the value of this INode instance
int	hashCode() Returns a hash code value for this INode instance.
protected int	hashCodeForNode(INode aNode) Returns the shallow hashCode for this specified INode instance.
boolean	isEmpty() Indicates whether this INode instance has no children.
java.util.Iterator	iterator() Returns an Iterator over this INode instance's children.
protected boolean	nodesEqual(INode aNodeA, INode aNodeB) Checks for equality between the two specified INode instances.
void	remove(INode aNode) Removes the INode child instance for the specified identifer from this INode instance if present.
void	removeParent(INode aParent) Removes the specified parent INode instance from this INode instance.
void	setValue(java.lang.Object aValue) Sets the value for this INode instance.
int	size() Returns the number of children in this INode instance.
java.lang.String	toString() Returns a String representation of this INode instance.

Methods inherited from class net.sourceforge.esw.util.SupportObject

addPropertyChangeListener, addPropertyChangeListener, addVetoableChangeListener, addVetoableChangeListener, firePropertyChange, firePropertyChange, fireVetoableChange, fireVetoableChange, getID, getProperty, getPropertySize, propertyKeys, removeProperty, removePropertyChangeListener, removePropertyChangeListener, removeVetoableChangeListener, removeVetoableChangeListener, setID, setProperty

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface net.sourceforge.esw.util.ISupportObject

addPropertyChangeListener, addPropertyChangeListener, addVetoableChangeListener, addVetoableChangeListener, firePropertyChange, firePropertyChange, fireVetoableChange, fireVetoableChange, getID, getProperty, getPropertySize, propertyKeys, removeProperty, removePropertyChangeListener, removePropertyChangeListener, removeVetoableChangeListener, removeVetoableChangeListener, setID, setProperty

Field Detail

value

protected java.lang.Object value

The value of this INode instance.

map

protected java.util.Map map

The Map instance containing this INode instance's children. Used for fast access by identifier.

list

protected java.util.List list

The List instance containing this INode instance's children, in insertion order. Used for fast access by position.

parents

protected java.util.List parents

The List instancecontaining this INode instance's parents, in insertion order. Used for fast access by position.

Constructor Detail

Node

protected Node()

Creates a new Node instance.

This method is proected to force creation to be performed by the NodeFactory. See Section 6.6.1 of the Java Language Specification for an explanation of why this method cannot be invoked by classes outside this package.

Method Detail

getValue

public java.lang.Object getValue()

Returns the value of this INode instance

Specified by:

getValue in interface INode

Returns:

the value of this INode instance.

See Also:

setValue(Object)

setValue

public void setValue(java.lang.Object aValue)

Sets the value for this INode instance.

Fires an INodeResources.VALUE_PROPERTY property change event.

Specified by:

setValue in interface INode

Parameters:

aValue - the value for this INode instance.

See Also:

getValue()

size

public int size()

Returns the number of children in this INode instance. If the INode contains more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE.

Specified by:

size in interface INode

Returns:

the number of children in this INode instance.

See Also:

isEmpty()

isEmpty

public boolean isEmpty()

Indicates whether this INode instance has no children.

Specified by:

isEmpty in interface INode

Returns:

true if this INode instance contains no children.

See Also:

size()

clear

public void clear()

Removes the children from this INode instance.

Fires an INodeResources.CLEAR_PROPERTY property change event only if there were children that were cleared from this INode instance.

Specified by:

clear in interface INode

containsID

public boolean containsID(java.lang.Object aId)

Indicates whether this INode instance contains the specified identifer as a child of this INode instance.

Specified by:

containsID in interface INode

Parameters:

aId - the identifer of the child INode instance for which to search.

Returns:

true if this INode instance contains the specified child.

getList

public java.util.List getList(java.lang.Object aId)

Returns the List of INode child instances with the specified identifer. The list is in insertion order: the first INode child instance added to this INode instance is the first INode child instance in the returned List instance. Returns null if this INode instance does not contain any INode child instances with the specified identifier.

The returned List instance is immutable. That is, you cannot alter the position or size of the returned List instance.

Specified by:

getList in interface INode

Parameters:

aId - identifer whose associated INode child instances are returned.

Returns:

the List of INode child instances with the specified identifer, or null if this INode contains no children with the specified identifier.

See Also:

get(Object), get(int), remove(INode), add(INode)

get

public INode get(java.lang.Object aId)

Returns the first INode child instance that contains specified identifer. Returns null if this INode instance does not contain children with specified identifer.

Specified by:

get in interface INode

Parameters:

aId - identifer whose associated INode child instances are returned.

Returns:

the first INode child instances with the specified identifer, or null if this INode instance contains no children for this identifer.

See Also:

get(int), remove(INode), add(INode)

get

public INode get(int aIndex)

Returns the INode child instance at the specified index. Indexes are 0 based.

Specified by:

get in interface INode

Parameters:

aIndex - the index of the INode child instance to return.

Returns:

the INode child instance at the specified index.

Throws:

ArrayIndexOutOfBoundsException - if there is no value at the specified index. Said differently, this INode instance's size is less than the specified index.

See Also:

get(Object), remove(INode), add(INode)

remove

public void remove(INode aNode)

Removes the INode child instance for the specified identifer from this INode instance if present.

Fires an INodeResources.REMOVE_PROPERTY property change event.

Specified by:

remove in interface INode

Parameters:

aNode - INode child instance to be removed from this INode instance.

See Also:

get(Object), get(int), add(INode)

add

public void add(INode aNode)

Appends the specified INode child instance to the end of this INode instances child collection. This method automatically adds this INode instance as a parent of the specified child INode instance.

Fires an INodeResources.ADD_PROPERTY property change event.

Specified by:

add in interface INode

Parameters:

aNode - INode child instance to be appended to this INode instance.

See Also:

add(INode, boolean), get(Object), get(int), remove(INode)

add

public void add(INode aNode,
                boolean bAddParent)

Appends the specified INode child instance to the end of this INode instance's child collection. Per the value of the boolean parameter, will add this INode instance as a parent of the specified child INode instance.

Fires an INodeResources.ADD_PROPERTY property change event.

Specified by:

add in interface INode

Parameters:

aNode - INode child instance to be appended to this INode instance.

bAddParent - if true, will add this INode instance as the parent of the specified child INode instance, if false, does not add parent link to the child.

See Also:

add(INode), get(Object), get(int), remove(INode)

addParent

public void addParent(INode aParent)

Sets the parent INode instance for this INode instance.

This method is semantically dangerous to client developers. It could put the graph structure that this INode instance belongs to into an inconsistant state. Use this method with caution.

Fires an INodeResources.PARENT_PROPERTY property change event.

Specified by:

addParent in interface INode

Parameters:

aParent - the INode parent instance to be set.

See Also:

removeParent(INode), getParents()

getParents

public java.util.Iterator getParents()

Returns an Iterator over the INode parent instances of this INode instance.

Specified by:

getParents in interface INode

Returns:

the parent INode instances for this INode instance.

See Also:

removeParent(INode), addParent(INode)

removeParent

public void removeParent(INode aParent)

Removes the specified parent INode instance from this INode instance.

Specified by:

removeParent in interface INode

Parameters:

aParent - the Parent to remove from this INode instance.

See Also:

addParent(INode), getParents()

iterator

public java.util.Iterator iterator()

Returns an Iterator over this INode instance's children. This is a shallow operation, iterating through this INode instance's children and no further child generations. If you wish deep iterators, see the net.sourceforge.esw.graph.decorators package.

Specified by:

iterator in interface INode

Returns:

an iterator over the INode child instances of this INode instance.

acceptVisitor

public void acceptVisitor(IGraphVisitor aVisitor)

Requests that this INode instance accept the specified IGraphVisitor instance and that visiting of this INode struture begin. This is a shallow operation, visiting this INode instance's children and no further child generations. If you wish deep visits, see the net.sourceforge.esw.graph.decorators package.

Specified by:

acceptVisitor in interface INode

Parameters:

aVisitor - the IGraphVisitor instance to visit the children of this INode instance.

toString

public java.lang.String toString()

Returns a String representation of this INode instance.

Overrides:

toString in class java.lang.Object

Returns:

a String representation of this INode instance.

equals

public boolean equals(java.lang.Object aObject)

Checks for equality between this INode instance and the specified Object.

The specified object must be an INode instance and be non-null.

Overrides:

equals in class java.lang.Object

Parameters:

aObject - the object for which to check equality.

Returns:

true if aObject and this INode instance are equal.

hashCode

public int hashCode()

Returns a hash code value for this INode instance.

Overrides:

hashCode in class java.lang.Object

clone

public java.lang.Object clone()

Creates and returns a shallow copy of this INode instance.

Specified by:

clone in interface ICloneable

Overrides:

clone in class java.lang.Object

Returns:

a shallow copy of this INode instance.

hashCodeForNode

protected int hashCodeForNode(INode aNode)

Returns the shallow hashCode for this specified INode instance.

Parameters:

aNode - the INode instance on which to check shallow hashCode.

nodesEqual

protected boolean nodesEqual(INode aNodeA,
                             INode aNodeB)

Checks for equality between the two specified INode instances.

Parameters:

aNodeA - the first INode instance to check for equality.

aNodeB - the second INode instance to check for equality.

Returns:

true if the two specified INode instances are equal.