(01)Chronicle Queue 入门

本节帮助您在几分钟内开始使用Chronicle Queue。这个过程可以总结为五个步骤:

1. [安装Chronicle Queue]
2. [创建一个新队列]
3. [写入队列]
4. [从队列中读取]
5. [清理]
6. [把它们组合在一起]

本文提供的指南并不打算详尽地解释这些步骤，而是提供足够的信息，帮助您快速启动和运行。因此，在整个Chronicle Queue文档中对大多数主题进行了更深入的解释。

要求

在开始设置之前，请确保您的开发环境满足以下要求：

• Maven 3.6.x 或者 更高版本
• Java 8 update 180+ 更高版本
• 访问互联网以允许 Maven 或 Gradle 下载所需的 JAR

安装Chronicle Queue

通过通知您的构建工具需要 Chronicle Queue 依赖项来编译您的源代码来执行安装。 以下是使用 Maven 或 Gradle 进行安装的说明。

Maven

通过在项目的 pom.xml 文件中添加以下代码，使用 Maven 安装 Chronicle Queue：

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

<1>: 将替换为 Maven Central 上的最新版本。

Gradle

通过在项目的 build.gradle 文件中添加以下代码，使用 Gradle 安装 Chronicle Queue：

dependencies {
  implementation 'net.openhft:chronicle-queue:<Latest version>'   // <1>
}

<1>: 将替换为 Maven Central 上的最新版本。

Chronicle Queue 的 Hello World

现在安装已完成，是时候创建第一个队列并尝试从中附加和读取消息了。

创建一个新队列

一个新的 Chronicle Queue 是通过将字段 singleBuilder 传递给要存储队列的路径从构建器获得的。 下面的示例创建了一个 IndexedChronicle，它创建了两个 RandomAccessFiles； 一种用于索引，一种用于具有相对名称的数据：

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

队列文件将位于getting-started目录中，文件以当前日期命名，格式如下：

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

写入队列

使用 appender 将消息写入或附加到队列中。 appender 仅将消息写入队列的末尾，无法在特定位置插入消息。

以下是添加一条包含文本 “Hello World!” 的简单文本消息的方法：

ExcerptAppender appender = queue.acquireAppender();   // <1>

appender.writeText("Hello World!");                   // <2>

<1>: 创建一个 appender
<2>: 写 “Hello World!” 到队列

Appender: 一个appender是消息源。您可以通过将数据附加到Chronicle Queue来添加数据。顺序写只能通过追加到队列的末尾来执行。没有办法插入或删除摘录。

从队列中读取

从队列中读取 a 最简单的方法是使用 tailer，即“ExcerptTailer”。 术语 tailing 源于从队列的尾部读取，即队列的末尾。 但是，您并不仅限于使用 tailer 从队列末尾读取数据。

以下是它如何用于读取刚刚写入队列的 “Hello World” 消息：

ExcerptTailer tailer = queue.createTailer();       // <1>

assertEquals("Hello World!", tailer.readText());   // <2>

<1>: 创建一个 tailer
<2>: 从队列中读取写好的消息 “Hello World!”

📝注意: 译者在这里提醒, queue.createTailer() 创建的tailer会一直读取队列尾部的消息而不会移动指针.如果想像普通读取需要使用 queue.createTailer(“读取者ID”) 方法!这种做法的好处是,可以有任意个读取者来读取队列的消息而互不干扰,Chronicle Queue创建的队列类似于"扇形队列".

Tailer: Tailer 是针对顺序读取优化的摘录阅读器。 它可以执行顺序和随机读取，包括向前和向后。 Tailer 每次被调用时都会阅读下一条可用消息。

您还可以使用 dump() 方法将队列的原始内容转储到控制台：

queue.dump();

清理

Chronicle Queue 将其数据存储在堆外，因此建议您在使用完 Chronicle Queue 后调用 .close() 以释放资源。

queue.close();

🔔重要: 关闭队列时不会丢失任何数据。 此过程仅清理在运行时使用的资源。

把它们组合在一起

将这些代码放在一起，应用程序如下所示：

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

    ExcerptAppender appender = queue.acquireAppender();
    appender.writeText("TestMessage");

    ExcerptTailer tailer = queue.createTailer();
    assertEquals("TestMessage", tailer.readText());

    queue.close();
}

原文链接: (https://docs.chronicle.software/chronicle-queue/chronicle-queue/getting-started/quick-start.html)

---

<<<<<<<<<<<< [完] >>>>>>>>>>>>