gishur.graph.core
Class GraphElement

java.lang.Object
  |
  +--gishur.graph.core.GraphElement
All Implemented Interfaces:
java.lang.Cloneable, Cloneable, ControlledCloneable, KeyValueHolder, java.io.Serializable
Direct Known Subclasses:
Edge, Node

public abstract class GraphElement
extends java.lang.Object
implements KeyValueHolder, java.io.Serializable, ControlledCloneable

Abstract basic class for Node, Edge and Graph. This class provides the whole basic functionality needed to construct arbitrary Graphs.

Version:
1.0
Author:
Christoph Sachse
See Also:
Serialized Form

Field Summary
static int ACCESS_CONNECT
          Access code for a new connection between two GraphElements
static int ACCESS_REMOVE
          Access code for the removal of an existing connection between two GraphElements
static byte BOTH
          Link type constant indicating both an inward or an outward link
static int DETAILED
          A detailed info string
static byte IN
          Link type constant indicating an inward link
static byte LINK_ALL
          Link type constant indicating any other link type
static int NORMAL
          Normal info string
static byte OUT
          Link type constant indicating an outward link
static int SET_KEY
          Access code for setting a new key
static int SET_VALUE
          Access code for setting a new value
static int SHORT
          Short information (mostly only the name)
static int VERY_DETAILED
          The highest level of detail
 
Fields inherited from interface gishur.core.ControlledCloneable
DEEP, FLAT
 
Constructor Summary
protected GraphElement(java.lang.String name)
          Name constructor.
 
Method Summary
protected  void addOwner(Owner o)
          Makes this GraphElement owned by o.
protected  boolean checkAccess(int access, java.lang.Object argument)
          A method to which is called before performing any connecting operation on this GraphElement.
 boolean checkState(short state)
          Checks if the given state is identical to the internal state.
 boolean checkStateCleared(short state)
          Checks if the given state is cleared as internal state, that means that state is binary inverse to the internal state.
protected  void clearState(short state)
          Clears the given state as internal state, that means that the internal state will be set to state's inverse.
 java.lang.Object clone()
          Creates a new object of the same class as this object.
 java.lang.Object clone(java.util.Hashtable h, int level)
          Clones this object.
protected  int countConnectedElements(Graph g, byte linktype)
          Counts and returns the number of GraphElements which are connected to this one and are linked to it in the way specified by linktype.
 Flow createFlow(java.lang.String key)
          Creates, stores in the properties and returns a new Flow object with key key.
 Flow createFlow(java.lang.String key, double hicap, double locap, double flow)
          Creates, stores in the properties and returns a new Flow object with key key.
protected  GraphCursor cursor(Graph g, byte linktype)
          Creates and returns a new Cursor object which allows to scope through the GraphElements connected to this one.
protected  GraphCursor cursor(Graph g, GraphElement e, byte linktype)
          Creates and returns a new Cursor object which allows to scope through the GraphElements connected to this one.
protected  GraphElement element(Graph g, byte linktype, GraphElement e, int step)
          Returns the next step-th GraphElement from e which is linked to this one in the way specified by linktype within Graph g.
 Flow flow(java.lang.String key)
          Returns the Flow mapped to key.
 boolean getBoolProperty(java.lang.String key, boolean def)
          Method to get a property value which is not an object, but a boolean.
 double getDoubleProperty(java.lang.String key, double def)
          Method to get a property value which is not an object, but a double.
 Edge getEdgeProperty(java.lang.String key)
          Returns a property value like getProperty(java.lang.String) which is casted to Edge, if this is possible, otherwise null.
 float getFloatProperty(java.lang.String key, float def)
          Method to get a property value which is not an object, but a float.
 GraphElement getGraphElementProperty(java.lang.String key)
          Returns a property value like getProperty(java.lang.String) which is casted to GraphElement, if this is possible, otherwise null.
 int getIntProperty(java.lang.String key, int def)
          Method to get a property value which is not an object, but an int.
 long getLongProperty(java.lang.String key, long def)
          Method to get a property value which is not an object, but a long.
 Node getNodeProperty(java.lang.String key)
          Returns a property value like getProperty(java.lang.String) which is casted to Node, if this is possible, otherwise null.
 List getProperties(boolean hidden)
          Returns a List of all (not hidden) properties.
 java.lang.Object getProperty(java.lang.String key)
          Returns a property value stored for this GraphElement, specified by key.
 java.lang.Object getProperty(java.lang.String key, java.lang.Object def)
          Returns a property value stored for this GraphElement, specified by key.
 short getShortProperty(java.lang.String key, short def)
          Method to get a property value which is not an object, but a short.
 List getSortedProperties()
          Returns a sorted List of all not hidden properties.
 List getSortedProperties(boolean hidden)
          Returns a sorted List of all (not hidden) properties.
 boolean hasProperty(java.lang.String key)
          Returns true, if the properties contain the key.
protected  boolean isConnectedTo(Graph g, byte linkmask, GraphElement e)
          Checks, if e is connected to this GraphElement in the way specified by linkmask within Graph g.
 boolean isOwner(Owner o)
          Checks, if o is an Owner of this GraphElement.
 java.lang.Object key()
          Returns the stored key of the object.
protected  java.lang.String linkListToString()
          Returns the list of connected elements as a string where in each element is printed out as a SHORT string.
static java.lang.String linkTypeToString(byte linktype)
          Returns a short string representation for the basic link types.
 java.lang.String name()
          Return the name of the node
static byte opposite(byte linktype)
          Returns the opposite link type constant to linktype.
protected  java.lang.String ownerListToString()
          Returns the list of Owners of the GraphElement as a string representation.
protected  java.lang.String propertiesToString()
          Returns a string representation of the list of properties of this GraphElement.
 void removeAllProperties()
          Removes all properties of this GraphElement without its name().
 Flow removeFlow(java.lang.String key)
          Removes the Flow object identified by key from the properties and returns it.
 void removePropertiesStartingWith(java.lang.String key)
          Removes all properties whose keys are starting with substring key.
 java.lang.Object removeProperty(java.lang.String key)
          Removes the property defined by key from the stored list of properties and returns its value.
 boolean setKey(java.lang.Object key)
          Sets the key.
 void setName(java.lang.String s)
          Stets the name of the node
 void setProperty(java.lang.String key, boolean value)
          Sets a boolean-value as value.
 void setProperty(java.lang.String key, double value)
          Sets a double-value as value.
 void setProperty(java.lang.String key, float value)
          Sets a float-value as value.
 void setProperty(java.lang.String key, int value)
          Sets an int-value as value.
 void setProperty(java.lang.String key, long value)
          Sets a long-value as value.
 void setProperty(java.lang.String key, java.lang.Object value)
          Sets a property of this Node, specified by the String key to the given value.
 void setProperty(java.lang.String key, short value)
          Sets a short-value as value.
protected  void setState(short state)
          Sets the internal state to the given state.
 boolean setValue(java.lang.Object value)
          Stores the object value as value.
protected  short state()
          Returns the complete internal state.
protected  short state(short state)
          Returns the internal state for the given state constant.
 java.lang.String toString()
          Returns a DETAILED string representation of the object, as no detail level has been specified.
 java.lang.String toString(int level)
          Returns a string representing this GraphElement in a definable level of detail.
 java.lang.Object value()
          Returns the stored value.
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

ACCESS_CONNECT

public static final int ACCESS_CONNECT
Access code for a new connection between two GraphElements

ACCESS_REMOVE

public static final int ACCESS_REMOVE
Access code for the removal of an existing connection between two GraphElements

SET_KEY

public static final int SET_KEY
Access code for setting a new key

SET_VALUE

public static final int SET_VALUE
Access code for setting a new value

IN

public static final byte IN
Link type constant indicating an inward link

OUT

public static final byte OUT
Link type constant indicating an outward link

BOTH

public static final byte BOTH
Link type constant indicating both an inward or an outward link

LINK_ALL

public static final byte LINK_ALL
Link type constant indicating any other link type

SHORT

public static final int SHORT
Short information (mostly only the name)

NORMAL

public static final int NORMAL
Normal info string

DETAILED

public static final int DETAILED
A detailed info string

VERY_DETAILED

public static final int VERY_DETAILED
The highest level of detail
Constructor Detail

GraphElement

protected GraphElement(java.lang.String name)
Name constructor.
Parameters:
name - the name of the GraphElement
Method Detail

toString

public java.lang.String toString(int level)
Returns a string representing this GraphElement in a definable level of detail. If level==SHORT, only the name of the GraphElement will be returned. If level==NORMAL, a list of the other GraphElements connected to this one will be added. If level==DETAILED, a list of all Owners and a the full class name will be put out additionally. Finally, if level==VERY_DETAILED, the string includes a list of all property values set for this GraphElement.
Parameters:
level - the requested level of detail: SHORT,NORMAL, DETAILED or VERY_DETAILED
Returns:
a string representation of this GraphElement

toString

public java.lang.String toString()
Returns a DETAILED string representation of the object, as no detail level has been specified.
Overrides:
toString in class java.lang.Object
Returns:
a DETAILED string representation of the object.
See Also:
toString(int)

ownerListToString

protected java.lang.String ownerListToString()
Returns the list of Owners of the GraphElement as a string representation.
Returns:
a string representation of the Owner-list.

linkListToString

protected java.lang.String linkListToString()
Returns the list of connected elements as a string where in each element is printed out as a SHORT string.
Returns:
a string representation of the link list

propertiesToString

protected java.lang.String propertiesToString()
Returns a string representation of the list of properties of this GraphElement.
Returns:
the properties in a string representation

linkTypeToString

public static java.lang.String linkTypeToString(byte linktype)
Returns a short string representation for the basic link types. These are the names of the constants that define these values.
Parameters:
linktype - the linktype mask
Returns:
the string representation of the given link type

checkAccess

protected boolean checkAccess(int access,
                              java.lang.Object argument)
A method to which is called before performing any connecting operation on this GraphElement.
Parameters:
access - an access constant for the requested operation
argument - the argument of the requested operation
Returns:
true if the operation is allowed, false otherwise

opposite

public static final byte opposite(byte linktype)
Returns the opposite link type constant to linktype. I.e. if linktype is IN, OUT will be returned and vice versa. If linktype is BOTH, BOTH will be returned itself.
Parameters:
linktype - the link type constant whose opposite should be returned
Returns:
the opposite of linktype

isConnectedTo

protected boolean isConnectedTo(Graph g,
                                byte linkmask,
                                GraphElement e)
Checks, if e is connected to this GraphElement in the way specified by linkmask within Graph g. g==null is allowed to indicate, that each owning Graph shall be checked, if there's a connection between this and e inside him.
Parameters:
g - the Graph within the two GraphElements should be checked for connection. If g==null, it is checked, if this and e are connected at all (no matter in which Graph)
e - the GraphElement to check
linkmask - a byte-sized number interpreted as a bitmask specifying the way, in which e is connected to this

element

protected GraphElement element(Graph g,
                               byte linktype,
                               GraphElement e,
                               int step)
Returns the next step-th GraphElement from e which is linked to this one in the way specified by linktype within Graph g. If g==null is given, the step-th connected element will be returned, no matter inside which Graph(s) the connection exists. The search starts at e and steps forward or backward (specified by the sign of step) through all connected elements until it has found the appropiate number of GraphElements or until it reaches the end of the connected-elements-pointers array. This means, the connected elements are not supposed to be saved in a cyclic structure!
Parameters:
g - the Graph to which the requested connected element shall belong
e - the GraphElement from which the search shall start; if e==null, the first matching element is returned
linktype - the linkmask which the found element should match
step - step-1 elements matching linktype will be skipped and the step-th will be returned
Returns:
the step-th element matching linktype or null, if no such element could be found

countConnectedElements

protected int countConnectedElements(Graph g,
                                     byte linktype)
Counts and returns the number of GraphElements which are connected to this one and are linked to it in the way specified by linktype.
Parameters:
linktype - a link type constant specifying the way in which the elements to count shall be bound to this one

cursor

protected GraphCursor cursor(Graph g,
                             GraphElement e,
                             byte linktype)
Creates and returns a new Cursor object which allows to scope through the GraphElements connected to this one. The returned Cursor is set to GraphElement e.
Parameters:
g - the Graph to navigate in (or null)
e - the GraphElement to start at
linktype - the link-mask for the elements

cursor

protected GraphCursor cursor(Graph g,
                             byte linktype)
Creates and returns a new Cursor object which allows to scope through the GraphElements connected to this one. The returned Cursor is set to the first valid GraphElement.
Parameters:
g - the Graph to navigate in (or null)
linktype - the link-mask for the elements

isOwner

public boolean isOwner(Owner o)
Checks, if o is an Owner of this GraphElement.
Parameters:
o - an Owner
Returns:
true, if o is an Owner of this GraphElement and false otherwise

addOwner

protected void addOwner(Owner o)
Makes this GraphElement owned by o. If it is already owned by o, the method returns without any effect. None of the other Owners will be asked.
Parameters:
o - this GraphElement's new Owner

getProperties

public List getProperties(boolean hidden)
Returns a List of all (not hidden) properties. A property is hidden, if it starts with a dot ('.').
Parameters:
hidden - if true also hidden properties will be returned
Returns:
a List of all (not hidden) properties.

getSortedProperties

public List getSortedProperties(boolean hidden)
Returns a sorted List of all (not hidden) properties. A property is hidden, if it starts with a dot ('.').
Parameters:
hidden - if true also hidden properties will be returned
Returns:
a sorted List of all (not hidden) properties.

getSortedProperties

public List getSortedProperties()
Returns a sorted List of all not hidden properties. A property is hidden, if it starts with a dot ('.').
Returns:
a sorted List of all not hidden properties.

setProperty

public void setProperty(java.lang.String key,
                        java.lang.Object value)
Sets a property of this Node, specified by the String key to the given value.
Parameters:
key - the key-string specifying the property to change
value - the value to set as property
Throws:
java.lang.NullPointerExecption - if key or value is null

setProperty

public void setProperty(java.lang.String key,
                        int value)
Sets an int-value as value.

setProperty

public void setProperty(java.lang.String key,
                        short value)
Sets a short-value as value.

setProperty

public void setProperty(java.lang.String key,
                        long value)
Sets a long-value as value.

setProperty

public void setProperty(java.lang.String key,
                        float value)
Sets a float-value as value.

setProperty

public void setProperty(java.lang.String key,
                        double value)
Sets a double-value as value.

setProperty

public void setProperty(java.lang.String key,
                        boolean value)
Sets a boolean-value as value.

hasProperty

public boolean hasProperty(java.lang.String key)
Returns true, if the properties contain the key.
Parameters:
key - the key value
Returns:
true if the specified property is contained

getProperty

public java.lang.Object getProperty(java.lang.String key)
Returns a property value stored for this GraphElement, specified by key.
Parameters:
key - the key-string specifying the property to return
Returns:
the property value stored with key key or null, if no such key has been found

getProperty

public java.lang.Object getProperty(java.lang.String key,
                                    java.lang.Object def)
Returns a property value stored for this GraphElement, specified by key. If no property was stored under key, the default object def will be returned instead of null.
Parameters:
key - the key-string specifying the property to return
Returns:
the property value stored with key key or def, if no such key has been found

removeProperty

public java.lang.Object removeProperty(java.lang.String key)
Removes the property defined by key from the stored list of properties and returns its value. If the given key does not specify a property of this GraphElement, null will be returned.
Parameters:
key - the key specifying the property to remove
Returns:
the value which was mapped to this key in the properties

removeAllProperties

public void removeAllProperties()
Removes all properties of this GraphElement without its name().

removePropertiesStartingWith

public void removePropertiesStartingWith(java.lang.String key)
Removes all properties whose keys are starting with substring key. If key==null, the method returns effectiveless.
Parameters:
key - the substring identifying the properties to remove

getIntProperty

public int getIntProperty(java.lang.String key,
                          int def)
Method to get a property value which is not an object, but an int. If no value was found with key key or if this value was not a java.lang.Number, the default value def will be returned.
Parameters:
key - the key-string specifying the property to return
Returns:
the property value stored with key key

getShortProperty

public short getShortProperty(java.lang.String key,
                              short def)
Method to get a property value which is not an object, but a short. If no value was found with key key or if this value was not a java.lang.Number, the default value def will be returned.
Parameters:
key - the key-string specifying the property to return
Returns:
the property value stored with key key

getLongProperty

public long getLongProperty(java.lang.String key,
                            long def)
Method to get a property value which is not an object, but a long. If no value was found with key key or if this value was not a java.lang.Number, the default value def will be returned.
Parameters:
key - the key-string specifying the property to return
Returns:
the property value stored with key key

getFloatProperty

public float getFloatProperty(java.lang.String key,
                              float def)
Method to get a property value which is not an object, but a float. If no value was found with key key or if this value was not a java.lang.Number, the default value def will be returned.
Parameters:
key - the key-string specifying the property to return
Returns:
the property value stored with key key

getDoubleProperty

public double getDoubleProperty(java.lang.String key,
                                double def)
Method to get a property value which is not an object, but a double. If no value was found with key key or if this value was not a java.lang.Number, the default value def will be returned.
Parameters:
key - the key-string specifying the property to return
Returns:
the property value stored with key key

getBoolProperty

public boolean getBoolProperty(java.lang.String key,
                               boolean def)
Method to get a property value which is not an object, but a boolean. If no value was found with key key or if this value was not a java.lang.Boolean, the default value def will be returned.
Parameters:
key - the key-string specifying the property to return
Returns:
the property value stored with key key

getGraphElementProperty

public GraphElement getGraphElementProperty(java.lang.String key)
Returns a property value like getProperty(java.lang.String) which is casted to GraphElement, if this is possible, otherwise null.
Parameters:
key - the key-string specifying the property to return
Returns:
the GraphElement stored with key key

getNodeProperty

public Node getNodeProperty(java.lang.String key)
Returns a property value like getProperty(java.lang.String) which is casted to Node, if this is possible, otherwise null.
Parameters:
key - the key-string specifying the property to return
Returns:
the Node stored with key key

getEdgeProperty

public Edge getEdgeProperty(java.lang.String key)
Returns a property value like getProperty(java.lang.String) which is casted to Edge, if this is possible, otherwise null.
Parameters:
key - the key-string specifying the property to return
Returns:
the Edge stored with key key

setName

public void setName(java.lang.String s)
Stets the name of the node
Parameters:
s - name of the node

name

public java.lang.String name()
Return the name of the node
Returns:
name of the node

createFlow

public Flow createFlow(java.lang.String key)
Creates, stores in the properties and returns a new Flow object with key key. The values for upper and lower capacity bound and the flow value are set to zero and the capacity check is deactivated.
Parameters:
key - a key string identifying the new Flow
Returns:
the newly created Flow or null if key==null

createFlow

public Flow createFlow(java.lang.String key,
                       double hicap,
                       double locap,
                       double flow)
Creates, stores in the properties and returns a new Flow object with key key. The values for upper and lower capacity bound and the flow value are set to the specified values and the capacity check is deactivated.
Parameters:
key - a key string identifying the new Flow
hicap - the upper capacity
locap - the lower capacity
flow - the flow value
Returns:
the newly created Flow

flow

public Flow flow(java.lang.String key)
Returns the Flow mapped to key.
Parameters:
key - a key string identifying the requested Flow object
Returns:
the requested Flow or null, if either key is null or key is not stored in the properties or the value stored under key is not of type Flow

removeFlow

public Flow removeFlow(java.lang.String key)
Removes the Flow object identified by key from the properties and returns it. If no such key is stored or if key is null, null will be returned.
Parameters:
key - a key string identifying the requested Flow object
Returns:
the requested Flow or null, if eiter key is null or key is not stored in the properties

checkState

public boolean checkState(short state)
Checks if the given state is identical to the internal state.
Parameters:
state - the state variable to compare with the internal state
Returns:
true, if state is equal to the internal state

checkStateCleared

public boolean checkStateCleared(short state)
Checks if the given state is cleared as internal state, that means that state is binary inverse to the internal state.
Parameters:
state - the state variable to compare with the internal state
Returns:
true, if state is inverse to the internal state

state

protected short state()
Returns the complete internal state.
Returns:
the internal state variable

state

protected short state(short state)
Returns the internal state for the given state constant.
Returns:
State information.

setState

protected void setState(short state)
Sets the internal state to the given state.

clearState

protected void clearState(short state)
Clears the given state as internal state, that means that the internal state will be set to state's inverse.

key

public java.lang.Object key()
Returns the stored key of the object.
Specified by:
key in interface KeyValueHolder
Returns:
stored key

setKey

public boolean setKey(java.lang.Object key)
Sets the key.
Specified by:
setKey in interface KeyValueHolder
Parameters:
key - new key

value

public java.lang.Object value()
Returns the stored value.
Specified by:
value in interface KeyValueHolder
Returns:
stored object

setValue

public boolean setValue(java.lang.Object value)
Stores the object value as value.
Specified by:
setValue in interface KeyValueHolder
Parameters:
value - the value to be stored

clone

public java.lang.Object clone()
Creates a new object of the same class as this object. It then initializes each of the new object's fields by assigning it the same value as the corresponding field in this object. No constructor is called. In some Implementations, the fields are cloned, if possible (deep clone).
Specified by:
clone in interface Cloneable
Overrides:
clone in class java.lang.Object
Returns:
a clone of this object.

clone

public java.lang.Object clone(java.util.Hashtable h,
                              int level)
Clones this object. According to the parameter level, this object will be cloned down to level levels. That means, the object will be cloned. If level==-1(==DEEP), every object, which can be reached by traversing the references beginning with this object will be cloned if possible. This recursion stopps, if there are no more objects to clone, or no reachable object implements Cloneable. If level==1(==FLAT), no object contained by this object will be cloned, but this will be cloned. Only the references will be maintained. If level>=0, no objects will be cloned at all and this will be returned.
The recursive cloning stopps, if there's a ring structure. In this case, all Objects implementing Cloneable are cloned, and connected properly, so that even ring structures are cloned as rings. A GraphElement's cloning behaviour is somewhat special: The lists containing the Owners, linked GraphElements and their link types are not cloned, but set to null in the cloned object. But the properties are cloned, i.e. all cloneable values they are containing are cloned (not the keys!). The values which are not cloneable, will be only referenced in the cloned properties list.
Specified by:
clone in interface ControlledCloneable
Parameters:
h - Hastable which containes all objects already cloned (with their original objects as keys), to avoid multiple cloning of the same object (if h==null a new Hashtable will be created - you can use null to start a clone recursion)
level - indicates how many generations should be cloned recursive at most
Returns:
the cloned Object
Throws:
InternalError - - if the Object could not be cloned properly