com.hazelcast.spi.merge

## Class RingbufferMergeData

- java.lang.Object
- - com.hazelcast.spi.merge.RingbufferMergeData

- All Implemented Interfaces:
    Iterable<Object>

      public class RingbufferMergeData
      extends Object
      implements Iterable<Object>

  A ringbuffer implementation holding data involved in split-brain healing.
  Since:
    3.10
  See Also:
    `RingbufferMergingValueImpl`

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `RingbufferMergeData(int capacity)`
    `RingbufferMergeData(com.hazelcast.ringbuffer.impl.Ringbuffer<Object> ringbuffer)`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `long` | `add(Object item)` Adds an item to the tail of the ringbuffer.
    `void` | `clear()` Clears the data in the ringbuffer.
    `int` | `getCapacity()` Returns the capacity of this ringbuffer.
    `long` | `getHeadSequence()` Returns the sequence of the head.
    `Object[]` | `getItems()` Returns the array representing this ringbuffer.
    `long` | `getTailSequence()` Returns the sequence of the tail.
    `Iterator<Object>` | `iterator()` Returns a read-only iterator.
    `<E> E` | `read(long sequence)` Reads one item from the ringbuffer.
    `void` | `set(long seq, Object data)` Sets the item at the given sequence.
    `void` | `setHeadSequence(long sequence)` Sets the head sequence.
    `void` | `setTailSequence(long sequence)` Sets the tail sequence.
    `int` | `size()` Returns number of items in the ringbuffer (meaning the number of items between the `getHeadSequence()` and `getTailSequence()`).

    - ### Methods inherited from class java.lang.Object

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

    - ### Methods inherited from interface java.lang.Iterable

      `forEach, spliterator`

- - ### Constructor Detail

    - #### RingbufferMergeData

          public RingbufferMergeData(int capacity)

    - #### RingbufferMergeData

          public RingbufferMergeData(com.hazelcast.ringbuffer.impl.Ringbuffer<Object> ringbuffer)

  - ### Method Detail

    - #### getTailSequence

          public long getTailSequence()

      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

          public void setTailSequence(long sequence)

      Sets the tail sequence. The tail sequence cannot be less than `headSequence() - 1`.
      Parameters:
        `sequence` - the new tail sequence
      Throws:
        `IllegalArgumentException` - if the target sequence is less than `headSequence() - 1`
      See Also:
        `getHeadSequence()`

    - #### getHeadSequence

          public long getHeadSequence()

      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 `getTailSequence()`.

      The initial value of the head is 0 (1 more than tail).

      Returns:
        the sequence of the head

    - #### setHeadSequence

          public 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`
      See Also:
        `getTailSequence()`

    - #### getCapacity

          public int getCapacity()

      Returns the capacity of this ringbuffer.
      Returns:
        the capacity

    - #### size

          public int size()

      Returns number of items in the ringbuffer (meaning the number of items between the `getHeadSequence()` and `getTailSequence()`).
      Returns:
        the size

    - #### add

          public long add(Object 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

          public <E> E read(long sequence)

      Reads one item from the ringbuffer.
      Type Parameters:
        `E` - ringbuffer item type
      Parameters:
        `sequence` - the sequence of the item to read
      Returns:
        the ringbuffer item
      Throws:
        `StaleSequenceException` - if the sequence is smaller then `getHeadSequence()` or larger than `getTailSequence()`

    - #### set

          public void set(long seq,
                          Object data)

      Sets the item at the given sequence. The method allows `null` data.
      Parameters:
        `seq` - the target sequence
        `data` - the data to be set

    - #### clear

          public void clear()

      Clears the data in the ringbuffer.

    - #### getItems

          public Object[] getItems()

      Returns the array representing this ringbuffer.

      Items at the beginning of this array may have higher sequence IDs than items at the end of this array. This means that this array is not sorted by sequence ID and the index of the item in this array must be calculated using the sequence and the modulo of the array.

    - #### iterator

          public Iterator<Object> iterator()

      Returns a read-only iterator. Mutation methods will throw a `UnsupportedOperationException`.
      Specified by:
        `iterator` in interface `Iterable<Object>`

Copyright © 2020. All rights reserved.