com.virtuosotechnologies.lib.ring
Class AbstractRing

java.lang.Object
  extended bycom.virtuosotechnologies.lib.ring.AbstractRing
Direct Known Subclasses:
ByteRing, CharRing, IntRing, ObjectRing

public abstract class AbstractRing
extends Object

Circular buffer abstract base class. This class is not thread-safe.


Constructor Summary
protected AbstractRing(int initialCapacity)
          Constructs an empty buffer with the specified initial capacity.
 
Method Summary
 void addBack(int num)
          Extends the size of the buffer to the back.
 void addFront(int num)
          Extends the size of the buffer to the front.
 void addMiddle(int index, int num)
          Inserts elements into the middle of the buffer.
protected abstract  Object allocateArray(int capacity)
          Override this method to allocate an array of the desired type.
protected  int calculateRawIndex(int index)
          Calculates the real index into the array given the buffer index.
 void clear()
          Clears the buffer, setting its size to 0.
protected abstract  void clearArrayValues(Object array, int start, int end)
          Override this method to clear the specified values in the array.
 void ensureCapacity(int minCapacity)
          Increases the capacity of this ring, if necessary, to ensure that it can hold at least the number of elements specified by the minimum capacity argument.
protected abstract  int getArrayLength(Object array)
          Override this method to get the length of the array.
protected  void getRangeRaw(int start, int end, Object destination, int pos)
          Gets a range of values and copies it into the given array.
protected  Object getRawArray()
          Gets the current array object.
 int getSize()
          Returns the number of elements in this ring.
protected abstract  void initArrayValues(Object array, int start, int end)
          Override this method to initialize the specified values in the array.
 void removeBack(int num)
          Truncates the size of the buffer to the back.
 void removeFront(int num)
          Truncates the size of the buffer to the front.
 void removeMiddle(int fromIndex, int toIndex)
          Removes elements from the middle of the buffer.
protected  void setRangeRaw(int start, int end, Object source, int pos)
          Sets a range of values from the given array.
 void trimToSize()
          Trims the capacity of this ring to be the buffer's current size.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

AbstractRing

protected AbstractRing(int initialCapacity)
Constructs an empty buffer with the specified initial capacity.

Parameters:
initialCapacity - the initial capacity of the buffer.
Throws:
IllegalArgumentException - if the specified initial capacity is negative
Method Detail

allocateArray

protected abstract Object allocateArray(int capacity)
Override this method to allocate an array of the desired type.

Parameters:
capacity - size of the array to allocate
Returns:
the allocated array

getArrayLength

protected abstract int getArrayLength(Object array)
Override this method to get the length of the array.

Parameters:
array - an array object
Returns:
the size of the array

clearArrayValues

protected abstract void clearArrayValues(Object array,
                                         int start,
                                         int end)
Override this method to clear the specified values in the array.

Parameters:
array - an array object
start - the index of the first item to clear
end - one more than the index of the last item to clear

initArrayValues

protected abstract void initArrayValues(Object array,
                                        int start,
                                        int end)
Override this method to initialize the specified values in the array.

Parameters:
array - an array object
start - the index of the first item to initialize
end - one more than the index of the last item to initialize

getRawArray

protected final Object getRawArray()
Gets the current array object. Subclasses should not expect that this object will remain the real array object (that is, do not cache the return value of this method) because the object will likely change if the buffer is mutated. This is mainly useful in conjuction with calculateRawIndex() to obtain or set the value of a specific element in the buffer.

Returns:
the array object

calculateRawIndex

protected final int calculateRawIndex(int index)
Calculates the real index into the array given the buffer index.

Parameters:
index - index into the buffer
Returns:
corresponding index into the array

getRangeRaw

protected final void getRangeRaw(int start,
                                 int end,
                                 Object destination,
                                 int pos)
Gets a range of values and copies it into the given array. The type of the destination must match the type of the buffer.

Parameters:
start - starting position in the buffer
end - one more than the ending position in the buffer
destination - destination array
pos - starting position in the destination array

setRangeRaw

protected final void setRangeRaw(int start,
                                 int end,
                                 Object source,
                                 int pos)
Sets a range of values from the given array. The type of the source must match the type of the buffer.

Parameters:
start - starting position in the buffer
end - one more than the ending position in the buffer
source - source array
pos - starting position in the source array

trimToSize

public void trimToSize()
Trims the capacity of this ring to be the buffer's current size. An application can use this operation to minimize the storage of a ring.


ensureCapacity

public void ensureCapacity(int minCapacity)
Increases the capacity of this ring, if necessary, to ensure that it can hold at least the number of elements specified by the minimum capacity argument.

Parameters:
minCapacity - the desired minimum capacity.

getSize

public int getSize()
Returns the number of elements in this ring.

Returns:
the number of elements in this ring.

addFront

public void addFront(int num)
Extends the size of the buffer to the front. Added elements are initialized according to the particular ring subclass.

Parameters:
num - number of elements to add

removeFront

public void removeFront(int num)
Truncates the size of the buffer to the front. Removed elements are cleared according to the particular ring subclass.

Parameters:
num - number of elements to remove

addBack

public void addBack(int num)
Extends the size of the buffer to the back. Added elements are initialized according to the particular ring subclass.

Parameters:
num - number of elements to add

removeBack

public void removeBack(int num)
Truncates the size of the buffer to the back. Removed elements are cleared according to the particular ring subclass.

Parameters:
num - number of elements to remove

clear

public void clear()
Clears the buffer, setting its size to 0. Removed elements are cleared according to the particular ring subclass.


addMiddle

public void addMiddle(int index,
                      int num)
Inserts elements into the middle of the buffer. Added elements are initialized according to the particular ring subclass.

Parameters:
index - index at which to begin inserting elements
num - number of elements to insert
Throws:
IndexOutOfBoundsException - if index out of range

removeMiddle

public void removeMiddle(int fromIndex,
                         int toIndex)
Removes elements from the middle of the buffer. Removed elements are cleared according to the particular ring subclass.

Parameters:
fromIndex - first index
toIndex - one more than last index
Throws:
IndexOutOfBoundsException - if index out of range