Module org.cojen.tupl
Package org.cojen.tupl.repl

Interface Replicator

All Superinterfaces:
AutoCloseable, Closeable
All Known Subinterfaces:
MessageReplicator, StreamReplicator
public interface Replicator extends Closeable
Defines common features available to all types of replicators.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static interface 
    Replicator.Accessor
    Direct interface for accessing replication data, for a given term.
    static interface 
    Replicator.Reader
    Direct interface for reading from a replicator, for a given term.
    static interface 
    Replicator.Writer
    Direct interface for writing to a replicator, for a given term.

  • Method Summary

    Modifier and Type
    Method
    Description
    long
    commitPosition()
    Returns the highest observed commit position overall.
    void
    compact(long position)
    Permit all data lower than the given position to be deleted, freeing up space in the log.
    Socket
    connect(SocketAddress addr)
    Connect to any replication group member, for any particular use.
    long
    encoding()
    Return a constant non-zero value which identifies the replicator implementation and its encoding format.
    boolean
    failover()
    Attempt to switch the replication role from leader to replica.
    boolean
    isReadable(long position)
    Returns true if committed data exists at the given position.
    SocketAddress
    localAddress()
     
    long
    localMemberId()
     
    Role
    localRole()
    Returns the effective local role, as known by the group.
    Replicator.Reader
    newReader(long position, boolean follow)
    Returns a new reader which accesses data starting from the given position.
    Replicator.Writer
    newWriter()
    Returns a new writer for the leader to write into, or else returns null if the local member isn't the leader.
    Replicator.Writer
    newWriter(long position)
    Returns a new writer for the leader to write into, or else returns null if the local member isn't the leader.
    SnapshotReceiver
    requestSnapshot(Map<String,String> options)
    Connect to a remote replication group member, for receiving a database snapshot.
    SnapshotReceiver
    restore(Map<String,String> options)
    Start by receiving a snapshot from another group member, expected to be called only by newly joined members.
    void
    snapshotRequestAcceptor(Consumer<SnapshotSender> acceptor)
    Install a callback to be invoked when a snapshot is requested by a new group member.
    void
    socketAcceptor(Consumer<Socket> acceptor)
    Install a callback to be invoked when plain connections are established to the local group member.
    void
    start()
    Start accepting replication data, to be called for new or existing members.
    void
    sync()
    Durably persist all data up to the highest position.
    boolean
    syncCommit(long position, long nanosTimeout)
    Returns immediately if all data up to the given committed position is durable, or else durably persists all data up to the highest position.

    Methods inherited from interface java.io.Closeable

    close

  • Method Details

    • encoding

      long encoding()
      Return a constant non-zero value which identifies the replicator implementation and its encoding format. Value should be chosen randomly, so as not to collide with other implementations.

    • start

      void start() throws IOException
      Start accepting replication data, to be called for new or existing members. For newly restored members, the start method must be called to update its role.
      Throws:
      IOException

    • restore

      SnapshotReceiver restore(Map<String,String> options) throws IOException
      Start by receiving a snapshot from another group member, expected to be called only by newly joined members. New members are initially restoring, so call the start method after restoration to update the role.
      Parameters:
      options - requested options; can pass null if none
      Returns:
      null if no snapshot could be found and replicator hasn't started
      Throws:
      ConnectException - if a snapshot was found, but requesting it failed
      IllegalStateException - if already started
      IOException

    • requestSnapshot

      SnapshotReceiver requestSnapshot(Map<String,String> options) throws IOException
      Connect to a remote replication group member, for receiving a database snapshot. An acceptor must be installed on the group member being connected to for the request to succeed.

      The sender is selected as the one which has the fewest count of active snapshot sessions. If all the counts are the same, then a sender is instead randomly selected, favoring a follower over a leader.

      Parameters:
      options - requested options; can pass null if none
      Returns:
      null if no snapshot could be found
      Throws:
      ConnectException - if a snapshot was found, but requesting it failed
      IOException

    • snapshotRequestAcceptor

      void snapshotRequestAcceptor(Consumer<SnapshotSender> acceptor)
      Install a callback to be invoked when a snapshot is requested by a new group member.
      Parameters:
      acceptor - acceptor to use, or pass null to disable

    • isReadable

      boolean isReadable(long position)
      Returns true if committed data exists at the given position.
      Throws:
      IllegalStateException - if replicator is closed

    • newReader

      Replicator.Reader newReader(long position, boolean follow)
      Returns a new reader which accesses data starting from the given position. The reader returns EOF whenever the end of a term is reached. At the end of a term, try to obtain a new writer to determine if the local member has become the leader.

      When passing true for the follow parameter, a reader is always provided at the requested position. When passing false for the follow parameter, null is returned if the current member is the leader for the given position.

      Note: Reader instances are not expected to be thread-safe.

      Parameters:
      position - position to start reading from, known to have been committed
      follow - pass true to obtain an active reader, even if local member is the leader
      Returns:
      reader or possibly null when follow is false
      Throws:
      InvalidReadException - if position is lower than the start position, or if position is higher than the commit position
      IllegalStateException - if replicator is closed

    • newWriter

      Replicator.Writer newWriter()
      Returns a new writer for the leader to write into, or else returns null if the local member isn't the leader. The writer stops accepting messages when the term has ended, and possibly another leader has been elected.

      Note: Writer instances are not expected to be thread-safe.

      Returns:
      writer or null if not the leader
      Throws:
      IllegalStateException - if an existing writer for the current term already exists

    • newWriter

      Replicator.Writer newWriter(long position)
      Returns a new writer for the leader to write into, or else returns null if the local member isn't the leader. The writer stops accepting messages when the term has ended, and possibly another leader has been elected.

      Note: Writer instances are not expected to be thread-safe.

      Parameters:
      position - expected position to start writing from as leader; method returns null if the given position is lower
      Returns:
      writer or null if not the leader
      Throws:
      IllegalArgumentException - if the given position is negative
      IllegalStateException - if an existing writer for the current term already exists

    • syncCommit

      boolean syncCommit(long position, long nanosTimeout) throws IOException
      Returns immediately if all data up to the given committed position is durable, or else durably persists all data up to the highest position.
      Parameters:
      position - committed position required to be durable
      nanosTimeout - relative nanosecond time to wait; infinite if <0
      Returns:
      false if timed out
      Throws:
      IllegalStateException - if position is too high
      IOException

    • compact

      void compact(long position) throws IOException
      Permit all data lower than the given position to be deleted, freeing up space in the log.
      Parameters:
      position - lowest position which must be retained
      Throws:
      IOException

    • commitPosition

      long commitPosition()
      Returns the highest observed commit position overall. This commit position might be higher than what can be currently applied, if gaps exist in the log.

    • localMemberId

      long localMemberId()

    • localAddress

      SocketAddress localAddress()

    • localRole

      Role localRole()
      Returns the effective local role, as known by the group. Changes to the role don't become effective until proposed by the leader, committed, and then applied.

    • connect

      Socket connect(SocketAddress addr) throws IOException
      Connect to any replication group member, for any particular use. An acceptor must be installed on the group member being connected to for the connect to succeed.
      Throws:
      IllegalArgumentException - if address is null
      ConnectException - if not given a member address or if the connect fails
      IOException

    • socketAcceptor

      void socketAcceptor(Consumer<Socket> acceptor)
      Install a callback to be invoked when plain connections are established to the local group member. No new connections are accepted (of any type) until the callback returns.
      Parameters:
      acceptor - acceptor to use, or pass null to disable

    • sync

      void sync() throws IOException
      Durably persist all data up to the highest position. The highest term, the highest position, and the commit position are all recovered when reopening the replicator. Incomplete data beyond this is discarded.
      Throws:
      IOException

    • failover

      boolean failover() throws IOException
      Attempt to switch the replication role from leader to replica. If successful, or if already a replica, true is returned. When false is returned, the role is likely still the leader, possibly because no replicas exist to failover to.
      Throws:
      IOException