com.ccg.util
Class WrapArray

java.lang.Object
  com.ccg.util.WrapArray

public class WrapArray
extends Object

Implementation of a wrap-around buffer. This class implements a queue in a array type form. Eventually it will probably implement the Java 1.2 Collection interface.

Basically, this object allows one to create an fixed size array capable of holding a maximum number of objects. As objects are added to the array, newer objects will replace older objects. When you fetch elements from the buffer, you specify a index value with must be from 0 to the current number of objects remaining in the queue.

This type of object is extremely useful when you want to keep a buffer of the last N objects around for a period of time.

At the moment, this object is NOT thread safe. I am currently assuming that this object should remain light weight and those which require synchronization will do it themselves.

There are numerous "protected" methods which are provided to allow extended classes the ability to optimize some operations (like binary searches).

NOTE: The name of this class can only be properly expressed while folding one's arms across the chest, wearing a baseball cap backwards, and tipping one's head to the right and slightly back (also use a deep voice).

Since:

1.0

Version:

$Revision: 1.5 $

Author:

$Author: pkb $

Constructor Summary

WrapArray()
Initializes array with a capacity of 1024 objects.

WrapArray(int size)
Initializes the array with a configurable buffer capacity.

Method Summary

boolean	add(Object o) Add a new object to the buffer.
protected int	decrementIndex(int i) Get next index position of element following a known index position.
protected Object	elementAt(int i) Retrieve a specific object out of the buffer.
Object	get(int i) Retrieve the Nth object out of the buffer.
protected int	getEndIndex() Get index position of the last element in the buffer.
int	getMaxSize() Get the maximum size the buffer can hold.
protected int	getMiddleIndex(int s, int e) Routine to find the "middle" index value between a start/end pair.
protected int	getStartIndex() Get index position of the first element in the buffer.
protected int	incrementIndex(int i) Get next index position of element following a known index position.
boolean	isEmpty() Determine if the wrap around buffer is empty.
Object	remove() Removes the oldest object from the buffer.
void	remove(int n) Removes the oldest N objects from the buffer.
int	size() Get the number of objects which are still in the buffer.

Methods inherited from class java.lang.Object

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

Constructor Detail

WrapArray

public WrapArray()

Initializes array with a capacity of 1024 objects.

Since:

1.0

See Also:

WrapArray(int)

WrapArray

public WrapArray(int size)

Initializes the array with a configurable buffer capacity.

Parameters:

size - Initial size for array.

Since:

1.0

See Also:

add(java.lang.Object), get(int), remove()

Method Detail

isEmpty

public final boolean isEmpty()

Determine if the wrap around buffer is empty.

Returns:

true if the buffer is empty (has no objects).

Since:

1.0

See Also:

get(int)

size

public final int size()

Get the number of objects which are still in the buffer.

Returns:

Number of objects left in the buffer.

Since:

1.0

See Also:

add(java.lang.Object), get(int)

getMaxSize

public int getMaxSize()

Get the maximum size the buffer can hold. This method returns the maximum size which the WrapArray object can hold. This should be the same as the size which the WrapArray was initially constructed with.

Returns:

Maximum number of objects the WrapArray can hold.

Since:

1.0

See Also:

WrapArray(int), size()

add

public boolean add(Object o)

Add a new object to the buffer. This routine is used to add a new object to the queue. If the buffer is full, the oldest object will automatically be removed from the collection (it will be replaced by this new object).

Parameters:

o - Object to add to the collection.

Returns:

boolean (true indicating that new object was successfully added to the queue).

Since:

1.0

See Also:

remove(), get(int)

remove

public Object remove()

Removes the oldest object from the buffer. This method is used to remove the oldest object from the buffer. If you just want to "peek" at the oldest object, use get(0) instead.

Returns:

Oldest object in buffer or null if buffer is empty.

Since:

1.0

See Also:

add(java.lang.Object), get(int)

remove

public void remove(int n)

Removes the oldest N objects from the buffer. This method is used to remove 0 or more of the oldest objects from the buffer. This allows one to "trim" some of the old data from the buffer.

Parameters:

num - Number of object to remove (if 0 or less, then nothing is removed, if greater than or equal to size(), then ALL are removed).

Since:

1.0

See Also:

remove(), get(int)

get

public Object get(int i)
           throws ArrayIndexOutOfBoundsException

Retrieve the Nth object out of the buffer. This method is used to look at the objects contained by the buffer. You must specify a value in the range of 0 to the one less than current size of the buffer. The queue is ordered such that starting from 0 and going up to size()-1 will result in processing all objects remaining in the queue in the order which they were added. The following example demonstrates:

 void foo(WrapArray wa) {
   for (int i = 0; i != wa.size(); i++) {
     System.out.println("Object["+i+"] = "+wa.get(i).toString());
   }
 }
 

Parameters:

index - Index which should be in the range of [0,size()-1];

Returns:

Object as specific position, or null if index specifies a unused location or the collection is empty.

Throws:

ArrayOutOfBoundsException - If specified index is invalid.

ArrayIndexOutOfBoundsException

Since:

1.0

See Also:

size()

elementAt

protected final Object elementAt(int i)
                          throws ArrayIndexOutOfBoundsException

Retrieve a specific object out of the buffer.

Parameters:

index - Index which should be in the range of [getStartIndex(),getEndIndex()].

Returns:

Object as specific position, or null if index specifies a unused location or the collection is empty.

Throws:

ArrayOutOfBoundsException - If specified index is invalid.

ArrayIndexOutOfBoundsException

Since:

1.0

See Also:

size(), getStartIndex(), getEndIndex()

getStartIndex

protected final int getStartIndex()

Get index position of the first element in the buffer. Typically one just uses the getOldest() and/or getNewest() members to access the objects at the ends of the queue. However, if one wants to iterate across the current contents of the queue in the order from the oldest to newest, this method is required as the following example demonstrates:

 void foo(WrapArray wa) {
   if (wa.size() == 0) return;
   for (int i = wa.getStartIndex(); i != wa.getEndIndex();) {
     System.out.println("Object["+i+"] = "+wa.elementAt(i).toString());
     i = wa.incrementIndex(i);
   }
 }
 

IMPORTANT: If there are not any objects left in the queue, this routine returns meaningless info.

Returns:

Index to the first element in the buffer.

Since:

1.0

See Also:

getEndIndex(), isEmpty()

getEndIndex

protected final int getEndIndex()

Get index position of the last element in the buffer. Typically one just uses the getOldest() and/or getNewest() members to access the objects at the ends of the queue. However, if one wants to iterate across the current contents of the queue in the order from the oldest to newest, this method is required as the following example demonstrates:

 void foo(WrapArray wa) {
   if (wa.size() == 0) return;
   for (int i = wa.getStartIndex(); i != wa.getEndIndex();) {
     System.out.println("Object["+i+"] = "+wa.elementAt(i).toString());
     i = wa.incrementIndex(i);
   }
 }
 

IMPORTANT: If there are not any objects left in the queue, this routine returns meaningless info.

Returns:

Index to the last element in the buffer.

Since:

1.0

See Also:

getStartIndex(), isEmpty()

incrementIndex

protected final int incrementIndex(int i)

Get next index position of element following a known index position. Typically one just uses the getOldest() and/or getNewest() members to access the objects at the ends of the queue. However, if one wants to iterate across the current contents of the queue in the order from the oldest to newest, this method is required as the following example demonstrates:

 void foo(WrapArray wa) {
   for (int i = wa.getStartIndex(); i != wa.getEndIndex();) {
     System.out.println("Object["+i+"] = "+wa.elementAt(i).toString());
     i = wa.incrementIndex(i);
   }
 }
 

Parameters:

index - Current index position.

Returns:

Index to element which follows this one (will wrap around to start once the end of the array is reached).

Since:

1.0

See Also:

getStartIndex()

decrementIndex

protected final int decrementIndex(int i)

Get next index position of element following a known index position. Typically one just uses the getOldest() and/or getNewest() members to access the objects at the ends of the queue. However, if one wants to iterate across the current contents of the queue in the order from the oldest to newest, this method is required as the following example demonstrates:

 void foo(WrapArray wa) {
   for (int i = wa.getStartIndex(); i != wa.getEndIndex();) {
     System.out.println("Object["+i+"] = "+wa.elementAt(i).toString());
     i = wa.incrementIndex(i);
   }
 }
 

Parameters:

index - Current index position.

Returns:

Index to element which follows this one (will wrap around to start once the end of the array is reached).

Since:

1.0

See Also:

incrementIndex(int)

getMiddleIndex

protected final int getMiddleIndex(int s,
                                   int e)

Routine to find the "middle" index value between a start/end pair. It is conceivable that this type of wrap around array will hold sorted data. For example, lets suppose you were adding lightning data objects which occurred at specific points in time and the data was showing up time ordered. In this type of condition, the contents of your wrap around array would be time ordered. By making use of this function, you could "search" the buffer in a binary search fashion for a event which occurred at a specific point in time.

 int findClosestIndex(WrapArray wa, long tMillis) {
   int s = wa.getStartIndex();
   int e = wa.getEndIndex();

   while (s != e) {
                           // get time of object in middle
    int i = wa.getMiddleIndex(s,e);
    long dMillis = getTimeMillis(wa.getObject(i));
                          // if match found, then exit
    if (dMillis == tMillis) return i;
                          
    if (dMillis > tMillis) {
                          // check to see if end reached
      if (i == s) e = s;
      else e = wa.decrementIndex(i);
    }
    else {
      if (i == e) s = e;
      else s = wa.incrementIndex(i);
    }
   }
   return s;            // s == e == i at closest match
 }
 

Parameters:

s - Starting index postion into the wrap around array. Must be in the range of [getStartIndex(),getEndIndex()].

e - Ending index position into the wrap around array. Must be in the range of [getStartIndex(),getEndIndex()].

Returns:

Middle index position in the array. In the range of [getStartIndex(),getEndIndex()].

Since:

1.0

See Also:

getStartIndex(), getEndIndex()