Package com.wavefront.common

Class EvictingRingBuffer<T>

java.lang.Object

java.util.AbstractCollection<T>

com.wavefront.common.EvictingRingBuffer<T>

Type Parameters:

T - type of objects stored

All Implemented Interfaces:

Serializable, Cloneable, Iterable<T>, Collection<T>, Queue<T>, RandomAccess

Direct Known Subclasses:

SynchronizedEvictingRingBuffer

@NotThreadSafe
public class EvictingRingBuffer<T>
extends AbstractCollection<T>
implements Queue<T>, RandomAccess, Cloneable, Serializable

A basic ring buffer with an ability to evict values on overflow.

Author:

vasily@wavefont.com

See Also:

Serialized Form

Constructor Summary

Constructors

Modifier	Constructor	Description
	EvictingRingBuffer(int capacity)
	EvictingRingBuffer(int capacity, boolean throwOnOverflow)
	EvictingRingBuffer(int capacity, boolean throwOnOverflow, T defaultValue)
protected	EvictingRingBuffer(int capacity, boolean throwOnOverflow, T defaultValue, boolean preFill)
	EvictingRingBuffer(int capacity, T defaultValue)

Method Summary

Modifier and Type	Method	Description
boolean	add(T value)	Add a value at the end of the ring buffer.
int	capacity()	Returns buffer capacity (i.e.
Object	clone()
T	element()	Retrieves, but does not remove, the head of this buffer.
boolean	equals(Object obj)
T	get(int index)	Return the element at the specified position in the buffer.
int	hashCode()
Iterator<T>	iterator()
boolean	offer(T value)	Inserts the specified element into this queue if it is possible to do so immediately without violating capacity restrictions.
T	peek()	Retrieves, but does not remove, the head of this buffer, or returns null if empty.
T	poll()	Retrieves and removes the head of this buffer, or returns null if empty.
T	remove()	Retrieves and removes the head of this buffer.
int	size()	Returns number of elements in the buffer.
Object[]	toArray()
List<T>	toList()	Returns a List<T> containing all the elements in the buffer in proper sequence (first to last element).

Methods inherited from class java.util.AbstractCollection

addAll, clear, contains, containsAll, isEmpty, remove, removeAll, retainAll, toArray, toString

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.Collection

addAll, clear, contains, containsAll, isEmpty, parallelStream, remove, removeAll, removeIf, retainAll, spliterator, stream, toArray

Methods inherited from interface java.lang.Iterable

forEach

Constructor Detail

EvictingRingBuffer

public EvictingRingBuffer(int capacity)

Parameters:

capacity - desired capacity.

EvictingRingBuffer

public EvictingRingBuffer(int capacity,
                          boolean throwOnOverflow)

Parameters:

capacity - desired capacity

throwOnOverflow - Disables auto-eviction on overflow. When full capacity is reached, all subsequent append() operations would throw IllegalStateException if this parameter is true, or evict the oldest value if this parameter is false.

EvictingRingBuffer

public EvictingRingBuffer(int capacity,
                          @Nullable
                          T defaultValue)

Parameters:

capacity - desired capacity.

defaultValue - pre-fill the buffer with this default value.

EvictingRingBuffer

public EvictingRingBuffer(int capacity,
                          boolean throwOnOverflow,
                          @Nullable
                          T defaultValue)

Parameters:

capacity - desired capacity.

throwOnOverflow - disables auto-eviction on overflow. When full capacity is reached, all subsequent append() operations would throw IllegalStateException if this parameter is true, or evict the oldest value if this parameter is false.

defaultValue - pre-fill the buffer with this default value.

EvictingRingBuffer

protected EvictingRingBuffer(int capacity,
                             boolean throwOnOverflow,
                             @Nullable
                             T defaultValue,
                             boolean preFill)

Method Detail

capacity

public int capacity()

Returns buffer capacity (i.e. max number of elements this buffer can hold).

Returns:

buffer capacity

iterator

@Nonnull
public Iterator<T> iterator()

Specified by:

iterator in interface Collection<T>

Specified by:

iterator in interface Iterable<T>

Specified by:

iterator in class AbstractCollection<T>

size

public int size()

Returns number of elements in the buffer.

Specified by:

size in interface Collection<T>

Specified by:

size in class AbstractCollection<T>

Returns:

number of elements

get

public T get(int index)

Return the element at the specified position in the buffer.

Parameters:

index - index of the element to return

Returns:

the element at the specified position in the buffer

Throws:

IndexOutOfBoundsException - if the index is out of range (index < 0 || index >= size())

add

public boolean add(T value)

Add a value at the end of the ring buffer.

Specified by:

add in interface Collection<T>

Specified by:

add in interface Queue<T>

Overrides:

add in class AbstractCollection<T>

Parameters:

value - element to be appended to the end of the buffer

Returns:

true (as specified by Collection.add(Object))

Throws:

IllegalStateException - if the element cannot be added at this time due to capacity restrictions

offer

public boolean offer(T value)

Inserts the specified element into this queue if it is possible to do so immediately without violating capacity restrictions.

Specified by:

offer in interface Queue<T>

Parameters:

value - element to insert

Returns:

true if the element was added, else false

toList

public List<T> toList()

Returns a List<T> containing all the elements in the buffer in proper sequence (first to last element).

Returns:

a List<T> containing all the elements in the buffer in proper sequence

toArray

@Nonnull
public Object[] toArray()

Specified by:

toArray in interface Collection<T>

Overrides:

toArray in class AbstractCollection<T>

remove

public T remove()

Retrieves and removes the head of this buffer.

Specified by:

remove in interface Queue<T>

Returns:

removed element

Throws:

NoSuchElementException - if buffer is empty

poll

public T poll()

Retrieves and removes the head of this buffer, or returns null if empty.

Specified by:

poll in interface Queue<T>

Returns:

the head of this buffer or null if empty

element

public T element()

Retrieves, but does not remove, the head of this buffer. This method differs from peek only in that it throws an exception if empty.

Specified by:

element in interface Queue<T>

Returns:

the head of this buffer

peek

public T peek()

Retrieves, but does not remove, the head of this buffer, or returns null if empty.

Specified by:

peek in interface Queue<T>

Returns:

the head of this buffer or null if empty

hashCode

public int hashCode()

Specified by:

hashCode in interface Collection<T>

Overrides:

hashCode in class Object

equals

public boolean equals(Object obj)

Specified by:

equals in interface Collection<T>

Overrides:

equals in class Object

clone

public Object clone()
             throws CloneNotSupportedException

Overrides:

clone in class Object

Throws:

CloneNotSupportedException