com.cloudant.sync.replication

Interface Replicator

All Known Implementing Classes:

ReplicatorImpl

public interface Replicator

Manages replication between a local Datastore and a remote Cloudant or CouchDB database.

Create instances using the ReplicatorBuilder class.

The replicator is thread safe.

API Status: Public

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	Replicator.State Describes the state of a Replicator at a given moment.

Method Summary

Modifier and Type	Method and Description
EventBus	getEventBus() Returns an EventBus that clients can use to listen for state changes for this replicator.
int	getId()
Replicator.State	getState() Returns the Replicator.State this replicator is in.
void	start() Starts a replication.
void	stop() Stops an in-progress replication.

Method Detail

start

void start()

Starts a replication.

The replication will continue until the replication is caught up with the source database; that is, until there are no current changes to replicate.

start can be called from any thread. It spawns background threads for its work. The methods on the ReplicationListener may be called from the background threads; any work that needs to be on the main thread will need to be explicitly executed on that thread.

start will spawn a manager thread for the replication and immediately return.

A given replicator instance can be reused:

• If you call start when in Replicator.State.PENDING, replication will start.
• In Replicator.State.STARTED, nothing changes.
• In Replicator.State.STOPPING, nothing changes.
• In Replicator.State.ERROR, the replication will restart. It's likely its going to error again, however, depending on whether the error is transient or not.
• In Replicator.State.STOPPED or Replicator.State.COMPLETE, the replication will start a second or further time.

stop

void stop()

Stops an in-progress replication.

Already replicated changes will remain in the datastore database.

stop can be called from any thread. It will initiate a shutdown process and return immediately.

The shutdown process may take time as we need to wait for in-flight network requests to complete before background threads can be safely stopped. However, no modifications to the database will be made after stop is called, including checkpoint related operations.

Consumers should check getState() if they need to know when the replicator has fully stopped. After stop is called, the replicator will be in the Replicator.State.STOPPING state while operations complete and will move to the Replicator.State.STOPPED state when the replicator has fully shutdown.

It is also possible the replicator moves to the Replicator.State.ERROR state if an error happened during the shutdown process.

If the replicator is in the Replicator.State.PENDING state, it will immediately move to the Replicator.State.STOPPED state.

getState

Replicator.State getState()

Returns the Replicator.State this replicator is in.

getState may be called from any thread.

In all states other than Replicator.State.STARTED and Replicator.State.STOPPING, the replicator object is idle with no background threads.

Returns:

the Replicator.State this replicator is in

getEventBus

EventBus getEventBus()

Returns an EventBus that clients can use to listen for state changes for this replicator.

The replicator raises the following events:

• ReplicationErrored if there is an error during replication.
• ReplicationCompleted when the replication is completed, unless there is an error.

Returns:

EventBus object.

getId

int getId()