CHRONICLE QUEUE

Quick Start

Getting Started

This section helps you get started with Chronicle Queue in a few minutes. The process can be summed up in five steps:

  1. Installing Chronicle Queue
  2. Creating a new queue
  3. Writing to a queue
  4. Reading from a queue
  5. Cleaning up

The provided guide does not intend to be an exhaustive explanation of these steps but rather provide enough information to get you up and running quickly. Hence, most of the topics are explained in greater depth throughout the Chronicle Queue documentation.

Requirements

Before starting with the setup, make sure your development environment meets the following requirements:

  • Maven version 3.6.x or later
  • Java 8 update 180 or later
  • Access to the internet to allow Maven or Gradle to download the JARs needed

Installing Chronicle Queue

The installation is performed by notifying your build tool that the Chronicle Queue dependency is required to compile your source code. Below are instructions for installation using Maven or Gradle.

You will need to look up the latest version of Chronicle Queue on Maven Central.

Maven

Install Chronicle Queue with Maven by adding the following code in the project’s pom.xml-file:

<dependency>
  <groupId>net.openhft</groupId>
  <artifactId>chronicle-queue</artifactId>
  <version><!-- Latest version --></version>
</dependency>

Gradle

Install Chronicle Queue with Gradle by adding the following code in the project’s build.gradle file under dependencies:


  implementation 'net.openhft:chronicle-queue:Latest-version'

Hello World with Chronicle Queue

Now that the installation is complete it is time to create a first queue and try appending and reading messages from it.

Creating a New Queue

A new Chronicle Queue is obtained from a builder by passing the field singleBuilder the path where the queue is to be stored. The example below creates an IndexedChronicle which creates two RandomAccessFiles; one for indexes, and one for data having names relatively:

String basePath = OS.getTarget() + "/getting-started"
ChronicleQueue queue = ChronicleQueue.singleBuilder(basePath).build()

The queue files will reside in the directory getting-started and files are named with the current date on the following format:

${java.io.tmpdir}/getting-started/{today}.cq4

Writing to a Queue

Messages are written, or appended, to a queue using an appender. The appender writes messages to the end of the queue only, there is no way to insert messages at a specific location.

Here is how you can append a simple text message containing the text "Hello World!":

ExcerptAppender appender = queue.acquireAppender(); 
appender.writeText("Hello World!");

Reading from a Queue

Reading a from a queue is easiest done using a tailer, namely ExcerptTailer. The term tailing stems from reading from the queue’s tail, i.e. the end of the queue. However, you are not limited to only read from the end of the queue using the tailer.

Here is how it is used to read the "Hello World" message that was just written to the queue:

ExcerptTailer tailer = queue.createTailer(); 
assertEquals("Hello World!", tailer.readText());

You can also dump the raw contents of the queue to the console using the method dump():

System.out.println(queue.dump());

Cleaning Up

Chronicle Queue stores its data off-heap, therefore it is recommended that you call .close() once you have finished working with Chronicle Queue to free up resources. No data will be lost when closing the queue. This procedure only cleans up resources that were used at runtime.

queue.close();

Putting it All Together

Putting these instructions together, the application looks as follows:

String basePath = OS.getTarget() + "/getting-started"
try (ChronicleQueue queue = ChronicleQueue.singleBuilder(basePath).build()) {
    try (ExcerptAppender appender = queue.acquireAppender()) {
        appender.writeText("TestMessage");
    }
    
    try (ExcerptTailer tailer = queue.createTailer()) {
        assertEquals("TestMessage", tailer.readText());
    }
    
    System.out.println(dump.close());
}