ChronicleQueue (OpenHFT/Chronicle-Queue 5.19.6 API)

All Superinterfaces:

AutoCloseable, Closeable

All Known Subinterfaces:

RollingChronicleQueue

All Known Implementing Classes:

SingleChronicleQueue
```
public interface ChronicleQueue
extends net.openhft.chronicle.core.io.Closeable
```
Chronicle (in a generic sense) is a Java project focused on building a persisted low latency messaging framework for high performance and critical applications.
Using non-heap storage options Chronicle provides a processing environment where applications does not suffer from GarbageCollection. GarbageCollection (GC) may slow down your critical operations non-deterministically at any time.. In order to avoid non-determinism and escape from GC delays off-heap memory solutions are addressed. The main idea is to manage your memory manually so does not suffer from GC. Chronicle behaves like a management interface over off-heap memory so you can build your own solutions over it.
Chronicle uses RandomAccessFiles while managing memory and this choice brings lots of possibility. Random access files permit non-sequential, or random, access to a file's contents. To access a file randomly, you open the file, seek a particular location, and read from or writeBytes to that file. RandomAccessFiles can be seen as "large" C-type byte arrays that you can access any random index "directly" using pointers. File portions can be used as ByteBuffers if the portion is mapped into memory.
ChronicleQueue (now in the specific sense) is the main interface for management and can be seen as the "Collection class" of the Chronicle environment. You will reserve a portion of memory and then put/fetch/update records using the ChronicleQueue interface.

ExcerptCommon is the main data container in a ChronicleQueue, each Chronicle is composed of Excerpts. Putting data to a queue means starting a new Excerpt, writing data into it and finishing the Excerpt at the upper.

While ExcerptCommon is a generic purpose container allowing for remote access, it also has more specialized counterparts for sequential operations. See ExcerptTailer and ExcerptAppender

Author:

peter.lawrey

Field Summary

Fields
Modifier and Type Field and Description

static int TEST_BLOCK_SIZE

Fields
Modifier and Type	Field and Description
`static int`	`TEST_BLOCK_SIZE`

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Default Methods Deprecated Methods
Modifier and Type	Method and Description
`@NotNull ExcerptAppender`	`acquireAppender()` Returns a ExcerptAppender for this ChronicleQueue that is local to the current Thread.
`void`	`clear()` Removes all the excerpts in the current ChronicleQueue.
`default @NotNull ExcerptAppender`	`createAppender()` Deprecated. to be remove in version 4.6 or later use `acquireAppender()`
`@NotNull ExcerptTailer`	`createTailer()` Creates and returns a new ExcerptTailer for this ChronicleQueue.
`default @NotNull ExcerptTailer`	`createTailer(String id)` Creates and returns a new ExcerptTailer for this ChronicleQueue with the given unique `id`.
`int`	`deltaCheckpointInterval()` Returns the Delta Checkpoint Interval for this ChronicleQueue.
`@NotNull String`	`dump()` Creates and returns a new String representation of this ChronicleQueue in YAML-format.
`default void`	`dump(@NotNull OutputStream stream, long fromIndex, long toIndex)` Dumps a representation of this ChronicleQueue to the provided `stream` in YAML-format.
`void`	`dump(Writer writer, long fromIndex, long toIndex)` Dumps a representation of this ChronicleQueue to the provided `writer` in YAML-format.
`@NotNull String`	`dumpLastHeader()` Creates and returns a new String representation of this ChronicleQueue's last header in YAML-format.
`@NotNull File`	`file()` Returns the base directory where ChronicleQueue stores its data.
`default @NotNull String`	`fileAbsolutePath()` Returns the absolute path of the base directory where ChronicleQueue stores its data.
`long`	`firstIndex()` Returns the lowest valid index available for this ChronicleQueue, or `Long.MAX_VALUE` if no such index exists.
`long`	`lastAcknowledgedIndexReplicated()` Returns the last index that was replicated and acknowledged by all remote hosts.
`void`	`lastAcknowledgedIndexReplicated(long lastAcknowledgedIndexReplicated)` Sets the last index that has been sent to a remote host.
`long`	`lastIndexReplicated()` Returns the last index that was replicated to a remote host.
`void`	`lastIndexReplicated(long lastIndex)` Sets the last index that has been sent to a remote host.
`default <T> T`	`methodWriter(@NotNull Class<T> tClass, Class... additional)` Creates and returns a new writer proxy for the given interface `tclass` and the given `additional` interfaces.
`default <T> @NotNull net.openhft.chronicle.wire.VanillaMethodWriterBuilder<T>`	`methodWriterBuilder(@NotNull Class<T> tClass)` Creates and returns a new writer proxy for the given interface `tclass`.
`void`	`refreshDirectoryListing()` Refreshed this ChronicleQueue's view of the directory used for storing files.
`RollCycle`	`rollCycle()` Returns the `RollCycle` for this ChronicleQueue.
`static ChronicleQueue`	`single(@NotNull String pathName)` Creates and returns a new `ChronicleQueue` that will be backed by files located in the directory named by the provided `pathName`.
`static SingleChronicleQueueBuilder`	`singleBuilder()` Creates and returns a new `SingleChronicleQueueBuilder`.
`static SingleChronicleQueueBuilder`	`singleBuilder(@NotNull File path)` Creates and returns a new `SingleChronicleQueueBuilder` that will be pre-configured to use files located in the directory of the provided `path`.
`static SingleChronicleQueueBuilder`	`singleBuilder(@NotNull Path path)` Creates and returns a new `SingleChronicleQueueBuilder` that will be pre-configured to use files located in the directory of the provided `path`.
`static SingleChronicleQueueBuilder`	`singleBuilder(@NotNull String pathName)` Creates and returns a new `SingleChronicleQueueBuilder` that will be pre-configured to use files located in the directory named by the provided `pathName`.
`int`	`sourceId()` Returns the source id.
`net.openhft.chronicle.core.time.TimeProvider`	`time()` Returns the `TimeProvider` for this ChronicleQueue.
`@NotNull net.openhft.chronicle.wire.WireType`	`wireType()` Returns the `WireType` used for this ChronicleQueue.

Methods inherited from interface net.openhft.chronicle.core.io.Closeable
close, closeQuietly, closeQuietly, isClosed, notifyClosing

- Field Detail
  - TEST_BLOCK_SIZE
```
static final int TEST_BLOCK_SIZE
```
    See Also:
    
    Constant Field Values
- Method Detail
  - single
```
static ChronicleQueue single(@NotNull
                             @NotNull String pathName)
```
    Creates and returns a new ChronicleQueue that will be backed by files located in the directory named by the provided pathName.
    
    Parameters:
    
    pathName - of the directory to use for storing the queue
    
    Returns:
    
    a new ChronicleQueue that will be stored in the directory given by the provided pathName
    
    Throws:
    
    NullPointerException - if the provided pathName is null.
  - singleBuilder
```
static SingleChronicleQueueBuilder singleBuilder()
```
    Creates and returns a new SingleChronicleQueueBuilder.
    The builder can be used to build a ChronicleQueue.
    
    Returns:
    
    a new SingleChronicleQueueBuilder
  - singleBuilder
```
static SingleChronicleQueueBuilder singleBuilder(@NotNull
                                                 @NotNull String pathName)
```
    Creates and returns a new SingleChronicleQueueBuilder that will be pre-configured to use files located in the directory named by the provided pathName.
    
    Parameters:
    
    pathName - of the directory to pre-configure for storing the queue
    
    Returns:
    
    a new SingleChronicleQueueBuilder that will be pre-configured to use files located in the directory named by the provided pathName
    
    Throws:
    
    NullPointerException - if the provided pathName is null.
  - singleBuilder
```
static SingleChronicleQueueBuilder singleBuilder(@NotNull
                                                 @NotNull File path)
```
    Creates and returns a new SingleChronicleQueueBuilder that will be pre-configured to use files located in the directory of the provided path.
    
    Parameters:
    
    path - of the directory to pre-configure for storing the queue
    
    Returns:
    
    a new SingleChronicleQueueBuilder that will be pre-configured to use files located in the directory named by the provided pathName
    
    Throws:
    
    NullPointerException - if the provided path is null.
  - singleBuilder
```
static SingleChronicleQueueBuilder singleBuilder(@NotNull
                                                 @NotNull Path path)
```
    Creates and returns a new SingleChronicleQueueBuilder that will be pre-configured to use files located in the directory of the provided path.
    
    Parameters:
    
    path - of the directory to pre-configure for storing the queue
    
    Returns:
    
    a new SingleChronicleQueueBuilder that will be pre-configured to use files located in the directory named by the provided pathName
    
    Throws:
    
    NullPointerException - if the provided path is null.
  - createTailer
```
@NotNull
@NotNull ExcerptTailer createTailer()
```
    Creates and returns a new ExcerptTailer for this ChronicleQueue. Tailers are NOT thread-safe. Sharing a Tailer across threads will lead to errors and unpredictable behaviour.
    
    Returns:
    
    a new ExcerptTailer to read sequentially.
    
    See Also:
    
    createTailer(String)
  - createTailer
```
@NotNull
default @NotNull ExcerptTailer createTailer(String id)
```
    Creates and returns a new ExcerptTailer for this ChronicleQueue with the given unique id.
    The id is used to persistently store the latest index for the trailer. Any new Trailer with a previously used id will continue where the old one left off. Tailers are NOT thread-safe. Sharing a Tailer across threads will lead to errors and unpredictable behaviour.
    If the provided id is null, the Trailer will be unnamed and this is equivalent to invoking createTailer().
    
    Parameters:
    
    id - unique id for a tailer which uses to track where it was up to
    
    Returns:
    
    a new ExcerptTailer for this ChronicleQueue with the given unique id
    
    See Also:
    
    createTailer()
  - acquireAppender
```
@NotNull
@NotNull ExcerptAppender acquireAppender()
```
    Returns a ExcerptAppender for this ChronicleQueue that is local to the current Thread.
    An Appender can be used to store new excerpts sequentially to the queue.
    Appenders are NOT thread-safe. Sharing an Appender across threads will lead to errors and unpredictable behaviour.
    This method returns a ThreadLocal appender, so does not produce any garbage, hence it's safe to simply call this method every time an appender is needed.
    
    Returns:
    
    Returns a ExcerptAppender for this ChronicleQueue that is local to the current Thread
  - createAppender
```
@NotNull
 @Deprecated
default @NotNull ExcerptAppender createAppender()
```
    Deprecated. to be remove in version 4.6 or later use acquireAppender()
  - firstIndex
```
long firstIndex()
```
    Returns the lowest valid index available for this ChronicleQueue, or Long.MAX_VALUE if no such index exists.
    
    Returns:
    
    the lowest valid index available for this ChronicleQueue, or Long.MAX_VALUE if no such index exists
  - wireType
```
@NotNull
@NotNull net.openhft.chronicle.wire.WireType wireType()
```
    Returns the WireType used for this ChronicleQueue.
    For example, the WireType could be WireTypes.TEXT or WireTypes.BINARY.
    
    Returns:
    
    Returns the wire type used for this ChronicleQueue
    
    See Also:
    
    WireType
  - clear
```
void clear()
```
    Removes all the excerpts in the current ChronicleQueue.
  - file
```
@NotNull
@NotNull File file()
```
    Returns the base directory where ChronicleQueue stores its data.
    
    Returns:
    
    the base directory where ChronicleQueue stores its data
  - fileAbsolutePath
```
@NotNull
default @NotNull String fileAbsolutePath()
```
    Returns the absolute path of the base directory where ChronicleQueue stores its data.
    This value might be cached, as getAbsolutePath is expensive
    
    Returns:
    
    the absolute path of the base directory where ChronicleQueue stores its data
  - dump
```
@NotNull
@NotNull String dump()
```
    Creates and returns a new String representation of this ChronicleQueue in YAML-format.
    
    Returns:
    
    a new String representation of this ChronicleQueue in YAML-format
  - dump
```
void dump(Writer writer,
          long fromIndex,
          long toIndex)
```
    Dumps a representation of this ChronicleQueue to the provided writer in YAML-format. Dumping will be made from the provided (@code fromIndex) (inclusive) to the provided toIndex (inclusive).
    
    Parameters:
    
    writer - to write to
    
    fromIndex - first index (inclusive)
    
    toIndex - last index (inclusive)
    
    Throws:
    
    NullPointerException - if the provided writer is null
  - dump
```
default void dump(@NotNull
                  @NotNull OutputStream stream,
                  long fromIndex,
                  long toIndex)
```
    Dumps a representation of this ChronicleQueue to the provided stream in YAML-format. Dumping will be made from the provided (@code fromIndex) (inclusive) to the provided toIndex (inclusive).
    
    Parameters:
    
    stream - to write to
    
    fromIndex - first index (inclusive)
    
    toIndex - last index (inclusive)
    
    Throws:
    
    NullPointerException - if the provided writer is null
  - sourceId
```
int sourceId()
```
    Returns the source id.
    The source id is non-negative.
    
    Returns:
    
    the source id
  - methodWriter
```
default <T> T methodWriter(@NotNull
                           @NotNull Class<T> tClass,
                           Class... additional)
```
    Creates and returns a new writer proxy for the given interface tclass and the given additional interfaces.
    When methods are invoked on the returned T object, messages will be put in the queue. Writers are NOT thread-safe. Sharing a Writer across threads will lead to errors and unpredictable behaviour.
    
    Type Parameters:
    
    T - type parameter of the main interface
    
    Parameters:
    
    tClass - of the main interface to be implemented
    
    additional - interfaces to be implemented
    
    Returns:
    
    a new proxy for the given interface tclass and the given additional interfaces
    
    Throws:
    
    NullPointerException - if any of the provided parameters are null.
  - methodWriterBuilder
```
@NotNull
default <T> @NotNull net.openhft.chronicle.wire.VanillaMethodWriterBuilder<T> methodWriterBuilder(@NotNull
                                                                                                           @NotNull Class<T> tClass)
```
    Creates and returns a new writer proxy for the given interface tclass.
    When methods are invoked on the returned T object, messages will be put in the queue.
    Writers are NOT thread-safe. Sharing a Writer across threads will lead to errors and unpredictable behaviour.
    
    Type Parameters:
    
    T - type parameter of the main interface
    
    Parameters:
    
    tClass - of the main interface to be implemented
    
    Returns:
    
    a new proxy for the given interface tclass
    
    Throws:
    
    NullPointerException - if the provided parameter is null.
  - rollCycle
```
RollCycle rollCycle()
```
    Returns the RollCycle for this ChronicleQueue.
    
    Returns:
    
    the RollCycle for this ChronicleQueue
    
    See Also:
    
    RollCycle
  - time
```
net.openhft.chronicle.core.time.TimeProvider time()
```
    Returns the TimeProvider for this ChronicleQueue.
    
    Returns:
    
    the TimeProvider for this ChronicleQueue
    
    See Also:
    
    TimeProvider
  - deltaCheckpointInterval
```
int deltaCheckpointInterval()
```
    Returns the Delta Checkpoint Interval for this ChronicleQueue.
    The value returned is always a power of two.
    
    Returns:
    
    the Delta Checkpoint Interval for this ChronicleQueue
  - lastIndexReplicated
```
long lastIndexReplicated()
```
    Returns the last index that was replicated to a remote host. If no such index exists, returns -1.
    This method is only applicable for replicating queues.
    
    Returns:
    
    the last index that was replicated to a remote host
  - lastAcknowledgedIndexReplicated
```
long lastAcknowledgedIndexReplicated()
```
    Returns the last index that was replicated and acknowledged by all remote hosts. If no such index exists, returns -1.
    This method is only applicable for replicating queues.
    
    Returns:
    
    the last index that was replicated and acknowledged by all remote hosts
  - lastIndexReplicated
```
void lastIndexReplicated(long lastIndex)
```
    Sets the last index that has been sent to a remote host.
    
    Parameters:
    
    lastIndex - last index that has been sent to the remote host.
    
    See Also:
    
    lastIndexReplicated()
  - lastAcknowledgedIndexReplicated
```
void lastAcknowledgedIndexReplicated(long lastAcknowledgedIndexReplicated)
```
    Sets the last index that has been sent to a remote host.
    
    Parameters:
    
    lastAcknowledgedIndexReplicated - last acknowledged index that has been sent to the remote host(s).
    
    See Also:
    
    lastAcknowledgedIndexReplicated()
  - refreshDirectoryListing
```
void refreshDirectoryListing()
```
    Refreshed this ChronicleQueue's view of the directory used for storing files.
    Invoke this method if you delete file from a chronicle-queue directory
    The problem solved by this is that we cache the structure of the queue directory in order to reduce file system adds latency. Calling this method, after deleting .cq4 files, will update the internal caches accordingly,
  - dumpLastHeader
```
@NotNull
@NotNull String dumpLastHeader()
```
    Creates and returns a new String representation of this ChronicleQueue's last header in YAML-format.
    
    Returns:
    
    a new String representation of this ChronicleQueue's last header in YAML-format

Interface ChronicleQueue

Field Summary

Method Summary

Methods inherited from interface net.openhft.chronicle.core.io.Closeable

Field Detail

TEST_BLOCK_SIZE

Method Detail

single

singleBuilder

singleBuilder

singleBuilder

singleBuilder

createTailer

createTailer

acquireAppender

createAppender

firstIndex

wireType

clear

file

fileAbsolutePath

dump

dump

dump

sourceId

methodWriter

methodWriterBuilder

rollCycle

time

deltaCheckpointInterval

lastIndexReplicated

lastAcknowledgedIndexReplicated

lastIndexReplicated

lastAcknowledgedIndexReplicated

refreshDirectoryListing

dumpLastHeader