Ringbuffer (Hazelcast Root 3.8 API)

Type Parameters:

T - the type of the data stored in the ring buffer

All Known Implementing Classes:

ArrayRingbuffer
```
public interface Ringbuffer<T>
```
The Ringbuffer is responsible for storing the actual content of a ringbuffer.

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`long`	`add(T item)` Adds an item to the tail of the Ringbuffer.
`void`	`checkBlockableReadSequence(long readSequence)` Check if the sequence can be read from the ring buffer or if the sequence is of the next item to be added into the ringbuffer.
`void`	`checkReadSequence(long sequence)` Check if the sequence can be read from the ring buffer.
`long`	`getCapacity()` Returns the capacity of this Ringbuffer.
`long`	`headSequence()` Returns the sequence of the head.
`boolean`	`isEmpty()` Is the ring buffer empty.
`T`	`read(long sequence)` Reads one item from the Ringbuffer.
`void`	`set(long seq, T data)` Sets the item at the given sequence.
`void`	`setHeadSequence(long sequence)` Sets the head sequence.
`void`	`setTailSequence(long tailSequence)` Sets the tail sequence.
`long`	`size()` Returns number of items in the ringbuffer (meaning the number of items between the `headSequence()` and `tailSequence()`).
`long`	`tailSequence()` Returns the sequence of the tail.

- Method Detail
  - getCapacity
```
long getCapacity()
```
    Returns the capacity of this Ringbuffer.
    
    Returns:
    
    the capacity.
  - size
```
long size()
```
    Returns number of items in the ringbuffer (meaning the number of items between the headSequence() and tailSequence()).
    
    Returns:
    
    the size.
  - tailSequence
```
long tailSequence()
```
    Returns the sequence of the tail. The tail is the side of the ringbuffer where the items are added to.
    The initial value of the tail is -1.
    
    Returns:
    
    the sequence of the tail.
  - setTailSequence
```
void setTailSequence(long tailSequence)
```
    Sets the tail sequence. The tail sequence cannot be less than headSequence() - 1.
    
    Parameters:
    
    tailSequence - the new tail sequence
    
    Throws:
    
    IllegalArgumentException - if the target sequence is less than headSequence() - 1
  - headSequence
```
long headSequence()
```
    Returns the sequence of the head. The head is the side of the ringbuffer where the oldest items in the ringbuffer are found.
    If the RingBuffer is empty, the head will be one more than the tailSequence().
    The initial value of the head is 0 (1 more than tail).
    
    Returns:
    
    the sequence of the head.
  - setHeadSequence
```
void setHeadSequence(long sequence)
```
    Sets the head sequence. The head sequence cannot be larger than tailSequence() + 1
    
    Parameters:
    
    sequence - The new head sequence.
    
    Throws:
    
    IllegalArgumentException - if the target sequence is greater than tailSequence() + 1
  - isEmpty
```
boolean isEmpty()
```
    Is the ring buffer empty.
    
    Returns:
    
    is the ring buffer empty
  - add
```
long add(T item)
```
    Adds an item to the tail of the Ringbuffer. If there is no space in the Ringbuffer, the add will overwrite the oldest item in the ringbuffer. The method allows null values.
    The returned value is the sequence of the added item. Using this sequence you can read the added item.
    
    Using the sequence as id
    This sequence will always be unique for this Ringbuffer instance so it can be used as a unique id generator if you are publishing items on this Ringbuffer. However you need to take care of correctly determining an initial id when any node uses the ringbuffer for the first time. The most reliable way to do that is to write a dummy item into the ringbuffer and use the returned sequence as initial id. On the reading side, this dummy item should be discard. Please keep in mind that this id is not the sequence of the item you are about to publish but from a previously published item. So it can't be used to find that item.
    
    Parameters:
    
    item - the item to add.
    
    Returns:
    
    the sequence of the added item.
  - read
```
T read(long sequence)
```
    Reads one item from the Ringbuffer.
    This method is not destructive unlike e.g. a queue.take. So the same item can be read by multiple readers or it can be read multiple times by the same reader.
    
    Parameters:
    
    sequence - the sequence of the item to read.
    
    Returns:
    
    the read item
    
    Throws:
    
    StaleSequenceException - if the sequence is smaller then headSequence() or larger than tailSequence(). Because a Ringbuffer won't store all event indefinitely, it can be that the data for the given sequence doesn't exist anymore and the StaleSequenceException is thrown. It is up to the caller to deal with this particular situation, e.g. throw an Exception or restart from the last known head. That is why the StaleSequenceException contains the last known head.
  - checkBlockableReadSequence
```
void checkBlockableReadSequence(long readSequence)
```
    Check if the sequence can be read from the ring buffer or if the sequence is of the next item to be added into the ringbuffer. This method also allows the sequence to be one greater than the tailSequence(), giving the oportunity to block until the item is added into the ring buffer.
    
    Parameters:
    
    readSequence - the sequence wanting to be read
    
    Throws:
    
    StaleSequenceException - if the requested sequence is smaller than the headSequence()
    
    IllegalArgumentException - if the requested sequence is greater than the tailSequence() + 1
  - checkReadSequence
```
void checkReadSequence(long sequence)
```
    Check if the sequence can be read from the ring buffer.
    
    Parameters:
    
    sequence - the sequence wanting to be read
    
    Throws:
    
    StaleSequenceException - if the requested sequence is smaller than the headSequence()
    
    IllegalArgumentException - if the requested sequence is greater than the tailSequence()
  - set
```
void set(long seq,
         T data)
```
    Sets the item at the given sequence. The method allows null data.
    
    Parameters:
    
    seq - The target sequence.
    
    data - The data to be set

Interface Ringbuffer<T>

Method Summary

Method Detail

getCapacity

size

tailSequence

setTailSequence

headSequence

setHeadSequence

isEmpty

add

Using the sequence as id

read

checkBlockableReadSequence

checkReadSequence

set