All Packages  Class Hierarchy  This Package  Previous  Next  Index

Interface uhr.core.structure.Node

public interface Node

A node is a container or leaf. A container node is the ContainerNode interface, which extendds Node. A leaf node is just the Node interface.

Responsibilites are to maintain the state that applies to the plugpoint structure only. This is the node's name, part, and parent node. That's all. The design philosophy is a Node should remain small and simple, serving only a "plugpoint structure role", with nearly no behavior.

But name, part and parent node are not enough. The systen or tool designer will eventually need to associate various properties with parts. Rather than have the part carry that data, or a custom parallel tree structure carry it, a Node has inherent and simple named properties.

Inherent properties are used by core parts or tools, and possibly a few domain parts. These are the boolean "abilities" a part has. They are isCore(), isContainer(), isInheritable(), isVirtual() and isHidden().

Custom properties are for any use and should have a key namespace. We hope we haven't opened up a Pandora's Box with custom properties. They are to be used wisely. :-)

buildPathToNode(Node, String)

Builds and returns a delimited path from this node to the toNode, using the provided delimiter.

findNodeWithProperty(String)

Finds and returns the Node with the propertyKey, starting in this node and searching upward until the root is found.

findProperty(String)

Finds and returns the property with the propertyKey, starting in this node and searching upward until the root is found.

getName()

Returns the part name.

getParent()

Returns the node's parent node or null if this is the root.

getPart()

Returns the node's part.

getProperties()

Returns the custom properties in this node.

getRootNode()

Returns the root node, which has no parent node.

isContainer()

Returns true if this is a container part or false if not.

isCore()

Returns true if this is a core part or false if not.

isHidden()

Returns true if this is a hidden part or false if not.

isInheritable()

Returns true if this is inheritable or false if not.

isRoot()

Determines whether this is the root node or not.

isVirtual()

Returns true if this is a virtual part or false if not.

setCore(boolean)

Sets whether this is a core part or not.

setHidden(boolean)

Sets whether this is a hidden part or not.

setInheritable(boolean)

Sets whether this is inheritable or not.

setName(String)

Sets the node or part name.

setParent(Container)

Sets the node's parent node.

setPart(Object)

Sets the node's part, which may be any object whatsoever.

setVirtual(boolean)

Sets whether this is a virtual part or not.

toString()

Returns a String representation of the node.

 public abstract void setName(String name)

Sets the node or part name. This must be unique per container. It must be alphanumeric, may contain periods, and must not contain blanks or slashes. It cannot be null or a zero length String. This is a required property.

The name "MyCell" is not allowed. This is reserved for use in Cell.findPart(String name).

Our convention is to capatalize the first letter of each word making up the self-documenting part name. Examples are "Root", "ControlRegistry" and "UserSecurity".

If part names are used for finding the part in other containers, then to avoid name space conflicts the names need careful design. This can achieve branch or system uniqueness. This will happen if service parts are used a lot. To support unique naming we allow periods in the name, such as "org.jcon.security.UserAuthorization".

Parameters:

name - the name of the node.

 public abstract String getName()

Returns the part name.

Returns:

the name of the part.

 public abstract void setPart(Object part)

Sets the node's part, which may be any object whatsoever. The object should be unique per container and probably unique per System Tree. This is a required property.

If the part implements NodeUser then setNode(Node) will be called, using "this" node.

Parameters:

part - the node's part.

 public abstract Object getPart()

Returns the node's part.

Returns:

the node's part.

 public abstract void setParent(Container parentNode)

Sets the node's parent node. This is required for all nodes in a tree except the root, which is null.

Parameters:

parentNode - the parent of this node or null if this is the root node.

 public abstract Container getParent()

Returns the node's parent node or null if this is the root.

Returns:

the parent of this node or null if this is the root node.

 public abstract boolean isRoot()

Determines whether this is the root node or not. The root node has no parent node.

Returns:

true if root node or false if not.

 public abstract Container getRootNode()

Returns the root node, which has no parent node.

Returns:

the root node.

 public abstract boolean isContainer()

Returns true if this is a container part or false if not.

A unique type of core part is a container. It holds other container or leaf parts. All non-container parts are leaf parts. A container part requires the other core parts to run. Thus the core parts form the "container" portion of a system. We do not call this "isCell" to allow other types of containers, such as organs.

Returns:

true if this is a container or false if not.

 public abstract void setCore(boolean isCore)

Sets whether this is a core part or not. The default is false.

Parameters:

isCore - true if this is a core part or false if not.

 public abstract boolean isCore()

Returns true if this is a core part or false if not.

Parts are divided into two groups: core and domain. Core parts are required for a System Tree to run. They are domain neutral, and are normally hidden. Domain parts are the ones supplied by the system builder, have the domain functionality, and form the bulk of a system. The use of core parts by domain parts should be minimized and fascaded to preserve core encapsulation.

Returns:

true if this is a core part or false if not.

 public abstract void setInheritable(boolean isInheritable)

Sets whether this is inheritable or not. The default is false.

Parameters:

isInheritable - true if this is inheritable or false if not.

 public abstract boolean isInheritable()

Returns true if this is inheritable or false if not.

Parts may play a "local" or "inheritable" role in their collaborations with other parts. Most parts are local, and are used via Messages or occasionally directly. Some parts play a "service" role by sitting near the upper region of a System Tree and serving the needs of many parts below by being inheritable. This is the Service Architecture Pattern, though that pattern is not limited to trees.

We recommend the use of "message services" instead of "part services" for most use. This has looser coupling.

An example of the use of isInheritable is core service parts. This allows cores that don't use Messages, gives greater speed, and allows part sharing of stateless part by many containers for efficiency. One purpose of this property is so the designer can declare that a part NOT be used as a service, which can improve cell encapsulation. Another advantage is automatic management of service parts by a service registry or such.

Returns:

true if this is inheritable or false if not.

 public abstract void setVirtual(boolean isVirtual)

Sets whether this is a virtual part or not. The default is false.

Parameters:

isVirtual - true if this is virtual or false if not.

 public abstract boolean isVirtual()

Returns true if this is a virtual part or false if not.

Parts may be normal or "virtual". Normally all parts are defined in Container DK. But virtual parts are not defined by Container DK. This allows more dynamic system behavior, less DK, and lighter system weight. An example of virtual parts is core parts in subcells below the root.

TODO - Perhaps we need a better word, but "virtual" means a part definition is hidden, and so the part appears out of nowhere. Is this property really needed?

Returns:

true if this is virtual or false if not.

 public abstract void setHidden(boolean isHidden)

Sets whether this is a hidden part or not. The default is false.

Parameters:

isHidden - true if this is hidden or false if not.

 public abstract boolean isHidden()

Returns true if this is a hidden part or false if not.

Most parts are visible in the visual System Tree tool and to "get all parts in a container" calls, etc. But the core parts (except for container) are hidden, because that would clutter up things visually, and expose them to possible misuse by non-core parts. This also helps preserve core encapsulation.

This property can be used to control the behavior of classes like "PartReader" to hide sensitive parts. (It's a little muddy because of the show container exception)

Returns:

true if this is hidden or false if not.

 public abstract Flexitron getProperties()

Returns the custom properties in this node. When a node is created these are empty.

Returns:

the Flexitron containing the properties. It is an InfotronStd.

 public abstract Object findProperty(String propertyKey)

Finds and returns the property with the propertyKey, starting in this node and searching upward until the root is found. If not found return null. RECURSIVE.

Parameters:

propertyKey - the key of interest.

Returns:

the property for the propertyKey or null if not found.

 public abstract Node findNodeWithProperty(String propertyKey)

Finds and returns the Node with the propertyKey, starting in this node and searching upward until the root is found. If not found returns null. RECURSIVE.

Parameters:

propertyKey - the key of interest.

Returns:

the node the propertyKey is in or null if not found.

 public abstract String buildPathToNode(Node toNode,
                                        String delimiter)

Builds and returns a delimited path from this node to the toNode, using the provided delimiter. This node's name is included and the toNode's name is excluded. If this node and the toNode are the same, "" is returned. Otherwise the result has a delimeter on the end.

Parameters:

toNode - the node to stop at, inclusive.

delimiter - the delimter, such as "/", to use.

Returns:

the delimted path or "" if toNode equals this node.

 public abstract String toString()

Returns a String representation of the node. The standard is the name of the node.

Returns:

a String representation of the node.

Overrides:

toString in class Object

All Packages  Class Hierarchy  This Package  Previous  Next  Index