Class MongoClientOptions
Various settings to control the behavior of a MongoClient
.
- Since:
- 2.10.0
- See Also:
-
Nested Class Summary
Modifier and TypeClassDescriptionstatic class
A builder for MongoClientOptions so that MongoClientOptions can be immutable, and to support easier construction through chaining. -
Method Summary
Modifier and TypeMethodDescriptionasMongoClientSettings
(List<ServerAddress> hosts, String srvHost, ClusterConnectionMode clusterConnectionMode, MongoCredential credential) Translate this instance intoMongoClientSettings
.static MongoClientOptions.Builder
builder()
Creates a builder instance.static MongoClientOptions.Builder
builder
(MongoClientOptions options) Creates a builder instance.static MongoClientOptions.Builder
builder
(MongoClientSettings settings) Creates a builder instance from aMongoClientSettings
instance.boolean
Gets the logical name of the application using this MongoClient.Gets the auto-encryption settingsGets the list of addedClusterListener
.The codec registry to use.Gets the list of addedCommandListener
.Gets the compressors to use for compressing messages to the server.Gets the list of addedConnectionPoolListener
.int
The maximum number of connections allowed per host for this MongoClient instance.int
The connection timeout in milliseconds.Override the decoder factory.Override the encoder factory.int
Gets the connect timeout for connections used for the cluster heartbeat.int
Gets the heartbeat frequency.int
Gets the socket timeout for connections used for the cluster heartbeat.int
Gets the local threshold.long
Returns the time period between runs of the maintenance job on each connection pool.long
Returns the period of time to wait before running the first maintenance job on each connection pool.int
The maximum number of connections a pool may be establishing concurrently.int
The maximum idle time of a pooled connection.int
The maximum life time of a pooled connection.int
The maximum wait time in milliseconds that a thread may wait for a connection to become available.int
The minimum number of connections per host for this MongoClient instance.int
Gets the minimum heartbeat frequency.The read concern to use.The read preference to use for queries, map-reduce, aggregation, and count.Gets the required replica set name.boolean
Returns true if reads should be retried if they fail due to a network error or other retryable error.boolean
Returns true if writes should be retried if they fail due to a network error or other retryable error.Gets the server API to use when sending commands to the server.Gets the list of addedServerListener
.Gets the list of addedServerMonitorListener
.int
Gets the server selection timeout in milliseconds, which defines how long the driver will wait for server selection to succeed before throwing an exception.Gets the server selector.int
The socket timeout in milliseconds.Gets the maximum number of hosts to connect to when using SRV protocol.Gets the SRV service name.Returns the SSLContext.The time limit for the full execution of an operation in Milliseconds.Gets the UUID representation to use when encoding instances ofUUID
and when decoding BSON binary values with subtype of 3.The write concern to use.int
hashCode()
boolean
Gets whether there is a a finalize method created that cleans up instances of DBCursor that the client does not close.boolean
Whether to use SSL.boolean
Returns whether invalid host names should be allowed if SSL is enabled.toString()
-
Method Details
-
builder
Creates a builder instance.- Returns:
- a builder
- Since:
- 3.0.0
-
builder
Creates a builder instance.- Parameters:
options
- existing MongoClientOptions to default the builder settings on.- Returns:
- a builder
- Since:
- 3.0.0
-
builder
Creates a builder instance from aMongoClientSettings
instance.- Parameters:
settings
- the settings to from which to initialize the builder- Returns:
- a builder
- Since:
- 4.2
-
asMongoClientSettings
public MongoClientSettings asMongoClientSettings(@Nullable List<ServerAddress> hosts, @Nullable String srvHost, ClusterConnectionMode clusterConnectionMode, @Nullable MongoCredential credential) Translate this instance intoMongoClientSettings
.- Parameters:
hosts
- the seed list of hosts to connect to, which must be null if srvHost is notsrvHost
- the SRV host name, which must be null if hosts is notclusterConnectionMode
- the connection modecredential
- the credential, which may be null- Returns:
- the settings
- Since:
- 4.2
- See Also:
-
getApplicationName
Gets 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.Default is null.
- Returns:
- the application name, which may be null
- Since:
- 3.4
- Since server release
- 3.4
-
getCompressorList
Gets 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.Default is the empty list.
- Returns:
- the compressors
- Since:
- 3.6
- Since server release
- 3.4
-
getConnectionsPerHost
public int getConnectionsPerHost()The maximum number of connections allowed per host for this MongoClient instance. Those connections will be kept in a pool when idle. Once the pool is exhausted, any operation requiring a connection will block waiting for an available connection.
Default is 100.
- Returns:
- the maximum size of the connection pool per host; if 0, then there is no limit.
-
getMinConnectionsPerHost
public int getMinConnectionsPerHost()The minimum number of connections per host for this MongoClient instance. Those connections will be kept in a pool when idle, and the pool will ensure over time that it contains at least this minimum number.
Default is 0.
- Returns:
- the minimum size of the connection pool per host
-
getServerSelectionTimeout
public int getServerSelectionTimeout()Gets the server selection timeout in milliseconds, which defines how long the driver will wait for server selection to succeed before throwing an exception.
Default is 30,000 milliseconds. A value of 0 means that it will timeout immediately if no server is available. A negative value means to wait indefinitely.
- Returns:
- the server selection timeout in milliseconds.
-
getMaxWaitTime
public int getMaxWaitTime()The maximum wait time in milliseconds that a thread may wait for a connection to become available.
Default is 120,000 milliseconds. A value of 0 means that it will not wait. A negative value means to wait indefinitely.
- Returns:
- the maximum wait time.
-
getMaxConnectionIdleTime
public int getMaxConnectionIdleTime()The maximum idle time of a pooled connection. A zero value indicates no limit to the idle time. A pooled connection that has exceeded its idle time will be closed and replaced when necessary by a new connection.Default is 0, indicating no limit to the idle time.
- Returns:
- the maximum idle time, in milliseconds
- Since:
- 2.12
-
getMaxConnectionLifeTime
public int getMaxConnectionLifeTime()The maximum life time of a pooled connection. A zero value indicates no limit to the life time. A pooled connection that has exceeded its life time will be closed and replaced when necessary by a new connection.Default is 0, indicating no limit to the life time.
- Returns:
- the maximum life time, in milliseconds
- Since:
- 2.12
-
getMaxConnecting
public int getMaxConnecting()The maximum number of connections a pool may be establishing concurrently. Establishment of a connection is a part of its life cycle starting after aConnectionCreatedEvent
and ending before aConnectionReadyEvent
.Default is 2.
- Returns:
- The maximum number of connections a pool may be establishing concurrently.
- Since:
- 4.4
- See Also:
-
getMaintenanceInitialDelay
public long getMaintenanceInitialDelay()Returns the period of time to wait before running the first maintenance job on each connection pool.Default is 0 ms.
- Returns:
- the time period to wait in milliseconds
- Since:
- 4.7
- See Also:
-
getMaintenanceFrequency
public long getMaintenanceFrequency()Returns the time period between runs of the maintenance job on each connection pool.Default is 60,000 ms.
- Returns:
- the time period between runs of the maintainance job in milliseconds
- Since:
- 4.7
- See Also:
-
getConnectTimeout
public int getConnectTimeout()The connection timeout in milliseconds. A value of 0 means no timeout. It is used solely when establishing a new connection
Socket.connect(java.net.SocketAddress, int)
Default is 10,000 milliseconds.
- Returns:
- the socket connect timeout
-
getSocketTimeout
public int getSocketTimeout()The socket timeout in milliseconds. It is used for I/O socket read operations
Socket.setSoTimeout(int)
Default is 0 and means no timeout.
- Returns:
- the socket timeout, in milliseconds
-
getHeartbeatFrequency
public int getHeartbeatFrequency()Gets the heartbeat frequency. This is the frequency that the driver will attempt to determine the current state of each server in the cluster.Default is 10,000 milliseconds.
- Returns:
- the heartbeat frequency, in milliseconds
- Since:
- 2.12
-
getMinHeartbeatFrequency
public int getMinHeartbeatFrequency()Gets the minimum heartbeat frequency. In the event that the driver has to frequently re-check a server's availability, it will wait at least this long since the previous check to avoid wasted effort.Default is 500 milliseconds.
- Returns:
- the minimum heartbeat frequency, in milliseconds
- Since:
- 2.13
-
getHeartbeatConnectTimeout
public int getHeartbeatConnectTimeout()Gets the connect timeout for connections used for the cluster heartbeat.
Default is 20,000 milliseconds.
- Returns:
- the heartbeat connect timeout, in milliseconds
- Since:
- 2.12
-
getHeartbeatSocketTimeout
public int getHeartbeatSocketTimeout()Gets the socket timeout for connections used for the cluster heartbeat.Default is 20,000 milliseconds.
- Returns:
- the heartbeat socket timeout, in milliseconds
- Since:
- 2.12
-
getLocalThreshold
public int getLocalThreshold()Gets the local threshold. When choosing among multiple MongoDB servers to send a request, the MongoClient will only send that request to a server whose ping time is less than or equal to the server with the fastest ping time plus the local threshold.
For example, let's say that the client is choosing a server to send a query when the read preference is
ReadPreference.secondary()
, and that there are three secondaries, server1, server2, and server3, whose ping times are 10, 15, and 16 milliseconds, respectively. With a local threshold of 5 milliseconds, the client will send the query to either server1 or server2 (randomly selecting between the two).Default is 15 milliseconds.
- Returns:
- the local threshold, in milliseconds
- Since:
- 2.13.0
- MongoDB documentation
- Local Threshold
-
getRequiredReplicaSetName
Gets the required replica set name. With this option set, the MongoClient instance will
- Connect in replica set mode, and discover all members of the set based on the given servers
- Make sure that the set name reported by all members matches the required set name.
- Refuse to service any requests if any member of the seed list is not part of a replica set with the required name.
- Returns:
- the required replica set name
- Since:
- 2.12
-
isSslEnabled
public boolean isSslEnabled()Whether to use SSL.Default is
false
.- Returns:
- true if SSL should be used
- Since:
- 3.0
-
isSslInvalidHostNameAllowed
public boolean isSslInvalidHostNameAllowed()Returns whether invalid host names should be allowed if SSL is enabled. Take care before setting this to true, as it makes the application susceptible to man-in-the-middle attacks.Default is
false
.- Returns:
- true if invalid host names are allowed.
-
getSslContext
Returns the SSLContext. This property is ignored when either sslEnabled is false or socketFactory is non-null.- Returns:
- the configured SSLContext, which may be null. In that case
SSLContext.getDefault()
will be used when SSL is enabled. - Since:
- 3.5
-
getReadPreference
The read preference to use for queries, map-reduce, aggregation, and count.
Default is
ReadPreference.primary()
.- Returns:
- the read preference
- See Also:
-
getWriteConcern
The write concern to use.
Default is
WriteConcern.ACKNOWLEDGED
.- Returns:
- the write concern
- See Also:
-
getRetryWrites
public boolean getRetryWrites()Returns true if writes should be retried if they fail due to a network error or other retryable error.Starting with the 3.11.0 release, the default value is true
- Returns:
- the retryWrites value
- Since:
- 3.6
- Since server release
- 3.6
-
getRetryReads
public boolean getRetryReads()Returns true if reads should be retried if they fail due to a network error or other retryable error.- Returns:
- the retryReads value
- Since:
- 3.11
- Since server release
- 3.6
-
getReadConcern
The read concern to use.
- Returns:
- the read concern
- Since:
- 3.2
- MongoDB documentation
- Read Concern
- Since server release
- 3.2
-
getCodecRegistry
The codec registry to use. By default, a
MongoClient
will be able to encode and decode instances ofDocument
.Note that instances of
DB
andDBCollection
do not use the registry, so it's not necessary to include a codec for DBObject in the registry.- Returns:
- the codec registry
- Since:
- 3.0
- See Also:
-
getUuidRepresentation
Gets the UUID representation to use when encoding instances ofUUID
and when decoding BSON binary values with subtype of 3.The default is
UuidRepresentation.UNSPECIFIED
, If your application stores UUID values in MongoDB, you must set this value to the desired representation. New applications should preferUuidRepresentation.STANDARD
, while existing Java applications should preferUuidRepresentation.JAVA_LEGACY
. Applications wishing to interoperate with existing Python or .NET applications should preferUuidRepresentation.PYTHON_LEGACY
orUuidRepresentation.C_SHARP_LEGACY
, respectively. Applications that do not store UUID values in MongoDB don't need to set this value.- Returns:
- the UUID representation, which may not be null
- Since:
- 3.12
-
getSrvMaxHosts
Gets the maximum number of hosts to connect to when using SRV protocol.- Returns:
- the maximum number of hosts to connect to when using SRV protocol. Defaults to null.
- Since:
- 4.5
-
getSrvServiceName
Gets the SRV service name.The SRV resource record (RFC 2782) service name, which is limited to 15 characters (RFC 6335 section 5.1). If specified, it is combined with the single host name as follows:
_srvServiceName._tcp.hostName
. The combined string is an SRV resource record name (RFC 1035 section 2.3.1), which is limited to 255 characters (RFC 1035 section 2.3.4).- Returns:
- the SRV service name, which defaults to
"mongodb"
- Since:
- 4.5
-
getServerApi
Gets the server API to use when sending commands to the server.- Returns:
- the server API, which may be null
- Since:
- 4.3
-
getTimeout
The time limit for the full execution of an operation in Milliseconds.If set the following deprecated options will be ignored:
waitQueueTimeoutMS
,socketTimeoutMS
,wTimeoutMS
,maxTimeMS
andmaxCommitTimeMS
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 availablesocketTimeoutMS
: 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 singlecommitTransaction
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.
- Returns:
- the timeout in milliseconds
- Since:
- 5.2
-
getServerSelector
Gets the server selector.The server selector augments the normal server selection rules applied by the driver when determining which server to send an operation to. At the point that it's called by the driver, the
ClusterDescription
which is passed to it contains a list ofServerDescription
instances which satisfy either the configuredReadPreference
for any read operation or ones that can take writes (e.g. a standalone, mongos, or replica set primary).The server selector can then filter the
ServerDescription
list using whatever criteria that is required by the application.After this selector executes, two additional selectors are applied by the driver:
- select from within the latency window
- select a random server from those remaining
To skip the latency window selector, an application can:
- configure the local threshold to a sufficiently high value so that it doesn't exclude any servers
- return a list containing a single server from this selector (which will also make the random member selector a no-op)
- Returns:
- the server selector, which may be null
- Since:
- 3.6
-
getClusterListeners
Gets the list of addedClusterListener
. The default is an empty list.- Returns:
- the unmodifiable list of cluster listeners
- Since:
- 3.3
-
getCommandListeners
Gets the list of addedCommandListener
.Default is an empty list.
- Returns:
- the unmodifiable list of command listeners
- Since:
- 3.1
-
getConnectionPoolListeners
Gets the list of addedConnectionPoolListener
. The default is an empty list.- Returns:
- the unmodifiable list of connection pool listeners
- Since:
- 3.5
-
getServerListeners
Gets the list of addedServerListener
. The default is an empty list.- Returns:
- the unmodifiable list of server listeners
- Since:
- 3.3
-
getServerMonitorListeners
Gets the list of addedServerMonitorListener
. The default is an empty list.- Returns:
- the unmodifiable list of server monitor listeners
- Since:
- 3.3
-
getDbDecoderFactory
Override the decoder factory.Default is for the standard Mongo Java driver configuration.
- Returns:
- the decoder factory
-
getDbEncoderFactory
Override the encoder factory.Default is for the standard Mongo Java driver configuration.
- Returns:
- the encoder factory
-
isCursorFinalizerEnabled
public boolean isCursorFinalizerEnabled()Gets whether there is a a finalize method created that cleans up instances of DBCursor that the client does not close. If you are careful to always call the close method of DBCursor, then this can safely be set to false.
Default is true.
- Returns:
- whether finalizers are enabled on cursors
- See Also:
-
getAutoEncryptionSettings
Gets the auto-encryption settings- Returns:
- the auto-encryption settings, which may be null
- Since:
- 3.11
-
equals
-
hashCode
public int hashCode() -
toString
-