com.couchbase.client.dcp

Class Client.Builder

java.lang.Object

com.couchbase.client.dcp.Client.Builder

Enclosing class:

Client

public static class Client.Builder
extends Object

Builder object to customize the Client creation.

Constructor Summary

Constructors

Constructor and Description
Builder()

Method Summary

Modifier and Type	Method and Description
Client.Builder	authenticator(Authenticator authenticator)
Client.Builder	bootstrapTimeout(Duration bootstrapTimeout) Time to wait for first configuration during bootstrap.
Client.Builder	bucket(String bucket) The name of the bucket to use.
Client.Builder	bufferAckWatermark(int watermark) The buffer acknowledge watermark in percent.
Client	build() Create the client instance ready to use.
Client.Builder	collectionIds(Collection<Long> collectionIds) Configures the client to stream only from the collections identified by the given IDs.
Client.Builder	collectionIds(long... collectionIds) Configures the client to stream only from the collections identified by the given IDs.
Client.Builder	collectionNames(Collection<String> qualifiedCollectionNames)
Client.Builder	collectionNames(String... qualifiedCollectionNames)
Client.Builder	collectionsAware(boolean enable) Controls whether the client operates in collections-aware mode (defaults to false).
Client.Builder	compression(CompressionMode compressionMode) Sets the compression mode for message values sent by Couchbase Server.
Client.Builder	configRefreshInterval(Duration configRefreshInterval) When connecting to versions of Couchbase Server older than 5.5, the DCP client polls the server for cluster topology config changes at the specified interval.
Client.Builder	connectionNameGenerator(ConnectionNameGenerator connectionNameGenerator) If specific names for DCP connections should be generated, a custom one can be provided.
Client.Builder	connectionString(String connectionString) Connection string to bootstrap with.
Client.Builder	controlParam(DcpControl.Names name, Object value) Set all kinds of DCP control params - check their description for more information.
Client.Builder	credentials(String username, String password)
Client.Builder	credentialsProvider(CredentialsProvider credentialsProvider)
Client.Builder	dcpChannelsReconnectDelay(Delay ignored) Deprecated. Doesn't do anything.
Client.Builder	dcpChannelsReconnectMaxAttempts(int dcpChannelsReconnectMaxAttempts) The maximum number of reconnect attempts for DCP channels
Client.Builder	eventBus(EventBus eventBus) Sets the event bus to an alternative implementation.
Client.Builder	eventLoopGroup(io.netty.channel.EventLoopGroup eventLoopGroup) Sets a custom event loop group.
Client.Builder	flowControl(int bufferSizeInBytes) Enables flow control with the specified buffer size (in bytes) and a reasonable default buffer ACK threshold.
Client.Builder	hostnames(List<String> addresses) Deprecated. use seedNodes(Collection) instead.
Client.Builder	hostnames(String... addresses) Deprecated. use seedNodes(String...) instead.
Client.Builder	meterRegistry(io.micrometer.core.instrument.MeterRegistry meterRegistry) Specifies the registry the client should use when tracking metrics.
Client.Builder	mitigateRollbacks(long persistencePollingInterval, TimeUnit unit) Enables rollback mitigation with the specified persistence polling interval.
Client.Builder	networkResolution(NetworkResolution nr) Network selection strategy for connecting to clusters whose nodes have alternate hostnames.
Client.Builder	noValue(boolean noValue) If the argument is true, configures the client to receive only document keys and metadata (no contents).
Client.Builder	poolBuffers(boolean pool) If buffer pooling should be enabled (yes by default).
Client.Builder	scopeId(long scopeId) Configures the client to stream only from the scope identified by the given ID.
Client.Builder	scopeName(String scopeName) Configures the client to stream only from the scope identified by the given ID.
Client.Builder	securityConfig(SecurityConfig.Builder securityConfigBuilder) Sets the TLS configutation options (from a builder, for convenience)
Client.Builder	securityConfig(SecurityConfig securityConfig) Sets the TLS configutation options
Client.Builder	seedNodes(Collection<String> addresses) Sets the addresses of the Couchbase Server nodes to bootstrap against.
Client.Builder	seedNodes(String... addresses) Sets the addresses of the Couchbase Server nodes to bootstrap against.
Client.Builder	socketConnectTimeout(long socketConnectTimeout) Sets a custom socket connect timeout.
Client.Builder	userAgent(String productName, String productVersion, String... comments) Sets the product information to include in the DCP client's User Agent string.
Client.Builder	xattrs(boolean xattrs) If the argument is true, configures the client to receive extended attributes (XATTRS).

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Builder

public Builder()

Method Detail

noValue

public Client.Builder noValue(boolean noValue)

If the argument is true, configures the client to receive only document keys and metadata (no contents).

Defaults to false.

Returns:

this Client.Builder for nice chainability.

xattrs

public Client.Builder xattrs(boolean xattrs)

If the argument is true, configures the client to receive extended attributes (XATTRS).

Defaults to false.

If set to true, users of the low-level API may call MessageUtil.getContentAndXattrs(ByteBuf) to parse the content and XATTRs of mutation requests. Users of the high-level API may view XATTRs by calling DocumentChange.getXattrs().

Returns:

this Client.Builder for nice chainability.

bufferAckWatermark

public Client.Builder bufferAckWatermark(int watermark)

The buffer acknowledge watermark in percent.

Parameters:

watermark - between 0 and 100, needs to be > 0 if flow control is enabled.

Returns:

this Client.Builder for nice chainability.

seedNodes

public Client.Builder seedNodes(Collection<String> addresses)

Sets the addresses of the Couchbase Server nodes to bootstrap against.

If a port is specified, it must be the KV service port.

The port may be omitted if Couchbase is listening on the standard KV ports (11210 and 11207 for insecure and TLS connections, respectively).

Parameters:

addresses - seed nodes.

Returns:

this Client.Builder for nice chainability.

seedNodes

public Client.Builder seedNodes(String... addresses)

Sets the addresses of the Couchbase Server nodes to bootstrap against.

If a port is specified, it must be the KV service port.

The port may be omitted if Couchbase is listening on the standard KV ports (11210 and 11207 for insecure and TLS connections, respectively).

Parameters:

addresses - seed nodes.

Returns:

this Client.Builder for nice chainability.

hostnames

@Deprecated
public Client.Builder hostnames(List<String> addresses)

Deprecated. use seedNodes(Collection) instead.

hostnames

@Deprecated
public Client.Builder hostnames(String... addresses)

Deprecated. use seedNodes(String...) instead.

connectionString

public Client.Builder connectionString(String connectionString)

Connection string to bootstrap with.

Note: it overrides list of addresses defined by seedNodes(Collection).

Connection string specification defined in SDK-RFC-11: https://github.com/couchbaselabs/sdk-rfcs/blob/master/rfc/0011-connection-string.md

Parameters:

connectionString - seed nodes.

Returns:

this Client.Builder for nice chainability.

networkResolution

public Client.Builder networkResolution(NetworkResolution nr)

Network selection strategy for connecting to clusters whose nodes have alternate hostnames. This usually only matters if Couchbase is running in a containerized environment and you're connecting from outside that environment.

Defaults to NetworkResolution.AUTO which attempts to infer the correct network name by comparing the hostnames reported by Couchbase against the hostnames used to connect to the cluster.

eventLoopGroup

public Client.Builder eventLoopGroup(io.netty.channel.EventLoopGroup eventLoopGroup)

Sets a custom event loop group.

If more than one client is initialized and runs at the same time, you may see better performance if you create a single event loop group for the clients to share.

Parameters:

eventLoopGroup - the group that should be used.

Returns:

this Client.Builder for nice chainability.

bucket

public Client.Builder bucket(String bucket)

The name of the bucket to use.

Parameters:

bucket - name of the bucket

Returns:

this Client.Builder for nice chainability.

collectionsAware

public Client.Builder collectionsAware(boolean enable)

Controls whether the client operates in collections-aware mode (defaults to false).

A client that is not collections-aware only receives events from the default collection.

A collections-aware client receives events from all collections (or the subset specified by the collections/scope filter, configured separately). In this mode, users of the low-level API are responsible for handling "DCP System Event" and "DCP Seqno Advanced" events in their ControlEventHandler. Users of the high-level API should implement DatabaseChangeListener.onSeqnoAdvanced(com.couchbase.client.dcp.highlevel.SeqnoAdvanced).

It is fine to enable collections awareness even when connecting to a server that does not support collections, as long as no collections/scope filter is configured.

Returns:

this Client.Builder for nice chainability.

See Also:

scopeId(long), scopeName(String), collectionIds(Collection), collectionNames(Collection)

collectionNames

public Client.Builder collectionNames(Collection<String> qualifiedCollectionNames)

collectionNames

public Client.Builder collectionNames(String... qualifiedCollectionNames)

collectionIds

public Client.Builder collectionIds(Collection<Long> collectionIds)

Configures the client to stream only from the collections identified by the given IDs.

Parameters:

collectionIds - IDs of the collections to stream.

Returns:

this Client.Builder for nice chainability.

collectionIds

public Client.Builder collectionIds(long... collectionIds)

Configures the client to stream only from the collections identified by the given IDs.

Parameters:

collectionIds - IDs of the collections to stream.

Returns:

this Client.Builder for nice chainability.

scopeName

public Client.Builder scopeName(String scopeName)

Configures the client to stream only from the scope identified by the given ID.

Parameters:

scopeName - name of the scope to stream (may be null, in which case this method has no effect)

Returns:

this Client.Builder for nice chainability.

scopeId

public Client.Builder scopeId(long scopeId)

Configures the client to stream only from the scope identified by the given ID.

Parameters:

scopeId - IDs of the scope to stream.

Returns:

this Client.Builder for nice chainability.

credentials

public Client.Builder credentials(String username,
                                  String password)

credentialsProvider

public Client.Builder credentialsProvider(CredentialsProvider credentialsProvider)

authenticator

public Client.Builder authenticator(Authenticator authenticator)

userAgent

public Client.Builder userAgent(String productName,
                                String productVersion,
                                String... comments)

Sets the product information to include in the DCP client's User Agent string. The User Agent will be part of the DCP connection name, which appears in the Couchbase Server logs for log entries associated with this client.

The product name may consist of alpha-numeric ASCII characters, plus the following special characters: !#$%&'*+-.^_`|~

Invalid characters will be converted to underscores.

Comments may optionally convey additional context, such as the name of the bucket being streamed or some other information about the client.

Returns:

this Client.Builder for nice chainability.

connectionNameGenerator

public Client.Builder connectionNameGenerator(ConnectionNameGenerator connectionNameGenerator)

If specific names for DCP connections should be generated, a custom one can be provided.

Parameters:

connectionNameGenerator - custom generator.

Returns:

this Client.Builder for nice chainability.

controlParam

public Client.Builder controlParam(DcpControl.Names name,
                                   Object value)

Set all kinds of DCP control params - check their description for more information.

Parameters:

name - the name of the param

value - the value of the param

Returns:

this Client.Builder for nice chainability.

compression

public Client.Builder compression(CompressionMode compressionMode)

Sets the compression mode for message values sent by Couchbase Server. If not specified, defaults to CompressionMode.ENABLED.

poolBuffers

public Client.Builder poolBuffers(boolean pool)

If buffer pooling should be enabled (yes by default).

Parameters:

pool - enable or disable buffer pooling.

Returns:

this Client.Builder for nice chainability.

socketConnectTimeout

public Client.Builder socketConnectTimeout(long socketConnectTimeout)

Sets a custom socket connect timeout.

Parameters:

socketConnectTimeout - the socket connect timeout in milliseconds.

bootstrapTimeout

public Client.Builder bootstrapTimeout(Duration bootstrapTimeout)

Time to wait for first configuration during bootstrap.

configRefreshInterval

public Client.Builder configRefreshInterval(Duration configRefreshInterval)

When connecting to versions of Couchbase Server older than 5.5, the DCP client polls the server for cluster topology config changes at the specified interval.

When connecting to modern versions of Couchbase Server, calling this method has no effect.

Parameters:

configRefreshInterval - time between config refresh requests. Must be between 1 second and 2 minutes (inclusive).

dcpChannelsReconnectMaxAttempts

public Client.Builder dcpChannelsReconnectMaxAttempts(int dcpChannelsReconnectMaxAttempts)

The maximum number of reconnect attempts for DCP channels

Parameters:

dcpChannelsReconnectMaxAttempts -

dcpChannelsReconnectDelay

@Deprecated
public Client.Builder dcpChannelsReconnectDelay(Delay ignored)

Deprecated. Doesn't do anything.

Delay between retry attempts for DCP channels

eventBus

public Client.Builder eventBus(EventBus eventBus)

Sets the event bus to an alternative implementation.

This setting should only be tweaked in advanced cases.

securityConfig

public Client.Builder securityConfig(SecurityConfig securityConfig)

Sets the TLS configutation options

securityConfig

public Client.Builder securityConfig(SecurityConfig.Builder securityConfigBuilder)

Sets the TLS configutation options (from a builder, for convenience)

mitigateRollbacks

public Client.Builder mitigateRollbacks(long persistencePollingInterval,
                                        TimeUnit unit)

Enables rollback mitigation with the specified persistence polling interval. Must be accompanied by a call to flowControl(int).

When rollback mitigation is enabled, stream events will not be propagated to the DataEventHandler or ControlEventHandler until the event has been persisted to disk on the active and all replica nodes.

To observe persistence, the client will poll each node at the given interval.

If a partition instance becomes unavailable, event propagation will pause until the cluster stabilizes. Because recovery may take a long time, flow control is required so the client need not buffer an indeterminately large number of events.

flowControl

public Client.Builder flowControl(int bufferSizeInBytes)

Enables flow control with the specified buffer size (in bytes) and a reasonable default buffer ACK threshold. To specify a custom threshold, chain this method with bufferAckWatermark(int).

Parameters:

bufferSizeInBytes - The amount of data the server will send before requiring an ACK

See Also:

ChannelFlowController

meterRegistry

public Client.Builder meterRegistry(io.micrometer.core.instrument.MeterRegistry meterRegistry)

Specifies the registry the client should use when tracking metrics. If not called, defaults to Micrometer's global registry.

build

public Client build()

Create the client instance ready to use.

Returns:

the built client instance.