Package com.couchbase.lite

Class AbstractReplicator

java.lang.Object
com.couchbase.lite.internal.replicator.BaseReplicator
com.couchbase.lite.AbstractReplicator
All Implemented Interfaces:
com.couchbase.lite.internal.listener.Listenable<ReplicatorChange,ReplicatorChangeListener>, AutoCloseable
Direct Known Subclasses:
Replicator
public abstract class AbstractReplicator extends com.couchbase.lite.internal.replicator.BaseReplicator implements com.couchbase.lite.internal.listener.Listenable<ReplicatorChange,ReplicatorChangeListener>
A replicator for replicating document changes between a local database and a target database. The replicator can be bidirectional or either push or pull. The replicator can also be one-shot or continuous. The replicator runs asynchronously, so observe the status to be notified of progress.

  • Constructor Details

    • AbstractReplicator

      protected AbstractReplicator(@NonNull ReplicatorConfiguration config)
      Initializes a replicator with the given configuration.
      Parameters:
      config - replicator configuration

  • Method Details

    • start

      public void start()
      Start the replicator.

    • start

      public void start(boolean resetCheckpoint)
      Start the replicator.

      This method does not wait for the replicator to start. The replicator runs asynchronously and reports its progress through replicator change notifications.

      Note: Replicators cannot be started from within a Database.inBatch() block.

    • stop

      public void stop()
      Stop a running replicator. This method does not wait for the replicator to stop. When the replicator actually stops, it will a broadcast a new state, STOPPED, to change listeners.

    • getConfig

      @NonNull public ReplicatorConfiguration getConfig()
      The replicator's configuration.
      Returns:
      this replicator's configuration

    • getStatus

      @NonNull public ReplicatorStatus getStatus()
      The replicator's current status: its activity level and progress.
      Returns:
      this replicator's status

    • getServerCertificates

      @Nullable public List<Certificate> getServerCertificates()
      The server certificates received from the server during the TLS handshake.
      Returns:
      this replicator's server certificates.

    • getPendingDocumentIds

      @Deprecated @NonNull public Set<String> getPendingDocumentIds() throws CouchbaseLiteException
      Deprecated.
      Use getPendingDocumentIds(Collection)
      Get a best effort list of documents in the default collection, that are still pending replication.
      Returns:
      a set of ids for documents in the default collection still awaiting replication.
      Throws:
      CouchbaseLiteException

    • getPendingDocumentIds

      @NonNull public Set<String> getPendingDocumentIds(@NonNull Collection collection) throws CouchbaseLiteException
      Get a best effort list of documents in the passed collection that are still pending replication.
      Returns:
      a set of ids for documents in the passed collection still awaiting replication.
      Throws:
      CouchbaseLiteException

    • isDocumentPending

      @Deprecated public boolean isDocumentPending(@NonNull String docId) throws CouchbaseLiteException
      Deprecated.
      Use isDocumentPending(String, Collection)
      Best effort check to see if the document whose ID is passed is still pending replication.
      Parameters:
      docId - Document id
      Returns:
      true if the document is pending
      Throws:
      CouchbaseLiteException

    • isDocumentPending

      public boolean isDocumentPending(@NonNull String docId, @NonNull Collection collection) throws CouchbaseLiteException
      Best effort check to see if the document whose ID is passed is still pending replication.
      Parameters:
      docId - Document id
      Returns:
      true if the document is pending
      Throws:
      CouchbaseLiteException

    • addChangeListener

      @NonNull public ListenerToken addChangeListener(@NonNull ReplicatorChangeListener listener)
      Adds a change listener for the changes in the replication status and progress.

      The changes will be delivered on the UI thread for the Android platform On other Java platforms, the callback will occur on the single threaded default executor.

      When developing a Java Desktop application using Swing or JavaFX that needs to update the UI after receiving the changes, make sure to schedule the UI update on the UI thread by using SwingUtilities.invokeLater(Runnable) or Platform.runLater(Runnable) respectively.

      Specified by:
      addChangeListener in interface com.couchbase.lite.internal.listener.Listenable<ReplicatorChange,ReplicatorChangeListener>
      Parameters:
      listener - callback

    • addChangeListener

      @NonNull public ListenerToken addChangeListener(@Nullable Executor executor, @NonNull ReplicatorChangeListener listener)
      Adds a change listener for the changes in the replication status and progress with an executor on which the changes will be posted to the listener. If the executor is not specified, the changes will be delivered on the UI thread on Android platform and on the single threaded default executor on other Java platforms
      Specified by:
      addChangeListener in interface com.couchbase.lite.internal.listener.Listenable<ReplicatorChange,ReplicatorChangeListener>
      Parameters:
      executor - executor on which events will be delivered
      listener - callback

    • addDocumentReplicationListener

      @NonNull public ListenerToken addDocumentReplicationListener(@NonNull DocumentReplicationListener listener)
      Adds a listener for receiving the replication status of the specified document. The status will be delivered on the UI thread for the Android platform and on the single threaded default executor on other platforms.

      When developing a Java Desktop application using Swing or JavaFX that needs to update the UI after receiving the status, make sure to schedule the UI update on the UI thread by using SwingUtilities.invokeLater(Runnable) or Platform.runLater(Runnable) respectively.

      Parameters:
      listener - callback
      Returns:
      A ListenerToken that can be used to remove the handler in the future.

    • addDocumentReplicationListener

      @NonNull public ListenerToken addDocumentReplicationListener(@Nullable Executor executor, @NonNull DocumentReplicationListener listener)
      Adds a listener for receiving the replication status of the specified document with an executor on which the status will be posted to the listener. If the executor is not specified, the status will be delivered on the UI thread for the Android platform and on an arbitrary thread for the Java platform.
      Parameters:
      executor - executor on which events will be delivered
      listener - callback

    • removeChangeListener

      @Deprecated public void removeChangeListener(@NonNull ListenerToken token)
      Deprecated.
      use ListenerToken.remove
      Remove the given ReplicatorChangeListener or DocumentReplicationListener from the this replicator.
      Parameters:
      token - returned by a previous call to addChangeListener or addDocumentListener.

    • close

      public void close()
      Immediatly close the replicator and free its resources. We recommend the use of this method on Replicators that are in the STOPPED state. If the replicator is not stopped, this method will make a best effort attempt to stop it but will not wait to confirm that it was stopped cleanly. Any attempt to restart a closed replicator will result in an CouchbaseLiteError. This includes calls to getPendingDocIds and isDocPending.
      Specified by:
      close in interface AutoCloseable

    • isClosed

      public boolean isClosed()
      Determine whether this replicator has been closed.
      Returns:
      true iff the replicator is closed.

    • toString

      @NonNull public String toString()
      Overrides:
      toString in class Object

    • createReplicatorForTarget

      @NonNull protected abstract com.couchbase.lite.internal.core.C4Replicator createReplicatorForTarget(@NonNull Endpoint target) throws LiteCoreException
      Throws:
      LiteCoreException

    • handleOffline

      protected abstract void handleOffline(@NonNull ReplicatorActivityLevel prevState, boolean nowOnline)

    • getLocalC4Replicator

      @NonNull protected final com.couchbase.lite.internal.core.C4Replicator getLocalC4Replicator(@NonNull Database targetDb) throws LiteCoreException
      Create and return a c4Replicator targeting the passed Database
      Parameters:
      targetDb - a local database for the replication target
      Returns:
      the c4Replicator
      Throws:
      LiteCoreException - on failure to create the replicator

    • getRemoteC4Replicator

      @NonNull protected final com.couchbase.lite.internal.core.C4Replicator getRemoteC4Replicator(@NonNull URI remoteUri) throws LiteCoreException
      Create and return a c4Replicator targeting the passed URI
      Parameters:
      remoteUri - a URI for the replication target
      Returns:
      the c4Replicator
      Throws:
      LiteCoreException - on failure to create the replicator

    • getMessageC4Replicator

      @NonNull protected final com.couchbase.lite.internal.core.C4Replicator getMessageC4Replicator(@NonNull com.couchbase.lite.internal.sockets.MessageFraming framing) throws LiteCoreException
      Create and return a c4Replicator. The socket factory is responsible for setting up the target
      Parameters:
      framing - the message framing
      Returns:
      the c4Replicator
      Throws:
      LiteCoreException - on failure to create the replicator