Annotation Interface JGroupsRaftStateMachine

@Target(TYPE) @Retention(RUNTIME) public @interface JGroupsRaftStateMachine
Marks a class as a Raft state machine.

This annotation is required to identify the state machine implementation that will process committed log entries in the Raft cluster. JGroups Raft uses this marker internally when initializing the Raft instance. The class with this annotation is provided to JGroupsRaft.builder(Object, Class) during the instance creation. Only one class per Raft instance should be annotated with this marker.

State Machine Requirements

To function correctly in a distributed consensus algorithm, the state machine must satisfy:

  • Determinism: Given the same sequence of operations, all replicas must produce identical results and reach the same state. The implementation should not utilize non-deterministic mechanisms. It should always be deterministic.
  • Sequential consistency: Operations must be applied in the exact order they appear in the committed log.
  • No side effects: Operations should not perform external I/O, network calls, or other non-deterministic actions that could cause replica divergence.

Since:
2.0
Author:
José Bolina
See Also:

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    StateMachineRead[]
    retiredReads
    Declares read operations that have been permanently removed from this state machine.
    StateMachineWrite[]
    retiredWrites
    Declares write operations that have been permanently removed from this state machine.

  • Element Details

    • retiredReads

      StateMachineRead[] retiredReads
      Declares read operations that have been permanently removed from this state machine.

      When a read operation is removed from the state machine interface, existing Raft logs may still contain entries referencing that operation's (id, version) pair. Declaring the removed operation here tells the schema validator that the removal is intentional, preventing a startup failure.

      A retired operation cannot be reused — its (id, version) pair is permanently reserved. Only retire an operation after ensuring no uncompacted log entries reference it. You can utilize the JGroupsRaftAdministration.snapshot() to ensure entries in the log are compacted.

      Example

      // The read operation (id=2, version=1) was removed from the interface.
// Declare it as retired to allow the node to start without validation errors.
@JGroupsRaftStateMachine(
    retiredReads = @StateMachineRead(id = 2, version = 1)
)
public interface MyStateMachine {
    @StateMachineWrite(id = 1, version = 1)
    void put(String key, String value);
}
      Returns:
      the retired read operations, empty by default
      See Also:
      Default:
      {}

    • retiredWrites

      StateMachineWrite[] retiredWrites
      Declares write operations that have been permanently removed from this state machine.

      When a write operation is removed from the state machine interface, existing Raft logs may still contain entries referencing that operation's (id, version) pair. Declaring the removed operation here tells the schema validator that the removal is intentional, preventing a startup failure.

      A retired operation cannot be reused — its (id, version) pair is permanently reserved. Only retire an operation after ensuring no uncompacted log entries reference it. You can utilize the JGroupsRaftAdministration.snapshot() to ensure entries in the log are compacted.

      Example

      // The write operation (id=1, version=1) was removed from the interface.
// Declare it as retired to allow the node to start without validation errors.
@JGroupsRaftStateMachine(
    retiredWrites = @StateMachineWrite(id = 1, version = 1)
)
public interface MyStateMachine {
    @StateMachineWrite(id = 2, version = 2)
    void put(String key, String value, int ttl);
}
      Returns:
      the retired write operations, empty by default
      See Also:
      Default:
      {}