com.cloudhopper.commons.util

Class CircularIndex

java.lang.Object

com.cloudhopper.commons.util.CircularIndex

public class CircularIndex
extends Object

Utility class for maintaining a circular index of a fixed capacity. Useful for implementing a "queue" using a fixed-length array where the head and tail keep looping around the fixed capacity.

Author:

joelauer (twitter: @jjlauer or http://twitter.com/jjlauer)

Constructor Summary

Constructors

Constructor and Description
CircularIndex(long capacity) Creates a circular index based on a fixed capacity of elements.
CircularIndex(long capacity, boolean resetOnZero)
CircularIndex(long capacity, long first, long size)
CircularIndex(long capacity, long first, long size, boolean resetOnZero) Creates a circular index based on a fixed capacity of elements.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	addFirst() Adds an element to the front of the index if its not full.
boolean	addLast() Adds an element to the back of the index if its not full.
protected long	calculateNewIndex(long index, long offset)
long	getCapacity() Gets the underlying capacity of the index.
long	getFirst() Gets the index to the first element if it exists.
protected long	getInternalFirst() protected methods just for testing purposes
protected long	getInternalNext()
long	getLast() Gets the index to the last element if it exists.
long	getMaxSize() Gets the maximum number of elements this index can support.
long	getNextFirst() Gets the index where the next first element will be put.
long	getNextLast() Gets the index where the next last element will be put.
long	getSize() Gets the current number of elements in this index.
boolean	isEmpty() Checks if the index is currently empty (contains no elements).
boolean	isFull() Checks if the index is currently full (contains all elements).
boolean	removeFirst() Removes the first element from the front of the index if its not empty.
boolean	removeLast() Removes the last element from the back of the index if its not empty.
void	reset() Resets index back to defaults with a zero size and no elements.
String	toString()

Methods inherited from class java.lang.Object

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

Constructor Detail

CircularIndex

public CircularIndex(long capacity)

Creates a circular index based on a fixed capacity of elements. This capacity should represent the actual length of an array, etc. The max size of elements permitted in the index is exactly one less than the capacity (maxSize = capacity - 1). This max size is driven by the requirement that 1 empty space exists to keep track of where the first and last elements are in the index.

Parameters:

capacity - The fixed capacity of elements. If this index is to be used with an array, the capacity should match the capacity of the array. Must be > 0.

CircularIndex

public CircularIndex(long capacity,
             boolean resetOnZero)

CircularIndex

public CircularIndex(long capacity,
             long first,
             long size)

CircularIndex

public CircularIndex(long capacity,
             long first,
             long size,
             boolean resetOnZero)

Creates a circular index based on a fixed capacity of elements. This capacity should represent the actual length of an array, etc. The max size of elements permitted in the index is exactly one less than the capacity (maxSize = capacity - 1). This max size is driven by the requirement that 1 empty space exists to keep track of where the first and last elements are in the index.

Parameters:

capacity - The fixed capacity of elements. If this index is to be used with an array, the capacity should match the capacity of the array. Must be > 0.

first - The initial index of the first element. This must be within the range based on the capacity.

size - The number of elements contained within the index. Used in conjunction with the first element index to calculate the "next" index used internally. Can be set to zero in order to control which will be the index of the first element added.

resetOnZero - Controls whether this index should automatically reset when the size hits zero. A reset sets the first and next indexes back to their defaults.

Method Detail

reset

public void reset()

Resets index back to defaults with a zero size and no elements. The first index will start from zero. The capacity remains the same as when the index was constructed.

getCapacity

public long getCapacity()

Gets the underlying capacity of the index. NOTE: This does not equal the maximum number of elements the index can support. The capacity is always 1 size larger than the maximum size since one empty space is used to track the first and last items in the index.

Returns:

The underlying capacity of the index.

getMaxSize

public long getMaxSize()

Gets the maximum number of elements this index can support. Always one less than the set capacity.

Returns:

The maximum number of elements this index can support.

getSize

public long getSize()

Gets the current number of elements in this index.

Returns:

The number of elements in this index.

isEmpty

public boolean isEmpty()

Checks if the index is currently empty (contains no elements).

Returns:

True if the index is empty, otherwise false.

isFull

public boolean isFull()

Checks if the index is currently full (contains all elements).

Returns:

True if the index is full, otherwise false.

calculateNewIndex

protected long calculateNewIndex(long index,
                     long offset)

addLast

public boolean addLast()

Adds an element to the back of the index if its not full.

Returns:

True if the element was added or false if the index was full.

addFirst

public boolean addFirst()

Adds an element to the front of the index if its not full.

Returns:

True if the element was added or false if the index was full.

removeLast

public boolean removeLast()

Removes the last element from the back of the index if its not empty.

Returns:

True if the element was removed or false if the index was empty.

removeFirst

public boolean removeFirst()

Removes the first element from the front of the index if its not empty.

Returns:

True if the element was removed or false if the index was empty.

getFirst

public long getFirst()

Gets the index to the first element if it exists.

Returns:

The index of the first element (head) or -1 if no elements exist.

getLast

public long getLast()

Gets the index to the last element if it exists.

Returns:

The index of the last element (tail) or -1 if no elements exist.

getNextLast

public long getNextLast()

Gets the index where the next last element will be put. This is the index where the next "addLast" operation would put the element. Will return -1 if the index is full (i.e. no next space available).

Returns:

The index of where the next last element will be put or -1 if the the index is full.

getNextFirst

public long getNextFirst()

Gets the index where the next first element will be put. This is the index where the next "addFirst" operation would put the element. Will return -1 if the index is full (i.e. no next space available).

Returns:

The index of where the next first element will be put or -1 if the the index is full.

getInternalFirst

protected long getInternalFirst()

protected methods just for testing purposes

getInternalNext

protected long getInternalNext()

toString

public String toString()

Overrides:

toString in class Object