com.borland.primetime.node
Class Node

java.lang.Object
  |
  +--com.borland.primetime.node.Node

Direct Known Subclasses:

LightweightNode, UrlNode

public abstract class Node

extends java.lang.Object

implements java.lang.Comparable

Node is an abstract parent of all node types supported by the node system. Project, FileNode, and LightweightNode are its immediate descendants, and all other nodes should derive from one of these three types.

All nodes share a number of common public characteristics. All nodes except project nodes have an associated project which is invariant for the lifetime of the node object. With the exception of project nodes, whose parent is always null, all nodes may also have a parent node. All nodes may have zero or more immediate children, and any node may list an entirely different set of "display children" for browsing purposes. Nodes have an icon, a short and long display name, and a natural grouping sequence for sorting purposes. Lastly, all nodes can store an unlimited number of named, categorized property values.

See Also:

Project, FileNode, LightweightNode

Field Summary

static Node[]	EMPTY_ARRAY
protected java.util.ArrayList	nodeListeners

Method Summary

void	addNodeListener(NodeListener listener)
void	check() Performs any periodic task required to keep the node's state up to date.
int	compareTo(java.lang.Object other) Provides a node ordering for display purposes.
void	dumpNodes() Provided for debugging purposes.
void	dumpNodes(boolean useDisplayChildren) Provided for debugging purposes.
void	dumpNodes(java.lang.String indent, boolean useDisplayChildren) Provided for debugging purposes.
boolean	equals(java.lang.Object other)
void	fireNodeRenamed() Notifies all registered NodeListeners that this node has been renamed.
Node[]	getChildren() Returns a collection of all nodes that list this node as their parent, sorted in an order suitable for display.
Node[]	getDisplayChildren() Returns a collection of nodes that should be displayed beneath this node in a project browser, sorted in an order suitable for display.
abstract javax.swing.Icon	getDisplayIcon() Provides an image to be used for graphical representation of the node.
abstract java.lang.String	getDisplayName()
int	getDisplaySequence() Describes the logical group the node belongs to for ordering purposes.
java.lang.String	getLongDisplayName()
int	getNodeID() Returns a node's internal unique node ID.
Node	getParent() Returns the node's immediate parent in the node hierarchy.
Project	getProject() Returns a reference to the project associated with this node.
java.util.SortedMap	getProperties() Returns a Map relating NodePropertyDescriptor instances to property values.
java.lang.String	getProperty(java.lang.String property) Gets a categorized string property value associated with the node as stored in the project file using an assumed category of "sys" and a default value of null.
java.lang.String	getProperty(java.lang.String property, java.lang.String defaultValue) Gets a categorized string property value associated with the node as stored in the project file using an assumed category of "sys".
java.lang.String	getProperty(java.lang.String category, java.lang.String property, java.lang.String defaultValue) Gets a categorized string property value associated with the node as stored in the project file.
boolean	hasChildren() Describes whether or not this node has one or more children.
boolean	hasDisplayChildren() Describes whether or not this node has one or more display children.
int	hashCode()
boolean	isModified() Describes the modified state of the node's underlying storage.
boolean	isPersistant() Determines whether or not the node definition and its properties will be saved with in a project file.
void	removeNodeListener(NodeListener listener)
void	setParent(Node parent) Changes the parent of a node to alter the node hierarchy.
void	setProperty(java.lang.String property, java.lang.String value) Sets a categorized string property value associated with the node for subsequent storage with the project file using an assumed default value of null and a category of "sys".
void	setProperty(java.lang.String category, java.lang.String property, java.lang.String value) Sets a categorized string property value associated with the node for subsequent storage with the project file using an assumed default value of null.
void	setProperty(java.lang.String category, java.lang.String property, java.lang.String value, java.lang.String defaultValue) Sets a categorized string property value associated with the node for subsequent storage with the project file.
java.lang.String	toString()

Methods inherited from class java.lang.Object

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

Field Detail

EMPTY_ARRAY

public static final Node[] EMPTY_ARRAY

nodeListeners

protected java.util.ArrayList nodeListeners

Method Detail

getDisplayIcon

public abstract javax.swing.Icon getDisplayIcon()

Provides an image to be used for graphical representation of the node.

Returns:

An Icon instance.

getDisplayName

public abstract java.lang.String getDisplayName()

getLongDisplayName

public java.lang.String getLongDisplayName()

getDisplaySequence

public int getDisplaySequence()

Describes the logical group the node belongs to for ordering purposes. Nodes are divided into groups, then sorted by name within a group of nodes sharing the same grouping value. The groups themselves are ordered by grouping value, with lower numbers appearing earlier. Arbitrary numbers have been chosen to sort nodes in JBuilder as follows: Projects = 100, Folders = 200, Packages = 300, the default = 400, FileNodes = 500, ClassFileNodes = 600.

Returns:

An integer value specifying a grouping value.

getProject

public Project getProject()

Returns a reference to the project associated with this node.

Returns:

A project reference.

isModified

public boolean isModified()

Describes the modified state of the node's underlying storage. Nodes that are not associated with any physical storage are always considered to be unmodified since they have no independant state to preserved, only properties which are saved as a part of the project node.

Returns:

Always false.

getNodeID

public int getNodeID()

Returns a node's internal unique node ID. This is value that does not change during the lifetime of the object and is never visible to the user but may be used for purposes where an unchanging orderable value is required.

Returns:

An integer identifier unique within the node's project.

check

public void check()

Performs any periodic task required to keep the node's state up to date. For example, the check method is invoked every time a viewer displaying the node's contents is activated, giving the node a chance to check for changes to the physical storage it represents.

dumpNodes

public void dumpNodes(java.lang.String indent,
                      boolean useDisplayChildren)

Provided for debugging purposes.

dumpNodes

public void dumpNodes(boolean useDisplayChildren)

Provided for debugging purposes.

dumpNodes

public void dumpNodes()

Provided for debugging purposes.

getParent

public Node getParent()

Returns the node's immediate parent in the node hierarchy.

Returns:

The node's parent, or null if no parent is defined.

setParent

public void setParent(Node parent)

Changes the parent of a node to alter the node hierarchy.

WARNING: The parent of a node must not in turn be a child of the same node. Loops in the child hierarchy can lead to endless loops at run time. When necessary, distinguish between getDisplayChildren and getChildren by using the former to return the list of conceptual children that may violate this rule.

Parameters:

parent - The new parent for this node. The parent must belong to the same project as this node.

getChildren

public Node[] getChildren()

Returns a collection of all nodes that list this node as their parent, sorted in an order suitable for display.

Returns:

An array of Node instances, or an empty array if no such nodes exist.

hasChildren

public boolean hasChildren()

Describes whether or not this node has one or more children.

Returns:

True if the node has one or more children, false otherwise.

getDisplayChildren

public Node[] getDisplayChildren()

Returns a collection of nodes that should be displayed beneath this node in a project browser, sorted in an order suitable for display. The nodes listed are not guaranteed to list this node as their parent, and as a result a complete recursive traversal of display children may result in endless loops.

By default, a nodes display children are the same as its actual children. Subclasses may decide to augment this list or replace it altogether.

Returns:

An array of Node instances, or an empty array if no such nodes exist.

hasDisplayChildren

public boolean hasDisplayChildren()

Describes whether or not this node has one or more display children.

Returns:

True if the node has one or more display children, false otherwise.

isPersistant

public boolean isPersistant()

Determines whether or not the node definition and its properties will be saved with in a project file. A node must have a persistant parent to be persistant.

Returns:

True if the node should be saved, false otherwise.

getProperty

public java.lang.String getProperty(java.lang.String category,
                                    java.lang.String property,
                                    java.lang.String defaultValue)

Gets a categorized string property value associated with the node as stored in the project file.

Parameters:

category - the name of the category that the property belongs to.

property - the property name for which a value is desired.

defaultValue - the value to return if no value currently exists.

getProperty

public java.lang.String getProperty(java.lang.String property,
                                    java.lang.String defaultValue)

Gets a categorized string property value associated with the node as stored in the project file using an assumed category of "sys".

Parameters:

property - the property name for which a value is desired.

defaultValue - the value to return if no value currently exists.

getProperty

public java.lang.String getProperty(java.lang.String property)

Gets a categorized string property value associated with the node as stored in the project file using an assumed category of "sys" and a default value of null.

Parameters:

property - the property name for which a value is desired.

setProperty

public void setProperty(java.lang.String category,
                        java.lang.String property,
                        java.lang.String value,
                        java.lang.String defaultValue)

Sets a categorized string property value associated with the node for subsequent storage with the project file.

Parameters:

category - the name of the category that the property belongs to.

property - the property name for which a value is to be stored.

value - the value to be stored.

defaultValue - the value for which no storage is necessary.

setProperty

public void setProperty(java.lang.String category,
                        java.lang.String property,
                        java.lang.String value)

Sets a categorized string property value associated with the node for subsequent storage with the project file using an assumed default value of null.

Parameters:

category - the name of the category that the property belongs to.

property - the property name for which a value is to be stored.

value - the value to be stored.

setProperty

public void setProperty(java.lang.String property,
                        java.lang.String value)

Sets a categorized string property value associated with the node for subsequent storage with the project file using an assumed default value of null and a category of "sys".

Parameters:

property - the property name for which a value is to be stored.

value - the value to be stored.

getProperties

public java.util.SortedMap getProperties()

Returns a Map relating NodePropertyDescriptor instances to property values. This mechanism is used by ProjectStorage implementations to iterate over all defined properties for a node.

Returns:

A SortedMap instance.

addNodeListener

public void addNodeListener(NodeListener listener)

removeNodeListener

public void removeNodeListener(NodeListener listener)

fireNodeRenamed

public void fireNodeRenamed()

Notifies all registered NodeListeners that this node has been renamed.

compareTo

public int compareTo(java.lang.Object other)

Provides a node ordering for display purposes.

Specified by:

compareTo in interface java.lang.Comparable

equals

public boolean equals(java.lang.Object other)

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object