Package com.couchbase.client.dcp

Class Client

java.lang.Object
com.couchbase.client.dcp.Client
All Implemented Interfaces:
Closeable, AutoCloseable
public class Client extends Object implements Closeable
This Client provides the main API to configure and use the DCP client.

Create a new instance using the builder returned by the builder() method.

  • Method Details

    • configure

      @Deprecated public static Client.Builder configure()
      Deprecated.
      in favor of builder()
      Allows to configure the Client before bootstrap through a Client.Builder.
      Returns:
      the builder to configure the client.

    • builder

      public static Client.Builder builder()

    • getSeqnos

      public reactor.core.publisher.Flux<PartitionAndSeqno> getSeqnos()
      Get the current sequence numbers from all partitions.
      Returns:
      an Flux of partition and sequence number.

    • sessionState

      public SessionState sessionState()
      Returns the current SessionState, useful for persistence and inspection.
      Returns:
      the current session state.

    • listener

      public void listener(DatabaseChangeListener listener, FlowControlMode flowControlMode)
      Registers an event listener that will be invoked in a dedicated thread. The listener's methods may safely block without disrupting the Netty I/O layer.

    • nonBlockingListener

      public void nonBlockingListener(DatabaseChangeListener listener)
      Registers an event listener to be invoked in the Netty I/O event loop thread. The listener's methods should return quickly and MUST NOT block.

      Non-blocking listeners always use FlowControlMode.MANUAL.

    • controlEventHandler

      public void controlEventHandler(ControlEventHandler controlEventHandler)
      Stores a ControlEventHandler to be called when control events happen.

      All events (passed as ByteBufs) that the callback receives need to be handled and at least released (by using ReferenceCounted.release(), otherwise they will leak.

      The following messages can happen and should be handled depending on the needs of the client:

      - RollbackMessage: If during a connect phase the server responds with rollback information, this event is forwarded to the callback. Does not need to be acknowledged.

      - DcpSnapshotMarkerRequest: Server transmits data in batches called snapshots before sending anything, it send marker message, which contains start and end sequence numbers of the data in it. Need to be acknowledged.

      Keep in mind that the callback is executed on the IO thread (netty's thread pool for the event loops) so further synchronization is needed if the data needs to be used on a different thread in a thread safe manner.

      Parameters:
      controlEventHandler - the event handler to use.

    • systemEventHandler

      public void systemEventHandler(SystemEventHandler systemEventHandler)
      Stores a SystemEventHandler to be called when control events happen.

    • dataEventHandler

      public void dataEventHandler(DataEventHandler dataEventHandler)
      Stores a DataEventHandler to be called when data events happen.

      All events (passed as ByteBufs) that the callback receives need to be handled and at least released (by using ReferenceCounted.release(), otherwise they will leak.

      The following messages can happen and should be handled depending on the needs of the client:

      - DcpMutationMessage: A mutation has occurred. Needs to be acknowledged. - DcpDeletionMessage: A deletion has occurred. Needs to be acknowledged. - DcpExpirationMessage: An expiration has occurred. Note that current server versions (as of 4.5.0) are not emitting this event, but in any case you should at least release it to be forwards compatible. Needs to be acknowledged.

      Keep in mind that the callback is executed on the IO thread (netty's thread pool for the event loops) so further synchronization is needed if the data needs to be used on a different thread in a thread safe manner.

      Parameters:
      dataEventHandler - the event handler to use.

    • connect

      public reactor.core.publisher.Mono<Void> connect()
      Initializes the underlying connections (not the streams) and sets up everything as needed.
      Returns:
      a Mono signaling that the connect phase has been completed or failed.

    • disconnect

      public reactor.core.publisher.Mono<Void> disconnect()
      Disconnect the Client and shut down all its owned resources.

      If custom state is used (like a shared EventLoopGroup), then they must be closed and managed separately after this disconnect process has finished.

      Returns:
      a Mono signaling that the disconnect phase has been completed or failed.

    • close

      public void close()
      Disconnects the client. This blocking alternative to disconnect() exists to support try-with-resources.
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable

    • resumeStreaming

      public reactor.core.publisher.Mono<Void> resumeStreaming(Map<Integer,StreamOffset> vbucketToOffset)
      Parameters:
      vbucketToOffset - a Map where each key is a vbucket to stream, and the value is the offset from which to resume streaming.
      Returns:
      a Mono that completes when the streams have been successfully opened.

    • startStreaming

      @Deprecated public reactor.core.publisher.Mono<Void> startStreaming(Short... vbids)
      Deprecated.
      Please use startStreaming(Collection) instead.

    • startStreaming

      public reactor.core.publisher.Mono<Void> startStreaming()
      Start streaming for all partitions.
      Returns:
      a Mono indicating that streaming has started or failed.

    • startStreaming

      public reactor.core.publisher.Mono<Void> startStreaming(Collection<Integer> vbids)
      Start DCP streams based on the initialized state for the given partition IDs (vbids).

      If no ids are provided, all initialized partitions will be started.

      Parameters:
      vbids - the partition ids (0-indexed) to start streaming for.
      Returns:
      a Mono indicating that streaming has started or failed.

    • stopStreaming

      @Deprecated public reactor.core.publisher.Mono<Void> stopStreaming(Short... vbids)
      Deprecated.
      Please use stopStreaming(Collection) instead.

    • stopStreaming

      public reactor.core.publisher.Mono<Void> stopStreaming(Collection<Integer> vbids)
      Stop DCP streams for the given partition IDs (vbids).

      If no ids are provided, all partitions will be stopped. Note that you can also use this to "pause" streams if startStreaming(java.lang.Short...) is called later - since the session state is persisted and streaming will resume from the current position.

      Parameters:
      vbids - the partition ids (0-indexed) to stop streaming for.
      Returns:
      a Mono indicating that streaming has stopped or failed.

    • failoverLogs

      @Deprecated public reactor.core.publisher.Flux<com.couchbase.client.core.deps.io.netty.buffer.ByteBuf> failoverLogs(Short... vbids)
      Deprecated.
      Please use failoverLogs(Collection) instead.

    • failoverLogs

      public reactor.core.publisher.Flux<com.couchbase.client.core.deps.io.netty.buffer.ByteBuf> failoverLogs(Collection<Integer> vbids)
      Helper method to return the failover logs for the given partitions (vbids).

      If the list is empty, the failover logs for all partitions will be returned. Note that the returned ByteBufs can be analyzed using the DcpFailoverLogResponse flyweight.

      Parameters:
      vbids - the partitions to return the failover logs from.
      Returns:
      an Flux containing all failover logs.

    • failoverLog

      public reactor.core.publisher.Mono<com.couchbase.client.core.deps.io.netty.buffer.ByteBuf> failoverLog(int vbid)

    • rollbackAndRestartStream

      public reactor.core.publisher.Mono<Void> rollbackAndRestartStream(int partition, long seqno)
      Helper method to rollback the partition state and stop/restart the stream.

      The stream is stopped (if not already done). Then:

      The rollback seqno state is applied. Note that this will also remove all the failover logs for the partition that are higher than the given seqno, since the server told us we are ahead of it.

      Finally, the stream is restarted again.

      Parameters:
      partition - the partition id
      seqno - the sequence number to rollback to

    • numPartitions

      public int numPartitions()
      Returns the number of partitions on the remote cluster.

      Note that you must be connected, since the information is loaded from the server configuration. On all OS'es other than OSX it will be 1024, on OSX it is 64. Treat this as an opaque value anyways.

      Returns:
      the number of partitions (vbuckets).

    • streamIsOpen

      public boolean streamIsOpen(int vbid)
      Returns true if the stream for the given partition id is currently open.
      Parameters:
      vbid - the partition id.
      Returns:
      true if it is open, false otherwise.

    • initializeState

      public reactor.core.publisher.Mono<Void> initializeState(StreamFrom from, StreamTo to)
      Initialize the SessionState based on arbitrary time points.

      The following combinations are supported and make sense:

      - StreamFrom.BEGINNING to StreamTo.NOW - StreamFrom.BEGINNING to StreamTo.INFINITY - StreamFrom.NOW to StreamTo.INFINITY

      If you already have state captured and you want to resume from this position, use recoverState(StateFormat, byte[]) or recoverOrInitializeState(StateFormat, byte[], StreamFrom, StreamTo) instead.

      Parameters:
      from - where to start streaming from.
      to - when to stop streaming.
      Returns:
      A Mono indicating the success or failure of the state init.

    • recoverState

      @Deprecated public reactor.core.publisher.Mono<Void> recoverState(StateFormat format, byte[] persistedState)
      Deprecated.
      This method of recovering state does not account for whether an event received by the DCP client was actually processed by the user's application. This can cause the application to resume from the wrong point, and silently ignore some events. Instead, an application should track its own state, and resume using resumeStreaming(Map).
      Initializes the SessionState from a previous snapshot with specific state information.

      If a system needs to be built that withstands outages and needs to resume where left off, this method, combined with the periodic persistence of the SessionState provides resume capabilities. If you need to start fresh, take a look at initializeState(StreamFrom, StreamTo) as well as recoverOrInitializeState(StateFormat, byte[], StreamFrom, StreamTo).

      Parameters:
      format - the format used when persisting.
      persistedState - the opaque byte array representing the persisted state.
      Returns:
      A Mono indicating the success or failure of the state recovery.

    • recoverOrInitializeState

      @Deprecated public reactor.core.publisher.Mono<Void> recoverOrInitializeState(StateFormat format, byte[] persistedState, StreamFrom from, StreamTo to)
      Deprecated.
      This method of recovering state does not account for whether an event received by the DCP client was actually processed by the user's application. This can cause the application to resume from the wrong point, silently skipping some events. Instead, an application should track its own state, and resume using resumeStreaming(Map).
      Recovers or initializes the SessionState.

      This method is a convenience wrapper around initialization and recovery. It combines both methods and checks if the persisted state byte array is null or empty and if so it starts with the params given. If it is not empty it recovers from there. This acknowledges the fact that ideally the state is persisted somewhere but if its not there you want to start at a specific point in time.

      Parameters:
      format - the persistence format used.
      persistedState - the state, may be null or empty.
      from - from where to start streaming if persisted state is null or empty.
      to - to where to stream if persisted state is null or empty.
      Returns:
      A Mono indicating the success or failure of the state recovery or init.