CBLReplicator

@interface CBLReplicator : NSObject

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-short or continuous. The replicator runs asynchronously, so observe the status property to be notified of progress.

  • The replicator’s configuration. The returned configuration object is readonly; an NSInternalInconsistencyException exception will be thrown if the configuration object is modified.

    Declaration

    Objective-C

    @property (nonatomic, readonly) CBLReplicatorConfiguration *_Nonnull config;

  • The replicator’s current status: its activity level and progress. Observable.

    Declaration

    Objective-C

    @property (readonly) CBLReplicatorStatus *_Nonnull status;

  • The SSL/TLS certificate received when connecting to the server. The application code takes responsibility for releasing the certificate object when the application code finishes using the certificate.

    Declaration

    Objective-C

    @property (copy, readonly, nullable) SecCertificateRef serverCertificate;

  • Initializes a replicator with the given configuration.

    Declaration

    Objective-C

    - (nonnull instancetype)initWithConfig:
    (nonnull CBLReplicatorConfiguration *)config;

  • Unavailable

    Not available

    Declaration

    Objective-C

    - (nonnull instancetype)init;

  • Starts the replicator. This method returns immediately; the replicator runs asynchronously and will report its progress through the replicator change notification.

    Note

    This method MUST NOT be called within database’s inBatch() block, as it will enter deadlock.

    Declaration

    Objective-C

    - (void)start;

  • Starts the replicator with an option to reset the local checkpoint of the replicator. When the local checkpoint is reset, the replicator will sync all changes since the beginning of time from the remote database. This method returns immediately; the replicator runs asynchronously and will report its progress through the replicator change notification.

    Declaration

    Objective-C

    - (void)startWithReset:(BOOL)reset;

    Parameters

    reset

    Resets the local checkpoint before starting the replicator.

  • Stops a running replicator. This method returns immediately; when the replicator actually stops, the replicator will change its status’s activity level to kCBLStopped and the replicator change notification will be notified accordingly.

    Declaration

    Objective-C

    - (void)stop;

  • Adds a replicator change listener. Changes will be posted on the main queue.

    Declaration

    Objective-C

    - (nonnull id<CBLListenerToken>)addChangeListener:
    (nonnull void (^)(CBLReplicatorChange *_Nonnull))listener;

    Parameters

    listener

    The listener to post the changes.

    Return Value

    An opaque listener token object for removing the listener.

  • Adds a replicator change listener with the dispatch queue on which changes will be posted. If the dispatch queue is not specified, the changes will be posted on the main queue.

    Declaration

    Objective-C

    - (nonnull id<CBLListenerToken>)
    addChangeListenerWithQueue:(nullable dispatch_queue_t)queue
                      listener:(nonnull void (^)(CBLReplicatorChange *_Nonnull))
                                   listener;

    Parameters

    queue

    The dispatch queue.
    listener

    The listener to post changes.

    Return Value

    An opaque listener token object for removing the listener.

  • Adds a replication event listener. The replication event will be posted on the main queue.

    According to performance optimization in the replicator, the document replication listeners need to be added before starting the replicator. If the listeners are added after the replicator is started, the replicator needs to be stopped and restarted again to ensure that the listeners will get the document replication events.

    Declaration

    Objective-C

    - (nonnull id<CBLListenerToken>)addDocumentReplicationListener:
    (nonnull void (^)(CBLDocumentReplication *_Nonnull))listener;

    Parameters

    listener

    The listener to post replication events.

    Return Value

    An opaque listener token object for removing the listener.

  • Adds a replication event listener with the dispatch queue on which replication events will be posted. If the dispatch queue is not specified, the replication events will be posted on the main queue.

    According to performance optimization in the replicator, the document replication listeners need to be added before starting the replicator. If the listeners are added after the replicator is started, the replicator needs to be stopped and restarted again to ensure that the listeners will get the document replication events.

    Declaration

    Objective-C

    - (nonnull id<CBLListenerToken>)
    addDocumentReplicationListenerWithQueue:(nullable dispatch_queue_t)queue
                                   listener:
                                       (nonnull void (^)(
                                           CBLDocumentReplication *_Nonnull))
                                           listener;

    Parameters

    queue

    The dispatch queue.
    listener

    The listener to post replication events.

    Return Value

    An opaque listener token object for removing the listener.

  • Removes a change listener with the given listener token.

    Declaration

    Objective-C

    - (void)removeChangeListenerWithToken:(nonnull id<CBLListenerToken>)token;

    Parameters

    token

    The listener token;

  • Deprecated

    Use [replicator pendingDocumentIDsForCollection:error:] instead.

    Get pending document ids for default collection. If the default collection is not part of the replication, an Illegal State Exception will be thrown.

    Declaration

    Objective-C

    - (nullable NSSet<NSString *> *)pendingDocumentIDs:
    (NSError *_Nullable *_Nullable)error;

    Parameters

    error

    On return, the error if any.

    Return Value

    A set of document Ids, each of which has one or more pending revisions. If error, nil.

  • Get pending document ids for the given collection. If the given collection is not part of the replication, an Illegal State Exception will be thrown.

    Declaration

    Objective-C

    - (nullable NSSet<NSString *> *)
    pendingDocumentIDsForCollection:(nonnull CBLCollection *)collection
                              error:(NSError *_Nullable *_Nullable)error;

    Parameters

    collection

    The given collection.
    error

    On return, the error if any.

    Return Value

    A set of document Ids, each of which has one or more pending revisions. If error, nil.

  • Deprecated

    Use [replicator isDocumentPending:collection:error:] instead.

    Check whether the document in the default collection is pending to push or not. If the default collection is not part of the replicator, an Illegal State Exception will be thrown.

    Declaration

    Objective-C

    - (BOOL)isDocumentPending:(nonnull NSString *)documentID
                    error:(NSError *_Nullable *_Nullable)error;

    Parameters

    documentID

    The ID of the document to check
    error

    On return, the error if any.

    Return Value

    true if the document has one or more revisions pending, false otherwise.

  • Check whether the document in the given collection is pending to push or not. If the given collection is not part of the replicator, an Illegal State Exception will be thrown.

    Declaration

    Objective-C

    - (BOOL)isDocumentPending:(nonnull NSString *)documentID
               collection:(nonnull CBLCollection *)collection
                    error:(NSError *_Nullable *_Nullable)error;

    Parameters

    documentID

    The ID of the document to check
    collection

    The collection which document belongs
    error

    On return, the error if any.

    Return Value

    true if the document has one or more revisions pending, false otherwise.