org.cdlib.xtf.util
Class EmbeddedList

Object
  extended by EmbeddedList

public class EmbeddedList
extends Object

This class implements a linked list, where the links are embedded within the objects added to the list.

Why another linked list you ask? Why not use the java.util.LinkedList? It depends on what you're doing with the list. Since the built-in LinkedList doesn't keep links in the object, any operation that takes an object as a parameter has to do a linear scan of the list to find it. So the remove(object) operation is slow, and therefore moveToHead() and moveToTail() are also slow (well, LinkedList doesn't have them directly.)

In contrast, embedding the links in the object allows remove(Linkable) to run in constant rather than linear time.

The downside to embedding the links is that an object can only be in a single EmbeddedList at one time.

Any object placed into an EmbeddedList must support the Linkable interface. The easiest way to do this is to simply extend the LinkableImpl class, and then no additional work is needed.


Field Summary
private  int count
          How many objects are currently in the list
private  Linkable head
          Reference to the first object in the list, or null if empty
private  Linkable tail
          Reference to the last object in the list, or null if empty
 
Constructor Summary
EmbeddedList()
           
 
Method Summary
 void addHead(Linkable l)
          Add an object to the head of the list.
 void addTail(Linkable l)
          Add an object to the tail of the list.
 int getCount()
          Get a count of the number of objects in the list.
 Linkable getHead()
          Get the first object in the list.
 Linkable getTail()
          Get the last object in the list.
 void moveToHead(Linkable l)
          Move the specified object to the head of the list (if it isn't already there).
 void moveToTail(Linkable l)
          Move the specified object to the tail of the list (if it isn't already there).
 Linkable remove(Linkable l)
          Remove (and return) the specified object from the list.
 Linkable removeHead()
          Remove (and return) the first object in the list.
 Linkable removeTail()
          Remove (and return) the last object in the list.
 
Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

head

private Linkable head
Reference to the first object in the list, or null if empty


tail

private Linkable tail
Reference to the last object in the list, or null if empty


count

private int count
How many objects are currently in the list

Constructor Detail

EmbeddedList

public EmbeddedList()
Method Detail

addHead

public void addHead(Linkable l)
Add an object to the head of the list.

Parameters:
l - The object to add. Note that it must not be in any other EmbeddedList.

addTail

public void addTail(Linkable l)
Add an object to the tail of the list.

Parameters:
l - The object to add. Note that it must not be in any other EmbeddedList.

getHead

public Linkable getHead()
Get the first object in the list.

Returns:
The object, or null if there are none in the list.

getTail

public Linkable getTail()
Get the last object in the list.

Returns:
The object, or null if there are none in the list.

getCount

public int getCount()
Get a count of the number of objects in the list.

Returns:
Number of objects.

removeHead

public Linkable removeHead()
Remove (and return) the first object in the list.

Returns:
The first object in the list, or null if the list is empty.

removeTail

public Linkable removeTail()
Remove (and return) the last object in the list.

Returns:
The last object in the list, or null if the list is empty.

moveToHead

public void moveToHead(Linkable l)
Move the specified object to the head of the list (if it isn't already there).


moveToTail

public void moveToTail(Linkable l)
Move the specified object to the tail of the list (if it isn't already there).


remove

public Linkable remove(Linkable l)
Remove (and return) the specified object from the list. Happily, unlike the standard LinkedList, this runs in constant time (not linear time.)

Returns:
The same object, useful for operator chaining.