com.ccg.util
Class TimeList

java.lang.Object
  java.util.AbstractCollection
      com.ccg.util.TimeList

All Implemented Interfaces:

Iterable, Collection

public final class TimeList
extends AbstractCollection

Collection of time ordered Objects.

This class is designed to serve as a buffer of time ordered objects. It is intended to be used in the following manner:

• Objects are added to the collection with an associated time stamp via add(Object,long) (we use the current system time if you don't provide a time stamp).
• When inserted into the collection, the objects are done so such that they maintain time order.
• When objects are removed from the collection, they come out in time order (oldest objects come out first).
• We guarantee that removal (via remove()) of objects produces a time ordered sequence as long as the collection exists. This means that we may refuse to accept the addition of some data - if the time stamp associated with the new data is older than data which has already been removed from the queue.
• Objects with identical time stamps will come out in the order entered (FIFO).

This class was originally designed for the purpose of sorting partially time ordered data in a real time context. The original problem, involved lightning solutions which had associated time stamps, however, due to the formulas involved, the resulting solutions would sometimes be slightly out of time order. This was undesirable as we wanted to distribute the solutions to other applications in time order. This class provides the ability to serve as a time ordering buffer in this situation.

Be aware that this implementation provides no internal synchronization. If you intend this collection with multiple threads, you will need to provide your own synchronization mechanism.

HANDY TIP: Though designed to work with the Java millisecond time stamp philosophy, this class could be used for ANY sequential integer sorting mechanism (since 'long' is used as the time stamp). This means you could pass nanoval, second values, day counts, etc - as long as you are consistent.

Here is how you might imbed a sample usage within the comment block:

 import com.ccg.util.TimeList;

 import java.util.Date;
 import java.text.SimpleDateFormat;

 public class BirthDay {

   public BirthDay(String name, long bdate)  {
     _Born = bdate;
     _Name = name;
   }

   public long getBirthDate() {
     return _Born;
   }
 
   public String toString() {
     return _Name+' '+(new Date(_Born));
   }

   private long _Born;
   private String _Name;
 
   public static void main(String[] args) {
     try {
       SimpleDateFormat df = new SimpleDateFormat("yyyy-MM-dd");
       TimeList tl = new TimeList();
       String[] names = { "Erik", "Scott", "Paul", "Megan" };
       String[] bdays = { "1992-05-17", "1993-10-04", 
                          "1963-12-25", "1964-01-11" };
       for (int i = 0; i < names.length; i++) {
         BirthDay bd = new BirthDay(names[i],df.parse(bdays[i]).getTime());
         tl.add(bd,bd.getBirthDate());
       }

       System.out.println(tl);
     } catch (Exception e) {
       e.printStackTrace(System.err);
     }
   }
 }
 

Since:

1.0

Version:

$Revision: 1.1 $

Author:

$Author: pkb $

Constructor Summary

TimeList()
Default constructor for the TimeList class.

Method Summary

boolean	add(Object o) Add a element to the collection.
boolean	add(Object o, long time_stamp) Add a element to the collection with an associated time stamp.
void	clear() Remove all elements from the collection.
Object	clone() Make a new clone of the TimeList object.
long	getDuration() Get the duration between the oldest and newest piece of data in the queue.
long	getTimeLastRemoved() Get the time stamp associated with the last object removed.
long	getTimeNewest() Get the time stamp of the newest object in the collection.
long	getTimeOldest() Get the time stamp of the oldest object in the collection.
boolean	isEmpty() Determine if the collection is empty.
Iterator	iterator() Get a iterator to go through the elements contained within the collection.
Object	peek() Peek at the oldest entry within the collection.
Object	remove() Remove the oldest entry which is in the collection.
boolean	remove(Object obj) Remove a specific entry from the collection.
int	size() Get the number of elements contained within the collection.

Methods inherited from class java.util.AbstractCollection

addAll, contains, containsAll, removeAll, retainAll, toArray, toArray, toString

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.Collection

equals, hashCode

Constructor Detail

TimeList

public TimeList()

Default constructor for the TimeList class.

The TimeList will be fully constructed and ready for the addition of objects after being constructed in this fashion.

Since:

1.0

Method Detail

clone

public Object clone()
             throws CloneNotSupportedException

Make a new clone of the TimeList object.

Overrides:

clone in class Object

Returns:

A new TimeList which contains references to the same objects as the original.

Throws:

CloneNotSupportedException

iterator

public Iterator iterator()

Get a iterator to go through the elements contained within the collection.

Please note that we support the use of Iterator.remove() in this implementation. However, since this allows the removal of objects in an arbitrary order, we do not update the time of the last removed object if you remove anything in this fashion.

Specified by:

iterator in interface Iterable

Specified by:

iterator in interface Collection

Specified by:

iterator in class AbstractCollection

Returns:

A iterator which is valid for going through the collection in the oldest to newest order maintained by the collection (never returns null).

size

public int size()

Get the number of elements contained within the collection.

Specified by:

size in interface Collection

Specified by:

size in class AbstractCollection

Returns:

The number of elements within the collection.

isEmpty

public boolean isEmpty()

Determine if the collection is empty.

Specified by:

isEmpty in interface Collection

Overrides:

isEmpty in class AbstractCollection

Returns:

true if Collection is empty.

add

public boolean add(Object o)

Add a element to the collection.

This method attempts to add a new element to the collection. It associates the current system time as the time stamp with the object as it attempts to insert it into the collection.

Specified by:

add in interface Collection

Overrides:

add in class AbstractCollection

Parameters:

o - Object to add to collection.

Returns:

true if successfully added to collection, false if not (would only happen if data has been removed from the collection with a time stamp later than the current system time).

Throws:

IllegalArgumentException - If insertion could yield an out of time order problem.

add

public boolean add(Object o,
                   long time_stamp)

Add a element to the collection with an associated time stamp.

This method attempts to add a new element to the collection with a specific time stamp associated with the object.

Parameters:

o - Object to add to collection.

time_stamp - The particular point in time to associate with the object. This is used in deciding how to insert the entry into the collection.

Returns:

true if successfully added to collection, false if not.

Throws:

IllegalArgumentException - If time_stamp contains a time prior to any element which has already passed into AND out of the time list (if insertion could yield an out of time order problem).

peek

public Object peek()

Peek at the oldest entry within the collection.

This method allows one to look at the "hot element" within the collection. The "hot element" is the next element within the Collection which the remove() operation will remove (the oldest piece of data).

Using this method does NOT remove the element "peeked" at from the collection.

Returns:

Reference to the oldest object within the collection.

Throws:

IllegalStateException - - if the collection is empty.

remove

public boolean remove(Object obj)

Remove a specific entry from the collection. This method removes a specific entry from the collection WITHOUT updating the time of the last removed item (since we can't guarantee time order if you remove items non sequentially).

Specified by:

remove in interface Collection

Overrides:

remove in class AbstractCollection

Parameters:

o - Object to remove (null is OK).

Returns:

true if matching object found in collection and removed.

Since:

1.0

remove

public Object remove()

Remove the oldest entry which is in the collection.

This is the counter part to the add method. This method is similar to the peek() method except that it removes one item from the collection. The removed object (if any are available) will be the one with the oldest associated time stamp.

Parameters:

removed - Handle to store reference to object removed (if anything removed).

Returns:

Reference to the object removed from the collection.

Throws:

IllegalStateException - - if the collection is empty.

clear

public void clear()

Remove all elements from the collection.

Specified by:

clear in interface Collection

Overrides:

clear in class AbstractCollection

getTimeLastRemoved

public long getTimeLastRemoved()

Get the time stamp associated with the last object removed.

This method allows one to get the time associated with the last object which was removed from the TimeList. If an object has NEVER been removed, then this method returns Long.MIN_VALUE. The time returned represents the oldest time which the collection will allow for new additions of data. In other words, if you attempt to add data to the collection with a time stamp earlier than this value, your request will be refused.

Parameters:

Millisecond - time stamp of oldest object which has ever been removed, OR Long.MIN_VALUE if a object has never been removed.

getTimeOldest

public long getTimeOldest()

Get the time stamp of the oldest object in the collection.

This method allows one to get the time associated with the oldest object which is still contained by the TimeList. If the TimeList is empty, then this method returns false. If this method returns true, it will update the ts variable you pass. The time returned represents the time associated with the oldest data currently in the collection.

Parameters:

ts - Where to store the time stamp of the oldest object in the collection.

Returns:

Time of oldest entry in the collection or 0 if collection is empty.

Throws:

IllegalStateException - - if the collection is empty.

getTimeNewest

public long getTimeNewest()

Get the time stamp of the newest object in the collection.

This method allows one to get the time associated with the newest object which is still contained by the TimeList. If the TimeList is empty, then this method returns 0.

Returns:

Time associated with the newest object in the collection (or 0 if collection is empty).

getDuration

public long getDuration()

Get the duration between the oldest and newest piece of data in the queue.

This method computes the age difference between the oldest and newest piece of data in the queue. It only does this if its possible (there are at least two items in the queue).

Returns:

The duration (difference in time stamps) between the oldest and newest entry (or 0 if there are 1 or less entries).