org.cojen.tupl.ext

Interface ReplicationManager

All Superinterfaces:

AutoCloseable, Closeable

public interface ReplicationManager
extends Closeable

Interface which replaces the redo log, for replicating transactional operations. Non-transactional operations, or those with NO_REDO durability will not pass through the replication manager.

See Also:

DatabaseConfig.replicate(org.cojen.tupl.ext.ReplicationManager)

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	ReplicationManager.Writer

Method Summary

Modifier and Type	Method and Description
void	checkpointed(long position) Indicates that all data prior to the given log position has been durably checkpointed.
long	encoding() Return a fixed non-zero value which identifies the replication manager implementation and its encoding format.
default void	fenced(long position) Called after a fence operation has been received and processed.
void	flip() Called to acknowledge mode change from replica to leader, or vice versa.
default void	notifyDrop(Index index) Notification to replica after an index is dropped.
default void	notifyRename(Index index, byte[] oldName, byte[] newName) Notification to replica after an index is renamed.
default void	notifyStore(Index index, byte[] key, byte[] value) Notification to replica when an entry is stored into an index.
int	read(byte[] b, int off, int len) Blocks at most once, reading as much replication input as possible.
long	readPosition() Returns the next position a replica will read from, which must be confirmed.
void	recover(EventListener listener) Called after replication threads have started, providing an opportunity to wait until replication has sufficiently "caught up".
void	start(long position) Start the replication manager in replica mode.
void	sync() Durably flushes all local data to non-volatile storage, up to the current position.
default void	syncConfirm(long position) Durably flushes all local data to non-volatile storage, up to the given confirmed position, and then blocks until fully confirmed.
void	syncConfirm(long position, long timeoutNanos) Durably flushes all local data to non-volatile storage, up to the given confirmed position, and then blocks until fully confirmed.
ReplicationManager.Writer	writer() Returns an object which allows the leader to write changes.

Methods inherited from interface java.io.Closeable

close

Method Detail

encoding

long encoding()

Return a fixed non-zero value which identifies the replication manager implementation and its encoding format. Value should be chosen randomly, so as not to collide with other implementations.

start

void start(long position)
    throws IOException

Start the replication manager in replica mode. Invocation of this method implies that all data lower than the given position is confirmed. All data at or higher than the given position might be discarded.

After started, the reported position must match the one provided to this method. The position can change only after read and write operations have been performed.

Parameters:

position - position to start reading from; 0 is the lowest position

Throws:

IllegalArgumentException - if position is negative

IllegalStateException - if already started

IOException

recover

void recover(EventListener listener)
      throws IOException

Called after replication threads have started, providing an opportunity to wait until replication has sufficiently "caught up". The thread which is opening the database invokes this method, and so it blocks until recovery completes.

Parameters:

listener - optional listener for posting recovery events to

Throws:

IOException

readPosition

long readPosition()

Returns the next position a replica will read from, which must be confirmed. Position is never negative and never retreats.

read

int read(byte[] b,
         int off,
         int len)
  throws IOException

Blocks at most once, reading as much replication input as possible. Returns -1 if local instance has become the leader.

Returns:

amount read, or -1 if leader

Throws:

IllegalStateException - if not started

IOException

flip

void flip()

Called to acknowledge mode change from replica to leader, or vice versa. Until flip is called, all read and write operations fail as if the leadership mode is indeterminate. Reads fail as if the local instance is the leader, and writes fail as if the local instance is a replica.

writer

ReplicationManager.Writer writer()
                          throws IOException

Returns an object which allows the leader to write changes. A new instance is required after a leader transition. Returned object can be null if local instance is a replica.

Throws:

IOException

sync

void sync()
   throws IOException

Durably flushes all local data to non-volatile storage, up to the current position.

Throws:

IOException

syncConfirm

default void syncConfirm(long position)
                  throws IOException

Durably flushes all local data to non-volatile storage, up to the given confirmed position, and then blocks until fully confirmed.

Throws:

ConfirmationFailureException

IOException

syncConfirm

void syncConfirm(long position,
                 long timeoutNanos)
          throws IOException

Durably flushes all local data to non-volatile storage, up to the given confirmed position, and then blocks until fully confirmed.

Parameters:

timeoutNanos - pass -1 for infinite

Throws:

ConfirmationFailureException

IOException

checkpointed

void checkpointed(long position)
           throws IOException

Indicates that all data prior to the given log position has been durably checkpointed. The log can discard the old data. This method is never invoked concurrently, and the implementation should return quickly.

Parameters:

position - log position immediately after the checkpoint position

Throws:

IOException

fenced

default void fenced(long position)
             throws IOException

Called after a fence operation has been received and processed. All replication processing and checkpoints are suspended until this method returns.

Parameters:

position - log position immediately after the fence operation

Throws:

IOException

notifyStore

default void notifyStore(Index index,
                         byte[] key,
                         byte[] value)

Notification to replica when an entry is stored into an index. All notifications are uncommitted, and so loading with an appropriate lock mode is required for confirmation. The current thread is free to perform any blocking operations — it will not suspend replication processing unless all replication threads are consumed.

Parameters:

index - non-null index reference

key - non-null key; contents must not be modified

value - null if entry is deleted; contents can be modified

notifyRename

default void notifyRename(Index index,
                          byte[] oldName,
                          byte[] newName)

Notification to replica after an index is renamed. The current thread is free to perform any blocking operations — it will not suspend replication processing unless all replication threads are consumed.

Parameters:

index - non-null index reference

oldName - non-null old index name

newName - non-null new index name

notifyDrop

default void notifyDrop(Index index)

Notification to replica after an index is dropped. The current thread is free to perform any blocking operations — it will not suspend replication processing unless all replication threads are consumed.

Parameters:

index - non-null closed and dropped index reference