Disclaimer
Apache Incubator Apache Ratis is an effort undergoing incubation at The Apache Software Foundation (ASF), sponsored by the Apache Incubator PMC. Incubation is required of all newly accepted projects until a further review indicates that the infrastructure, communications, and decision making process have stabilized in a manner consistent with other successful ASF projects. While incubation status is not necessarily a reflection of the completeness or stability of the code, it does indicate that the project has yet to be fully endorsed by the ASF.

What is Apache Ratis™?

Apache Ratis is a highly customizable Raft protocol implementation in Java.

Raft is a easily understandable consensus algorithm to manage replicated state.

Apache Ratis could be used in any Java application where state should be replicated between multiple instances.

Features

Pluggable transport

Ratis provides a pluggable transport layer. By default gRPC, Netty+Protobuf and Apache Hadoop RPC based transports are provided.

Pluggable state machine

Ratis supports a log and state machine. State machine typically contains the data that you want to make highly avialable. Ratis makes it easy to use your own state machine.

Pluggable raft log

RAFT log is also pluggable, users can provide their own log implementation. The default implementation stores log in local files.

Application can define the polices of how to write data and where it should be written easily.

Download

Apache Ratis is a Java library that can be used directly from your applications.

It is released as source code tarballs. The downloads are distributed via mirror sites and should be checked for tampering using GPG or SHA-256

The source tarball contains detailed instruction about how can it be built.

The binaries are also uploaded to the maven central for convenience. (See the getting started guide for more details)

Version Release date Source download Binary download Announcement
0.2.0 2018 Jul 15 source (checksum signature) binary (checksum signature) Announcement
0.1.0-alpha 2017 May 2 source (checksum signature) Announcement

Ratis is also available from the Maven central repository.

Getting started

Ratis is a Raft protocol library in Java. It’s not a standalone server application like Zookeeper or Consul.

Examples

To demonstrate how to use Ratis from the code, Please look at the following examples.

  • Arithmetic example: This is a simple distributed calculator that replicates the values defined and allows user to perform arithmetic operations on these replicated values.

  • FileStore example: This is an example of using Ratis for reading and writing files.

The source code the examples could be found in the ratis-examples subproject.

Arithmetic example also has some simple cli script to start it:

  1. First do a full build on the ratis source code: mvn clean install -DskipTests
  2. Go the the bin directory of the examples: cd ratis-examples/src/main/bin
  3. Start three Ratis server instances (with arithmetic state matchine). ./start-all (This helper script starts 3 Java instances in the background).
  4. Create a new variable in the state machine: ./client.sh assign --name a --value 3
  5. Assign a new variable: ./client.sh assign --name b --value a+5
  6. Get a variable from the state machine: ./client.sh get --name b

Maven usage

To use in our project you can access the latest binaries from maven central:

<dependency>
   <artifactId>ratis-server</artifactId>
   <groupId>org.apache.ratis</groupId>
</dependency>

You also need to include one of the transports:

<dependency>
   <artifactId>ratis-netty</artifactId>
   <groupId>org.apache.ratis</groupId>
</dependency>
 <dependency>
   <groupId>org.apache.ratis</groupId>
   <artifactId>ratis-grpc</artifactId>
</dependency>
    <dependency>
      <groupId>org.apache.ratis</groupId>
      <artifactId>ratis-hadoop-shaded</artifactId>
    </dependency>

Please note that Apache Hadoop dependencies are shaded, so it’s safe to use hadoop transport with different versions of Hadoop.

Community

Mailing list

Developers

If you’d like to contribute to Apache Ratis, please subscribe to the Ratis developer mailing list.

The Ratis developer mailing list is: dev@ratis.incubator.apache.org.

User

The user@ mailing list is the preferred mailing list for end-user questions and discussion.

Please use dev mailing list to address developers on a specific technical question.

The Ratis user mailing list is: user@ratis.incubator.apache.org.

To post to the list, it is necessary to subscribe to it.

Slack

There is also a slack instance for discussion at https://apacheratisdev.slack.com. Please write to the mailing list if you need an invite.

Source

Source code is part of every release, you can download the source bundles from download section and build the project according to the included instructions.

The versioned source code history is available from the Apache git repository or from the github mirror. It is only for development and not intended for use by the general public. Only the source code from the released artifacts are checked by the Project Management Committee.