Segment (Copycat API Reference (1.1.4))

java.lang.Object
- io.atomix.copycat.server.storage.Segment

All Implemented Interfaces:

AutoCloseable
```
public class Segment
extends Object
implements AutoCloseable
```
Stores a sequence of entries with monotonically increasing indexes in a Buffer.
Segments are individual file or memory based groups of sequential entries. Each segment has a fixed capacity in terms of either number of entries or size in bytes.
The SegmentDescriptor describes the metadata for the segment, including the starting index of the segment and various configuration options. The descriptor is persisted in 48 bytes at the head of the segment.
Internally, each segment maintains an in-memory index of entries. The index stores the offset and position of each entry within the segment's internal Buffer. For entries that are appended to the log sequentially, the index has an O(1) lookup time. For instances where entries in a segment have been skipped (due to log compaction), the lookup time is O(log n) due to binary search. However, due to the nature of the Raft consensus algorithm, readers should typically benefit from O(1) lookups.
When a segment is constructed, the segment will attempt to rebuild its index from the underlying segment Buffer. This is done by reading a 32-bit length and 64-bit offset for each entry. Once the segment has been built, new entries will be appended at the end of the segment.
Additionally, segments are responsible for keeping track of entries that have been released. Entry liveness is tracked in an internal BitArray with a size equal to the segment's entry count().
An entry in the log is written in binary format. The binary format of an entry is as follows:
- Required 32-bit entry length
- Required 64-bit offset
- Required 8-bit term flag
- Optional 64-bit term
Author:

Jordan Halterman

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`long`	`append(io.atomix.copycat.server.storage.entry.Entry entry)` Commits an entry to the segment.
`void`	`close()`
`boolean`	`contains(long index)` Returns a boolean value indicating whether the entry at the given index is active.
`int`	`count()` Returns the count of all entries in the segment.
`void`	`delete()` Deletes the segment.
`SegmentDescriptor`	`descriptor()` Returns the `SegmentDescriptor` for the segment.
`SegmentFile`	`file()` Returns the segment file.
`long`	`firstIndex()` Returns the index of the first entry in the segment.
`Segment`	`flush()` Flushes the segment buffers to disk.
`<T extends io.atomix.copycat.server.storage.entry.Entry> T`	`get(long index)` Reads the entry at the given index.
`boolean`	`isCompacted()` Returns a boolean value indicating whether the segment has been compacted.
`boolean`	`isEmpty()` Returns a boolean value indicating whether the segment is empty.
`boolean`	`isFull()` Returns a boolean value indicating whether the segment is full.
`boolean`	`isLive(long index)` Returns a boolean value indicating whether the given index was released from the segment.
`boolean`	`isOpen()` Returns a boolean value indicating whether the segment is open.
`long`	`lastIndex()` Returns the index of the last entry in the segment.
`long`	`length()` Returns the current range of the segment.
`long`	`nextIndex()` Returns the next index in the segment.
`long`	`offset(long index)` Returns the offset of the given index within the segment.
`io.atomix.copycat.server.storage.util.OffsetPredicate`	`offsetPredicate()` Returns a predicate for live offsets in the segment.
`boolean`	`release(long index)` Releases an entry from the segment.
`long`	`releaseCount()` Returns the number of entries in the segment that have been released.
`long`	`size()` Returns the total size of the segment in bytes.
`Segment`	`skip(long entries)` Skips a number of entries in the segment.
`long`	`term(long index)` Reads the term for the entry at the given index.
`String`	`toString()`
`Segment`	`truncate(long index)` Truncates entries after the given index.

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Method Detail
  - file
```
public SegmentFile file()
```
    Returns the segment file.
    
    Returns:
    
    The segment file.
  - descriptor
```
public SegmentDescriptor descriptor()
```
    Returns the SegmentDescriptor for the segment.
    The segment descriptor is stored in SegmentDescriptor.BYTES bytes at the head of the segment. The descriptor defines essential information about the segment, including its position in the complete Log and its index.
    
    Returns:
    
    The segment descriptor stored at the head of the segment.
  - isOpen
```
public boolean isOpen()
```
    Returns a boolean value indicating whether the segment is open.
    
    Returns:
    
    Indicates whether the segment is open.
  - isEmpty
```
public boolean isEmpty()
```
    Returns a boolean value indicating whether the segment is empty.
    The segment is considered empty if no entries have been written to the segment and no indexes in the segment have been skipped.
    
    Returns:
    
    Indicates whether the segment is empty.
  - isCompacted
```
public boolean isCompacted()
```
    Returns a boolean value indicating whether the segment has been compacted.
    The segment is considered compacted if its SegmentDescriptor.version() is greater than 1.
    
    Returns:
    
    Indicates whether the segment has been compacted.
  - isFull
```
public boolean isFull()
```
    Returns a boolean value indicating whether the segment is full.
    The segment is considered full if one of the following conditions is met:
    - size() is greater than or equal to SegmentDescriptor.maxSegmentSize()
    - count() is greater than or equal to SegmentDescriptor.maxEntries()
    Returns:
    
    Indicates whether the segment is full.
  - size
```
public long size()
```
    Returns the total size of the segment in bytes.
    
    Returns:
    
    The size of the segment in bytes.
  - length
```
public long length()
```
    Returns the current range of the segment.
    The length includes entries that may have been skipped at the end of the segment.
    
    Returns:
    
    The current range of the segment.
  - count
```
public int count()
```
    Returns the count of all entries in the segment.
    The count includes only entries that are physically present in the segment. Entries that have been compacted out of the segment are not counted towards the count, nor are skipped entries.
    
    Returns:
    
    The count of all entries in the segment.
  - firstIndex
```
public long firstIndex()
```
    Returns the index of the first entry in the segment.
    If the segment is empty, 0 will be returned regardless of the segment's base index.
    
    Returns:
    
    The index of the first entry in the segment or 0 if the segment is empty.
    
    Throws:
    
    IllegalStateException - if the segment is not open
  - lastIndex
```
public long lastIndex()
```
    Returns the index of the last entry in the segment.
    
    Returns:
    
    The index of the last entry in the segment or 0 if the segment is empty.
    
    Throws:
    
    IllegalStateException - if the segment is not open
  - nextIndex
```
public long nextIndex()
```
    Returns the next index in the segment.
    
    Returns:
    
    The next index in the segment.
  - offset
```
public long offset(long index)
```
    Returns the offset of the given index within the segment.
    The offset reflects the zero-based offset of the given index in the segment when missing/compacted entries are taken into account. For instance, if a segment contains entries at indexes {1, 3}, the offset of index 1 will be 0 and index 3 will be 1.
    
    Parameters:
    
    index - The index to check.
    
    Returns:
    
    The offset of the given index.
  - append
```
public long append(io.atomix.copycat.server.storage.entry.Entry entry)
```
    Commits an entry to the segment.
    
    Throws:
    
    NullPointerException - if entry is null
    
    IllegalStateException - if the segment is full
    
    IndexOutOfBoundsException - if the entry index does not match the next index
  - term
```
public long term(long index)
```
    Reads the term for the entry at the given index.
    
    Parameters:
    
    index - The index for which to read the term.
    
    Returns:
    
    The term for the given index.
    
    Throws:
    
    IllegalStateException - if the segment is not open or index is inconsistent
  - get
```
public <T extends io.atomix.copycat.server.storage.entry.Entry> T get(long index)
```
    Reads the entry at the given index.
    
    Parameters:
    
    index - The index from which to read the entry.
    
    Returns:
    
    The entry at the given index.
    
    Throws:
    
    IllegalStateException - if the segment is not open or index is inconsistent with the entry
  - contains
```
public boolean contains(long index)
```
    Returns a boolean value indicating whether the entry at the given index is active.
    
    Parameters:
    
    index - The index to check.
    
    Returns:
    
    Indicates whether the entry at the given index is active.
    
    Throws:
    
    IllegalStateException - if the segment is not open
  - release
```
public boolean release(long index)
```
    Releases an entry from the segment.
    
    Parameters:
    
    index - The index of the entry to release.
    
    Returns:
    
    Indicates whether the entry was newly released from the segment.
    
    Throws:
    
    IllegalStateException - if the segment is not open
  - isLive
```
public boolean isLive(long index)
```
    Returns a boolean value indicating whether the given index was released from the segment.
    
    Parameters:
    
    index - The index of the entry to check.
    
    Returns:
    
    Indicates whether the given entry was released from the segment.
    
    Throws:
    
    IllegalStateException - if the segment is not open
  - releaseCount
```
public long releaseCount()
```
    Returns the number of entries in the segment that have been released.
    
    Returns:
    
    The number of entries in the segment that have been released.
    
    Throws:
    
    IllegalStateException - if the segment is not open
  - offsetPredicate
```
public io.atomix.copycat.server.storage.util.OffsetPredicate offsetPredicate()
```
    Returns a predicate for live offsets in the segment.
    
    Returns:
    
    A predicate for live offsets in the segment.
  - skip
```
public Segment skip(long entries)
```
    Skips a number of entries in the segment.
    
    Parameters:
    
    entries - The number of entries to skip.
    
    Returns:
    
    The segment.
    
    Throws:
    
    IllegalStateException - if the segment is not open
  - truncate
```
public Segment truncate(long index)
```
    Truncates entries after the given index.
    
    Parameters:
    
    index - The index after which to remove entries.
    
    Returns:
    
    The segment.
    
    Throws:
    
    IllegalStateException - if the segment is not open
  - flush
```
public Segment flush()
```
    Flushes the segment buffers to disk.
    
    Returns:
    
    The segment.
  - close
```
public void close()
```
    Specified by:
    
    close in interface AutoCloseable
  - delete
```
public void delete()
```
    Deletes the segment.
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object

Class Segment

Method Summary

Methods inherited from class java.lang.Object

Method Detail

file

descriptor

isOpen

isEmpty

isCompacted

isFull

size

length

count

firstIndex

lastIndex

nextIndex

offset

append

term

get

contains

release

isLive

releaseCount

offsetPredicate

skip

truncate

flush

close

delete

toString