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