gishur.core
Interface ListItem

All Superinterfaces:
KeyValueHolder
All Known Implementing Classes:
BasicListItem

public interface ListItem
extends KeyValueHolder

The interface ListItem is used for doubly connected lists, stacks and queues for example.
Although BasicList, etc. implements Serializable, ListItem doesn't. Thus you can avoid serialization from list's using ListItems not implementing Serializable. Take care not to forget to implement Serializable, if you need to.

Version:
1.0
Author:
Thomas Wolf

Field Summary
static int CLEAR_CONNECTIONS
          Delete connections.
static int CONNECT_BACKWARD
          Connect object backwards only.
static int CONNECT_FORWARD
          Connect object forwards only.
static int REMOVE
          Remove object from list.
static int SET_OWNER
          Set new owner.
 
Fields inherited from interface gishur.core.KeyValueHolder
SET_KEY, SET_VALUE
 
Method Summary
 boolean answerConnect(ListItem link, boolean forward)
          Completes the connection and should therefore only be called by connect(link,forward).
 boolean clearConnections()
          Deletes all connections originating from this ListItem.
 java.lang.Object clone()
          Clones the object flat.
 java.lang.Object clone(java.util.Hashtable h, int level)
          Clones the object according to ControlledCloneable.
 boolean connect(ListItem link, boolean forward)
          Connects this ListItem to the ListItem link.
 ListItem find(java.lang.Object O)
          Searches for object O in the chain.
 ListItem findFirst()
          Searches for the first ListItem of the chain and returns that ListItem.
 ListItem findLast()
          Searches for the last ListItem of the chain and returns that ListItem.
 int getIndex(boolean fromStart)
          Calculates the index of this ListItem within the chain, beginning from the first or the last element.
 Owner getOwningList()
          Returns the owner of the ListItem.
 boolean isFirst()
          Tests if the ListItem is the first element of a chain.
 boolean isLast()
          Tests if the ListItem is the last element of a chain.
 ListItem next()
          Returns the next connected ListItem.
 ListItem prev()
          Returns the previous ListItem.
 boolean remove()
          Deletes the connections to other ListItems. {
 boolean setOwningList(Owner owner)
          Sets the owner of the ListItem.
 
Methods inherited from interface gishur.core.KeyValueHolder
key, setKey, setValue, value
 

Field Detail

SET_OWNER

public static final int SET_OWNER
Set new owner.

REMOVE

public static final int REMOVE
Remove object from list.

CLEAR_CONNECTIONS

public static final int CLEAR_CONNECTIONS
Delete connections.

CONNECT_FORWARD

public static final int CONNECT_FORWARD
Connect object forwards only.

CONNECT_BACKWARD

public static final int CONNECT_BACKWARD
Connect object backwards only.
Method Detail

clone

public java.lang.Object clone()
Clones the object flat. The following result should be achieved: The new ListItem is not connected and has no owner. The attached keys and objects will not be cloned. They will occure as reference in the Object. To avoid cloning, just don't implement the Cloneable interface.
Overrides:
clone in class java.lang.Object
Returns:
cloned object
Throws:
InternalError - - if the Object could not be cloned properly

clone

public java.lang.Object clone(java.util.Hashtable h,
                              int level)
Clones the object according to ControlledCloneable. The new ListItem is not connected. To avoid cloning, just don't implement the ControlledCloneable interface.
Parameters:
h - Hashtable to indicate which objects are already cloned
level - indicates how deep the objects should be cloned
Returns:
cloned object
Throws:
InternalError - - if the Object could not be cloned properly
See Also:
ControlledCloneable

setOwningList

public boolean setOwningList(Owner owner)
Sets the owner of the ListItem. If an owner already exists, he is asked for permission. The new owner is also asked for permission. A change only occurs, if both agree. If the old and the new owner is the same object, no one is asked for permission and true is returned. Connections remain untouched by the change.
Parameters:
owner - new owner
Returns:
true, if the change is successful

getOwningList

public Owner getOwningList()
Returns the owner of the ListItem.
Returns:
the owner

next

public ListItem next()
Returns the next connected ListItem.
Returns:
next ListItem

prev

public ListItem prev()
Returns the previous ListItem.
Returns:
previous ListItem

findFirst

public ListItem findFirst()
Searches for the first ListItem of the chain and returns that ListItem.
Returns:
first ListItem of the chain

findLast

public ListItem findLast()
Searches for the last ListItem of the chain and returns that ListItem.
Returns:
last ListItem of the chain

isFirst

public boolean isFirst()
Tests if the ListItem is the first element of a chain.
Returns:
true, if the ListItem is the first object of the chain

isLast

public boolean isLast()
Tests if the ListItem is the last element of a chain.
Returns:
true, if the ListItem is the last ListItem of the chain

find

public ListItem find(java.lang.Object O)
Searches for object O in the chain.
Parameters:
O - object to be found
Returns:
found ListItem object or null, if search not successful.

getIndex

public int getIndex(boolean fromStart)
Calculates the index of this ListItem within the chain, beginning from the first or the last element.
Parameters:
fromStart - if true then the first element has index 0, else the last element has index 0

answerConnect

public boolean answerConnect(ListItem link,
                             boolean forward)
Completes the connection and should therefore only be called by connect(link,forward). Here the owner may not again be asked for permission (all the necessary tests were already conducted by connect(link,forward)), but answerConnect must make sure that it can only be called by connect. This can be achieved for example, by testing if a 'half connection' is already established.
Parameters:
link - ListItem, with which a connection should be established
forward, - direction of the connection (forward, if true)
Returns:
true, if connection successful

connect

public boolean connect(ListItem link,
                       boolean forward)
Connects this ListItem to the ListItem link. This is a forward connection, if forward==true, otherwise it is a backward connection. To achieve a double connection, the method answerConnect(link,forward) of the ListItem link is called (if link!=null). The owner is asked for permission before the connection takes place. For two ListItems to be connected, they must both have the same owner.
Parameters:
link - ListItem with which this is to be connected
forward, - direction of the connection (forward, if true)
Returns:
true, if connection is permitted and successful.

remove

public boolean remove()
Deletes the connections to other ListItems. prev() is directly connected to next(). After the operation this will be ownerless.
Returns:
true, if remove() is permitted and successful.

clearConnections

public boolean clearConnections()
Deletes all connections originating from this ListItem. The connections are not removed completely (in both directions). In contrast to remove() the owner is asked only once for permission! The owner remains unchanged.
Returns:
true, if successful