Package com.mongodb

Class MongoClientSettings.Builder

java.lang.Object

com.mongodb.MongoClientSettings.Builder

Enclosing class:

MongoClientSettings

@NotThreadSafe
public static final class MongoClientSettings.Builder
extends Object

A builder for MongoClientSettings so that MongoClientSettings can be immutable, and to support easier construction through chaining.

Method Summary

Modifier and Type	Method	Description
MongoClientSettings.Builder	addCommandListener(CommandListener commandListener)	Adds the given command listener.
MongoClientSettings.Builder	applicationName(String applicationName)	Sets the logical name of the application using this MongoClient.
MongoClientSettings.Builder	applyConnectionString(ConnectionString connectionString)	Takes the settings from the given ConnectionString and applies them to the builder
MongoClientSettings.Builder	applyToClusterSettings(Block<ClusterSettings.Builder> block)	Applies the ClusterSettings.Builder block and then sets the clusterSettings.
MongoClientSettings.Builder	applyToConnectionPoolSettings(Block<ConnectionPoolSettings.Builder> block)	Applies the ConnectionPoolSettings.Builder block and then sets the connectionPoolSettings.
MongoClientSettings.Builder	applyToLoggerSettings(Block<LoggerSettings.Builder> block)	Applies the LoggerSettings.Builder block and then sets the loggerSettings.
MongoClientSettings.Builder	applyToServerSettings(Block<ServerSettings.Builder> block)	Applies the ServerSettings.Builder block and then sets the serverSettings.
MongoClientSettings.Builder	applyToSocketSettings(Block<SocketSettings.Builder> block)	Applies the SocketSettings.Builder block and then sets the socketSettings.
MongoClientSettings.Builder	applyToSslSettings(Block<SslSettings.Builder> block)	Applies the SslSettings.Builder block and then sets the sslSettings.
MongoClientSettings.Builder	autoEncryptionSettings(AutoEncryptionSettings autoEncryptionSettings)	Sets the auto-encryption settings
MongoClientSettings	build()	Build an instance of MongoClientSettings.
MongoClientSettings.Builder	codecRegistry(CodecRegistry codecRegistry)	Sets the codec registry
MongoClientSettings.Builder	commandListenerList(List<CommandListener> commandListeners)	Sets the command listeners
MongoClientSettings.Builder	compressorList(List<MongoCompressor> compressorList)	Sets the compressors to use for compressing messages to the server.
MongoClientSettings.Builder	contextProvider(ContextProvider contextProvider)	Sets the context provider
MongoClientSettings.Builder	credential(MongoCredential credential)	Sets the credential.
MongoClientSettings.Builder	dnsClient(DnsClient dnsClient)	Sets the DnsClient to use for resolving DNS queries.
MongoClientSettings.Builder	enableOverloadRetargeting(boolean enableOverloadRetargeting)	Sets whether to enable overload retargeting.
MongoClientSettings.Builder	inetAddressResolver(InetAddressResolver inetAddressResolver)	Sets the InetAddressResolver to use for looking up the InetAddress instances for each host.
MongoClientSettings.Builder	maxAdaptiveRetries(Integer maxAdaptiveRetries)	Sets the maximum number of retry attempts when executing a command and encountering an error having the "SystemOverloadedError" and "RetryableError" labels.
MongoClientSettings.Builder	observabilitySettings(ObservabilitySettings observabilitySettings)	Sets the ObservabilitySettings to apply.
MongoClientSettings.Builder	readConcern(ReadConcern readConcern)	Sets the read concern.
MongoClientSettings.Builder	readPreference(ReadPreference readPreference)	Sets the read preference.
MongoClientSettings.Builder	retryReads(boolean retryReads)	Sets whether attempts to execute read commands should be retried if they fail due to a retryable error.
MongoClientSettings.Builder	retryWrites(boolean retryWrites)	Sets whether attempts to execute write commands should be retried if they fail due to a retryable error.
MongoClientSettings.Builder	serverApi(ServerApi serverApi)	Sets the server API to use when sending commands to the server.
MongoClientSettings.Builder	timeout(long timeout, TimeUnit timeUnit)	Sets the time limit for the full execution of an operation.
MongoClientSettings.Builder	transportSettings(TransportSettings transportSettings)	Sets the TransportSettings to apply.
MongoClientSettings.Builder	uuidRepresentation(UuidRepresentation uuidRepresentation)	Sets the UUID representation to use when encoding instances of UUID and when decoding BSON binary values with subtype of 3.
MongoClientSettings.Builder	writeConcern(WriteConcern writeConcern)	Sets the write concern.

Methods inherited from class java.lang.Object

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

Method Details

applyConnectionString

public MongoClientSettings.Builder applyConnectionString(ConnectionString connectionString)

Takes the settings from the given ConnectionString and applies them to the builder

Parameters:

connectionString - the connection string containing details of how to connect to MongoDB

Returns:

this

applyToLoggerSettings

public MongoClientSettings.Builder applyToLoggerSettings(Block<LoggerSettings.Builder> block)

Applies the LoggerSettings.Builder block and then sets the loggerSettings.

Parameters:

block - the block to apply to the LoggerSettings.

Returns:

this

Since:

4.9

See Also:

• MongoClientSettings.getLoggerSettings()

applyToClusterSettings

public MongoClientSettings.Builder applyToClusterSettings(Block<ClusterSettings.Builder> block)

Applies the ClusterSettings.Builder block and then sets the clusterSettings.

Parameters:

block - the block to apply to the ClusterSettings.

Returns:

this

See Also:

• MongoClientSettings.getClusterSettings()

applyToSocketSettings

public MongoClientSettings.Builder applyToSocketSettings(Block<SocketSettings.Builder> block)

Applies the SocketSettings.Builder block and then sets the socketSettings.

Parameters:

block - the block to apply to the SocketSettings.

Returns:

this

See Also:

• MongoClientSettings.getSocketSettings()

applyToConnectionPoolSettings

public MongoClientSettings.Builder applyToConnectionPoolSettings(Block<ConnectionPoolSettings.Builder> block)

Applies the ConnectionPoolSettings.Builder block and then sets the connectionPoolSettings.

Parameters:

block - the block to apply to the ConnectionPoolSettings.

Returns:

this

See Also:

• MongoClientSettings.getConnectionPoolSettings()

applyToServerSettings

public MongoClientSettings.Builder applyToServerSettings(Block<ServerSettings.Builder> block)

Applies the ServerSettings.Builder block and then sets the serverSettings.

Parameters:

block - the block to apply to the ServerSettings.

Returns:

this

See Also:

• MongoClientSettings.getServerSettings()

applyToSslSettings

public MongoClientSettings.Builder applyToSslSettings(Block<SslSettings.Builder> block)

Applies the SslSettings.Builder block and then sets the sslSettings.

Parameters:

block - the block to apply to the SslSettings.

Returns:

this

See Also:

• MongoClientSettings.getSslSettings()

readPreference

public MongoClientSettings.Builder readPreference(ReadPreference readPreference)

Sets the read preference.

Parameters:

readPreference - read preference

Returns:

this

See Also:

• MongoClientSettings.getReadPreference()

writeConcern

public MongoClientSettings.Builder writeConcern(WriteConcern writeConcern)

Sets the write concern.

Parameters:

writeConcern - the write concern

Returns:

this

See Also:

• MongoClientSettings.getWriteConcern()

retryWrites

public MongoClientSettings.Builder retryWrites(boolean retryWrites)

Sets whether attempts to execute write commands should be retried if they fail due to a retryable error.

The errors having the "RetryableError" label are not the only ones considered retryable here: unlike applications, which may retry operations, the driver retries commands, which gives it more control and allows it to safely retry attempts failed due to a broader set of errors than what applications may safely retry.

For more information on how transactions affect retries, see the documentation of the "TransientTransactionError", "UnknownTransactionCommitResult" error labels.

Starting with the 3.11.0 release, the default value is true

Parameters:

retryWrites - sets if write commands should be retried if they fail due to a retryable error.

Returns:

this

See Also:

• MongoClientSettings.getRetryWrites()
• maxAdaptiveRetries(Integer)

MongoDB documentation

Retryable Writes

Since server release

3.6

retryReads

public MongoClientSettings.Builder retryReads(boolean retryReads)

Sets whether attempts to execute read commands should be retried if they fail due to a retryable error.

The errors having the "RetryableError" label are not the only ones considered retryable here: unlike applications, which may retry operations, the driver retries commands, which gives it more control and allows it to safely retry attempts failed due to a broader set of errors than what applications may safely retry.

For more information on how transactions affect retries, see the documentation of the "TransientTransactionError", "UnknownTransactionCommitResult" error labels.

Default is true.

Parameters:

retryReads - sets if read commands should be retried if they fail due to a retryable error.

Returns:

this

Since:

3.11

See Also:

• MongoClientSettings.getRetryReads()
• maxAdaptiveRetries(Integer)

MongoDB documentation

Retryable Reads

Since server release

3.6

maxAdaptiveRetries

@Beta(CLIENT)
public MongoClientSettings.Builder maxAdaptiveRetries(@Nullable
 Integer maxAdaptiveRetries)

Sets the maximum number of retry attempts when executing a command and encountering an error having the "SystemOverloadedError" and "RetryableError" labels. Such errors are referred to as retryable overload errors.

Default is null, implies the value 2 and the above retry behavior. The implied value and behavior may change in the future in a minor version. This means, there is no guarantee that not setting a value is equivalent to setting the value 2. The value 0 results in not retrying the attempts failed due to retryable overload errors.

Interactions with retryWrites(boolean)/retryReads(boolean)

Command kind	Interaction
write	The attempts failed due to retryable overload errors are retried only if retryWrites(boolean) is true.
read	The attempts failed due to retryable overload errors are retried only if retryReads(boolean) is true. Executing a write operation, for example, MongoCluster.bulkWrite, may involve executing not only write commands, but also read commands. In such a situation, just like in other situations, the behavior related to retries depends on the known kind of command, not on the kind of operation.
unknown	The attempts failed due to retryable overload errors are retried only if retryWrites(boolean) is true and retryReads(boolean) is true. The command kind is unknown if and only if a command is executed via the MongoDatabase.runCommand operation.

Parameters:

maxAdaptiveRetries - Sets the maximum number of retry attempts when encountering a retryable overload error.

Returns:

this.

Since:

5.12

See Also:

• MongoClientSettings.getMaxAdaptiveRetries()

MongoDB documentation

overloadAwareServerSelectionEnabled: the server-side counterpart, which is configured independently and affects the server behavior as opposed to the client behavior.

Since server release

9.0

enableOverloadRetargeting

@Beta(CLIENT)
public MongoClientSettings.Builder enableOverloadRetargeting(boolean enableOverloadRetargeting)

Sets whether to enable overload retargeting.

When enabled, the previously selected servers on which attempts failed with an error having the "SystemOverloadedError" label may be deprioritized during server selection on subsequent retry attempts. This applies to reads when retryReads is enabled, and to writes when retryWrites is enabled.

This setting does not take effect for sharded clusters.

Defaults to false.

Parameters:

enableOverloadRetargeting - whether to enable overload retargeting.

Returns:

this

Since:

5.12

See Also:

• MongoClientSettings.getEnableOverloadRetargeting()

Since server release

9.0

readConcern

public MongoClientSettings.Builder readConcern(ReadConcern readConcern)

Sets the read concern.

Parameters:

readConcern - the read concern

Returns:

this

MongoDB documentation

Read Concern

Since server release

3.2

credential

public MongoClientSettings.Builder credential(MongoCredential credential)

Sets the credential.

Parameters:

credential - the credential

Returns:

this

codecRegistry

public MongoClientSettings.Builder codecRegistry(CodecRegistry codecRegistry)

Sets the codec registry

The CodecRegistry configured by this method is effectively treated by the driver as an instance of CodecProvider, which CodecRegistry extends. So there is no benefit to defining a class that implements CodecRegistry. Rather, an application should always create CodecRegistry instances using the factory methods in CodecRegistries.

Parameters:

codecRegistry - the codec registry

Returns:

this

See Also:

• MongoClientSettings.getCodecRegistry()
• CodecRegistries

transportSettings

public MongoClientSettings.Builder transportSettings(TransportSettings transportSettings)

Sets the TransportSettings to apply.

Parameters:

transportSettings - the transport settings

Returns:

this

See Also:

• MongoClientSettings.getTransportSettings()

observabilitySettings

public MongoClientSettings.Builder observabilitySettings(ObservabilitySettings observabilitySettings)

Sets the ObservabilitySettings to apply.

Parameters:

observabilitySettings - the observability settings

Returns:

this

Since:

5.7

See Also:

• MongoClientSettings.getObservabilitySettings()

addCommandListener

public MongoClientSettings.Builder addCommandListener(CommandListener commandListener)

Adds the given command listener.

Parameters:

commandListener - the command listener

Returns:

this

commandListenerList

public MongoClientSettings.Builder commandListenerList(List<CommandListener> commandListeners)

Sets the command listeners

Parameters:

commandListeners - the list of command listeners

Returns:

this

applicationName

public MongoClientSettings.Builder applicationName(@Nullable
 String applicationName)

Sets the logical name of the application using this MongoClient. The application name may be used by the client to identify the application to the server, for use in server logs, slow query logs, and profile collection.

Parameters:

applicationName - the logical name of the application using this MongoClient. It may be null. The UTF-8 encoding may not exceed 128 bytes.

Returns:

this

See Also:

• MongoClientSettings.getApplicationName()

Since server release

3.4

compressorList

public MongoClientSettings.Builder compressorList(List<MongoCompressor> compressorList)

Sets the compressors to use for compressing messages to the server. The driver will use the first compressor in the list that the server is configured to support.

Parameters:

compressorList - the list of compressors to request

Returns:

this

See Also:

• MongoClientSettings.getCompressorList()

Since server release

3.4

uuidRepresentation

public MongoClientSettings.Builder uuidRepresentation(UuidRepresentation uuidRepresentation)

Sets the UUID representation to use when encoding instances of UUID and when decoding BSON binary values with subtype of 3.

See MongoClientSettings.getUuidRepresentation() for recommendations on settings this value

Parameters:

uuidRepresentation - the UUID representation, which may not be null

Returns:

this

Since:

3.12

serverApi

public MongoClientSettings.Builder serverApi(ServerApi serverApi)

Sets the server API to use when sending commands to the server.

This is required for some MongoDB deployments.

Parameters:

serverApi - the server API, which may not be null

Returns:

this

Since:

4.3

autoEncryptionSettings

public MongoClientSettings.Builder autoEncryptionSettings(@Nullable
 AutoEncryptionSettings autoEncryptionSettings)

Sets the auto-encryption settings

A separate, internal MongoClient is created if any of the following are true:

• AutoEncryptionSettings.keyVaultClient is not passed
• AutoEncryptionSettings.bypassAutomaticEncryption is false

If an internal MongoClient is created, it is configured with the same options as the parent MongoClient except minPoolSize is set to 0 and AutoEncryptionSettings is omitted.

Parameters:

autoEncryptionSettings - the auto-encryption settings

Returns:

this

Since:

3.11

See Also:

• MongoClientSettings.getAutoEncryptionSettings()

contextProvider

public MongoClientSettings.Builder contextProvider(@Nullable
 ContextProvider contextProvider)

Sets the context provider

When used with the synchronous driver, this must be an instance of com.mongodb.client.SynchronousContextProvider. When used with the reactive streams driver, this must be an instance of com.mongodb.reactivestreams.client.ReactiveContextProvider.

Parameters:

contextProvider - the context provider

Returns:

this

Since:

4.4

dnsClient

public MongoClientSettings.Builder dnsClient(@Nullable
 DnsClient dnsClient)

Sets the DnsClient to use for resolving DNS queries.

If set, it will be used to resolve SRV and TXT records for mongodb+srv connections. Otherwise, implementation of DnsClientProvider will be discovered via ServiceLoader and used to create an instance of DnsClient. If no implementation is discovered, then com.sun.jndi.dns.DnsContextFactory will be used to resolve these records.

If applying a connection string to these settings, care must be taken to also pass the same DnsClient as an argument to the ConnectionString constructor.

Parameters:

dnsClient - the DNS client

Returns:

the DNS client

Since:

4.10

See Also:

• ConnectionString(String, DnsClient)

inetAddressResolver

public MongoClientSettings.Builder inetAddressResolver(@Nullable
 InetAddressResolver inetAddressResolver)

Sets the InetAddressResolver to use for looking up the InetAddress instances for each host.

If set, it will be used to look up the InetAddress for each host, via InetAddressResolver.lookupByName(String). Otherwise, an implementation of InetAddressResolverProvider will be discovered via ServiceLoader and used to create an instance of InetAddressResolver. If no implementation is discovered, InetAddress.getAllByName(String) will be used to lookup the InetAddress instances for a host.

Parameters:

inetAddressResolver - the InetAddress provider

Returns:

the InetAddress resolver

Since:

4.10

See Also:

• MongoClientSettings.getInetAddressResolver()

timeout

@Alpha(CLIENT)
public MongoClientSettings.Builder timeout(long timeout,
 TimeUnit timeUnit)

Sets the time limit for the full execution of an operation.

• null means that the timeout mechanism for operations will defer to using:
  • waitQueueTimeoutMS: The maximum wait time in milliseconds that a thread may wait for a connection to become available
  • socketTimeoutMS: How long a send or receive on a socket can take before timing out.
  • wTimeoutMS: How long the server will wait for the write concern to be fulfilled before timing out.
  • maxTimeMS: The cumulative time limit for processing operations on a cursor. See: cursor.maxTimeMS.
  • maxCommitTimeMS: The maximum amount of time to allow a single commitTransaction command to execute. See: TransactionOptions.getMaxCommitTime(java.util.concurrent.TimeUnit).
• 0 means infinite timeout.
• > 0 The time limit to use for the full execution of an operation.

Note: When using synchronous API, this timeout does not limit socket writes, therefore there is a possibility that the operation might not be timed out when expected. This limitation does not apply to the reactive streams API.

Parameters:

timeout - the timeout

timeUnit - the time unit

Returns:

this

Since:

5.2

See Also:

• MongoClientSettings.getTimeout(java.util.concurrent.TimeUnit)

build

public MongoClientSettings build()

Build an instance of MongoClientSettings.

Returns:

the settings from this builder