Module org.jgroups.raft
Package org.jgroups.raft

Class RaftHandle

java.lang.Object
org.jgroups.raft.RaftHandle
All Implemented Interfaces:
Settable
public class RaftHandle extends Object implements Settable
Main interaction point for applications with jgroups-raft.

Provides methods to make changes, register a state machine, get commit-index and last-applied, register RAFT.RoleChange listeners etc.

Sample use: 
     JChannel ch=createChannel();
     RaftHandle handle=new RaftHandle(ch, new StateMachineImpl()); // implements StateMachine
     handle.addRoleListener(this);
     handle.setAsync(buf, 0, buf.length).whenComplete((buf,ex) -> ...);
Since:
0.2
Author:
Bela Ban

  • Field Details

    • ch

      protected org.jgroups.JChannel ch

    • raft

      protected RAFT raft

    • settable

      protected Settable settable

  • Constructor Details

    • RaftHandle

      public RaftHandle(org.jgroups.JChannel ch, StateMachine sm)
      Creates a RaftHandle instance.
      Parameters:
      ch - The channel over which to create the RaftHandle. Must be non-null, but doesn't yet need to be connected
      sm - An implementation of StateMachine. Can be null, ie. if it is set later via stateMachine(StateMachine).

  • Method Details

    • channel

      public org.jgroups.JChannel channel()

    • raft

      public RAFT raft()

    • raftId

      public String raftId()

    • raftId

      public RaftHandle raftId(String id)

    • leader

      public org.jgroups.Address leader()

    • isLeader

      public boolean isLeader()

    • stateMachine

      public StateMachine stateMachine()

    • stateMachine

      public RaftHandle stateMachine(StateMachine sm)

    • addRoleListener

      public RaftHandle addRoleListener(RAFT.RoleChange listener)

    • removeRoleListener

      public RaftHandle removeRoleListener(RAFT.RoleChange listener)

    • currentTerm

      public long currentTerm()

    • lastApplied

      public long lastApplied()

    • commitIndex

      public long commitIndex()

    • snapshot

      public void snapshot() throws Exception
      Throws:
      Exception

    • log

      public Log log()

    • logSize

      public long logSize()

    • addServer

      public CompletableFuture<byte[]> addServer(String server) throws Exception
      Asynchronously adds a new server to the RAFT cluster.

      Only a single membership change executes at any given time. Multiple concurrent changes are chained and executed serially. The membership change adds an entry to the log, meaning it tolerates crashes and restarts and only has an effect after a majority of members commit it.

      Parameters:
      server - The server RAFT ID to add.
      Returns:
      A CompletableFuture that completes once the command is committed.
      Throws:
      Exception - if dynamic view changes are not enabled.
      IllegalStateException - if the node is not the leader.

    • removeServer

      public CompletableFuture<byte[]> removeServer(String server) throws Exception
      Asynchronously removes a server from the RAFT cluster.
      Parameters:
      server - The server RAFT ID to remove.
      Returns:
      A CompletableFuture that completes once the command is committed.
      Throws:
      Exception - if dynamic view changes are not enabled.
      IllegalStateException - if the node is not the leader.
      See Also:

    • logEntries

      public void logEntries(ObjLongConsumer<LogEntry> func)

    • setAsync

      public CompletableFuture<byte[]> setAsync(byte[] buf, int offset, int length, Options options) throws Exception
      Description copied from interface: Settable
      Asynchronous set, returns immediately with a CompletableFuture. To wait for the result, CompletableFuture.get() or CompletableFuture.get(long, TimeUnit) can be called.
      Specified by:
      setAsync in interface Settable
      Parameters:
      buf - The buffer (usually a serialized command) which represent the change to be applied to all state machines
      offset - The offset into the buffer
      length - he number of bytes to be used in the buffer, starting at offset
      options - Options to pass to the call, may be null
      Returns:
      A CompletableFuture which can be used to fetch the result.
      Throws:
      Exception

    • getAsync

      public CompletableFuture<byte[]> getAsync(byte[] buf, int offset, int length, Options options) throws Exception
      Description copied from interface: Settable
      Asynchronous get operation that returns immediately without blocking.

      This method submits a read-only operation to the state machine. Read-only operations are treated differently by the replication algorithm. Since read-only operations do not change the state-machine state, these operations are not appended to the replicated log.

      Warning: Do not change the state-machine state by operations submitted through this method. Otherwise, the state-machine will diverge and lead to an undefined state.

      Specified by:
      getAsync in interface Settable
      Parameters:
      buf - The buffer representing the read-only operation to submit to the state machine.
      offset - The offset to skip the bytes in the buffer.
      length - The number of bytes to use from the buffer starting at offset.
      options - Options to pass along in the call chain, may be null.
      Returns:
      A buffer representing the result after submitting the read-only operation.
      Throws:
      Exception - Thrown if the operation could not be submitted.