ChronicleQueue (OpenHFT/Chronicle-Queue 5.22.22 API)

All Superinterfaces:

AutoCloseable, Closeable, net.openhft.chronicle.core.io.QueryCloseable

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

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Default 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.
`@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.
`default net.openhft.chronicle.core.values.LongValue`	`indexForId(String id)`
`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`	`lastIndex()` Returns the index of the last non-metadata excerpt written to this ChronicleQueue, or -1 if the queue is empty.
`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()` Refreshes this ChronicleQueue's view of the directory used for storing files.
`@NotNull RollCycle`	`rollCycle()` Returns the `RollCycle` for this ChronicleQueue.
`static @NotNull 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 @NotNull SingleChronicleQueueBuilder`	`singleBuilder()` Creates and returns a new `SingleChronicleQueueBuilder`.
`static @NotNull 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 @NotNull 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 @NotNull 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

Methods inherited from interface net.openhft.chronicle.core.io.QueryCloseable
isClosed, isClosing

- Method Detail
  - single
```
@NotNull
static @NotNull 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
```
@NotNull
static @NotNull SingleChronicleQueueBuilder singleBuilder()
```
    Creates and returns a new SingleChronicleQueueBuilder.
    The builder can be used to build a ChronicleQueue.
    
    Returns:
    
    a new SingleChronicleQueueBuilder
  - singleBuilder
```
@NotNull
static @NotNull 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
```
@NotNull
static @NotNull 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
```
@NotNull
static @NotNull 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. A Tailer is NOT thread-safe. A Tailer can be created by one Thread and might be used by at most one other Thread.. Sharing a Tailer across threads is unsafe and will inevitably lead to errors and unspecified behaviour.
    The tailor is created at the start, so unless you are using named tailors, this method is the same as calling `net.openhft.chronicle.queue.ChronicleQueue#createTailer(java.lang.String).toStart()`
    
    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 Tailer. Any new Tailer with a previously used id will continue where the old one left off. A Tailer is NOT thread-safe. A Tailer can be created by one Thread and might be used by at most one other Thread.. Sharing a Tailer across threads is unsafe and will inevitably lead to errors and unspecified behaviour.
    If the provided id is null, the Tailer 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()
  - indexForId
```
default net.openhft.chronicle.core.values.LongValue indexForId(String id)
```
  - 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.
    An Appender is NOT thread-safe and, in addition to that, confined to be used by the creating thread only.. Sharing an Appender across threads is unsafe and will inevitably lead to errors and unspecified 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
  - 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
  - lastIndex
```
long lastIndex()
```
    Returns the index of the last non-metadata excerpt written to this ChronicleQueue, or -1 if the queue is empty.
    The value returned by this method will not be reliable in the event the queue is being written to concurrently, as subsequent excerpts may have been written by the time it is returned.
    
    Returns:
    
    The highest non-metadata index available for this ChronicleQueue, or -1 if the queue is empty
  - 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. Source is is used to identify the queue in MessageHistory
    The source id is non-negative.
    
    Returns:
    
    the source id
  - methodWriter
```
@NotNull
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. A method writer is NOT thread-safe and, in addition to that, confined to be used by the creating thread only.. Sharing a method writer across threads is unsafe and will inevitably lead to errors and unspecified 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.
    A method writer is NOT thread-safe and, in addition to that, confined to be used by the creating thread only.. Sharing a method writer across threads is unsafe and will inevitably lead to errors and unspecified 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
```
@NotNull
@NotNull 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()
```
    Refreshes 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

Method Summary

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

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

Method Detail

single

singleBuilder

singleBuilder

singleBuilder

singleBuilder

createTailer

createTailer

indexForId

acquireAppender

firstIndex

lastIndex

wireType

clear

file

fileAbsolutePath

dump

dump

dump

sourceId

methodWriter

methodWriterBuilder

rollCycle

time

deltaCheckpointInterval

lastIndexReplicated

lastAcknowledgedIndexReplicated

lastIndexReplicated

lastAcknowledgedIndexReplicated

refreshDirectoryListing

dumpLastHeader