Package com.mongodb.client

Interface MongoCluster

All Known Subinterfaces:

MongoClient

@Immutable
public interface MongoCluster

The client-side representation of a MongoDB cluster operations.

The originating MongoClient is responsible for the closing of resources. If the originator MongoClient is closed, then any cluster operations will fail.

Since:

5.2

See Also:

• MongoClient

Method Summary

Modifier and Type	Method	Description
ClientBulkWriteResult	bulkWrite(ClientSession clientSession, List<? extends ClientNamespacedWriteModel> models)	Executes a client-level bulk write operation.
ClientBulkWriteResult	bulkWrite(ClientSession clientSession, List<? extends ClientNamespacedWriteModel> models, ClientBulkWriteOptions options)	Executes a client-level bulk write operation.
ClientBulkWriteResult	bulkWrite(List<? extends ClientNamespacedWriteModel> models)	Executes a client-level bulk write operation.
ClientBulkWriteResult	bulkWrite(List<? extends ClientNamespacedWriteModel> models, ClientBulkWriteOptions options)	Executes a client-level bulk write operation.
CodecRegistry	getCodecRegistry()	Get the codec registry for the MongoCluster.
MongoDatabase	getDatabase(String databaseName)	Gets a MongoDatabase instance for the given database name.
ReadConcern	getReadConcern()	Get the read concern for the MongoCluster.
ReadPreference	getReadPreference()	Get the read preference for the MongoCluster.
Long	getTimeout(TimeUnit timeUnit)	The time limit for the full execution of an operation.
WriteConcern	getWriteConcern()	Get the write concern for the MongoCluster.
MongoIterable<String>	listDatabaseNames()	Get a list of the database names
MongoIterable<String>	listDatabaseNames(ClientSession clientSession)	Get a list of the database names
ListDatabasesIterable<Document>	listDatabases()	Gets the list of databases
ListDatabasesIterable<Document>	listDatabases(ClientSession clientSession)	Gets the list of databases
<TResult> ListDatabasesIterable<TResult>	listDatabases(ClientSession clientSession, Class<TResult> resultClass)	Gets the list of databases
<TResult> ListDatabasesIterable<TResult>	listDatabases(Class<TResult> resultClass)	Gets the list of databases
ClientSession	startSession()	Creates a client session with default options.
ClientSession	startSession(ClientSessionOptions options)	Creates a client session.
ChangeStreamIterable<Document>	watch()	Creates a change stream for this client.
ChangeStreamIterable<Document>	watch(ClientSession clientSession)	Creates a change stream for this client.
<TResult> ChangeStreamIterable<TResult>	watch(ClientSession clientSession, Class<TResult> resultClass)	Creates a change stream for this client.
ChangeStreamIterable<Document>	watch(ClientSession clientSession, List<? extends Bson> pipeline)	Creates a change stream for this client.
<TResult> ChangeStreamIterable<TResult>	watch(ClientSession clientSession, List<? extends Bson> pipeline, Class<TResult> resultClass)	Creates a change stream for this client.
<TResult> ChangeStreamIterable<TResult>	watch(Class<TResult> resultClass)	Creates a change stream for this client.
ChangeStreamIterable<Document>	watch(List<? extends Bson> pipeline)	Creates a change stream for this client.
<TResult> ChangeStreamIterable<TResult>	watch(List<? extends Bson> pipeline, Class<TResult> resultClass)	Creates a change stream for this client.
MongoCluster	withCodecRegistry(CodecRegistry codecRegistry)	Create a new MongoCluster instance with a different codec registry.
MongoCluster	withReadConcern(ReadConcern readConcern)	Create a new MongoCluster instance with a different read concern.
MongoCluster	withReadPreference(ReadPreference readPreference)	Create a new MongoCluster instance with a different read preference.
MongoCluster	withTimeout(long timeout, TimeUnit timeUnit)	Create a new MongoCluster instance with the set time limit for the full execution of an operation.
MongoCluster	withWriteConcern(WriteConcern writeConcern)	Create a new MongoCluster instance with a different write concern.

Method Details

getCodecRegistry

CodecRegistry getCodecRegistry()

Get the codec registry for the MongoCluster.

Returns:

the CodecRegistry

Since:

5.2

getReadPreference

ReadPreference getReadPreference()

Get the read preference for the MongoCluster.

Returns:

the ReadPreference

Since:

5.2

getWriteConcern

WriteConcern getWriteConcern()

Get the write concern for the MongoCluster.

Returns:

the WriteConcern

Since:

5.2

getReadConcern

ReadConcern getReadConcern()

Get the read concern for the MongoCluster.

Returns:

the ReadConcern

Since:

5.2

MongoDB documentation

Read Concern

getTimeout

@Alpha(CLIENT)
@Nullable
Long getTimeout(TimeUnit timeUnit)

The time limit for the full execution of an operation.

If not null the following deprecated options will be ignored: waitQueueTimeoutMS, socketTimeoutMS, wTimeoutMS, maxTimeMS and maxCommitTimeMS

• 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.

Parameters:

timeUnit - the time unit

Returns:

the timeout in the given time unit

Since:

5.2

withCodecRegistry

MongoCluster withCodecRegistry(CodecRegistry codecRegistry)

Create a new MongoCluster instance with a different 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 new CodecRegistry for the database

Returns:

a new MongoCluster instance with the different codec registry

Since:

5.2

See Also:

• CodecRegistries

withReadPreference

MongoCluster withReadPreference(ReadPreference readPreference)

Create a new MongoCluster instance with a different read preference.

Parameters:

readPreference - the new ReadPreference for the database

Returns:

a new MongoCluster instance with the different readPreference

Since:

5.2

withWriteConcern

MongoCluster withWriteConcern(WriteConcern writeConcern)

Create a new MongoCluster instance with a different write concern.

Parameters:

writeConcern - the new WriteConcern for the database

Returns:

a new MongoCluster instance with the different writeConcern

Since:

5.2

withReadConcern

MongoCluster withReadConcern(ReadConcern readConcern)

Create a new MongoCluster instance with a different read concern.

Parameters:

readConcern - the new ReadConcern for the database

Returns:

a new MongoCluster instance with the different ReadConcern

Since:

5.2

MongoDB documentation

Read Concern

withTimeout

@Alpha(CLIENT)
MongoCluster withTimeout(long timeout,
 TimeUnit timeUnit)

Create a new MongoCluster instance with the set time limit for the full execution of an operation.

• 0 means infinite timeout.
• > 0 The time limit to use for the full execution of an operation.

Parameters:

timeout - the timeout, which must be greater than or equal to 0

timeUnit - the time unit

Returns:

a new MongoCluster instance with the set time limit for the full execution of an operation.

Since:

5.2

See Also:

• getTimeout(java.util.concurrent.TimeUnit)

getDatabase

MongoDatabase getDatabase(String databaseName)

Gets a MongoDatabase instance for the given database name.

Parameters:

databaseName - the name of the database to retrieve

Returns:

a MongoDatabase representing the specified database

Throws:

IllegalArgumentException - if databaseName is invalid

See Also:

• MongoNamespace.checkDatabaseNameValidity(String)

startSession

ClientSession startSession()

Creates a client session with default options.

Note: A ClientSession instance can not be used concurrently in multiple operations.

Returns:

the client session

Since server release

3.6

startSession

ClientSession startSession(ClientSessionOptions options)

Creates a client session.

Note: A ClientSession instance can not be used concurrently in multiple operations.

Parameters:

options - the options for the client session

Returns:

the client session

Since server release

3.6

listDatabaseNames

MongoIterable<String> listDatabaseNames()

Get a list of the database names

Returns:

an iterable containing all the names of all the databases

MongoDB documentation

List Databases

listDatabaseNames

MongoIterable<String> listDatabaseNames(ClientSession clientSession)

Get a list of the database names

Parameters:

clientSession - the client session with which to associate this operation

Returns:

an iterable containing all the names of all the databases

MongoDB documentation

List Databases

Since server release

3.6

listDatabases

ListDatabasesIterable<Document> listDatabases()

Gets the list of databases

Returns:

the list databases iterable interface

listDatabases

ListDatabasesIterable<Document> listDatabases(ClientSession clientSession)

Gets the list of databases

Parameters:

clientSession - the client session with which to associate this operation

Returns:

the list databases iterable interface

MongoDB documentation

List Databases

Since server release

3.6

listDatabases

<TResult> ListDatabasesIterable<TResult> listDatabases(Class<TResult> resultClass)

Gets the list of databases

Type Parameters:

TResult - the type of the class to use instead of Document.

Parameters:

resultClass - the class to cast the database documents to

Returns:

the list databases iterable interface

listDatabases

<TResult> ListDatabasesIterable<TResult> listDatabases(ClientSession clientSession,
 Class<TResult> resultClass)

Gets the list of databases

Type Parameters:

TResult - the type of the class to use instead of Document.

Parameters:

clientSession - the client session with which to associate this operation

resultClass - the class to cast the database documents to

Returns:

the list databases iterable interface

MongoDB documentation

List Databases

Since server release

3.6

watch

ChangeStreamIterable<Document> watch()

Creates a change stream for this client.

Returns:

the change stream iterable

Since:

3.8

MongoDB documentation

Change Streams

Since server release

4.0

watch

<TResult> ChangeStreamIterable<TResult> watch(Class<TResult> resultClass)

Creates a change stream for this client.

Type Parameters:

TResult - the target document type of the iterable.

Parameters:

resultClass - the class to decode each document into

Returns:

the change stream iterable

Since:

3.8

MongoDB documentation

Change Streams

Since server release

4.0

watch

ChangeStreamIterable<Document> watch(List<? extends Bson> pipeline)

Creates a change stream for this client.

Parameters:

pipeline - the aggregation pipeline to apply to the change stream.

Returns:

the change stream iterable

Since:

3.8

MongoDB documentation

Change Streams

Since server release

4.0

watch

<TResult> ChangeStreamIterable<TResult> watch(List<? extends Bson> pipeline,
 Class<TResult> resultClass)

Creates a change stream for this client.

Type Parameters:

TResult - the target document type of the iterable.

Parameters:

pipeline - the aggregation pipeline to apply to the change stream

resultClass - the class to decode each document into

Returns:

the change stream iterable

Since:

3.8

MongoDB documentation

Change Streams

Since server release

4.0

watch

ChangeStreamIterable<Document> watch(ClientSession clientSession)

Creates a change stream for this client.

Parameters:

clientSession - the client session with which to associate this operation

Returns:

the change stream iterable

Since:

3.8

MongoDB documentation

Change Streams

Since server release

4.0

watch

<TResult> ChangeStreamIterable<TResult> watch(ClientSession clientSession,
 Class<TResult> resultClass)

Creates a change stream for this client.

Type Parameters:

TResult - the target document type of the iterable.

Parameters:

clientSession - the client session with which to associate this operation

resultClass - the class to decode each document into

Returns:

the change stream iterable

Since:

3.8

MongoDB documentation

Change Streams

Since server release

4.0

watch

ChangeStreamIterable<Document> watch(ClientSession clientSession,
 List<? extends Bson> pipeline)

Creates a change stream for this client.

Parameters:

clientSession - the client session with which to associate this operation

pipeline - the aggregation pipeline to apply to the change stream.

Returns:

the change stream iterable

Since:

3.8

MongoDB documentation

Change Streams

Since server release

4.0

watch

<TResult> ChangeStreamIterable<TResult> watch(ClientSession clientSession,
 List<? extends Bson> pipeline,
 Class<TResult> resultClass)

Creates a change stream for this client.

Type Parameters:

TResult - the target document type of the iterable.

Parameters:

clientSession - the client session with which to associate this operation

pipeline - the aggregation pipeline to apply to the change stream

resultClass - the class to decode each document into

Returns:

the change stream iterable

Since:

3.8

MongoDB documentation

Change Streams

Since server release

4.0

bulkWrite

ClientBulkWriteResult bulkWrite(List<? extends ClientNamespacedWriteModel> models)
                         throws ClientBulkWriteException

Executes a client-level bulk write operation. This method is functionally equivalent to bulkWrite(List, ClientBulkWriteOptions) with the default options.

This operation supports retryable writes. Depending on the number of models, encoded size of models, and the size limits in effect, executing this operation may require multiple bulkWrite commands. The eligibility for retries is determined per each bulkWrite command: ClientNamespacedUpdateManyModel, ClientNamespacedDeleteManyModel in a command render it non-retryable.

This operation is not supported by MongoDB Atlas Serverless instances.

Parameters:

models - The individual write operations.

Returns:

The ClientBulkWriteResult if the operation is successful.

Throws:

ClientBulkWriteException - If and only if the operation is unsuccessful or partially unsuccessful, and there is at least one of the following pieces of information to report: ClientBulkWriteException.getWriteConcernErrors(), ClientBulkWriteException.getWriteErrors(), ClientBulkWriteException.getPartialResult().

MongoException - Only if the operation is unsuccessful.

Since:

5.3

MongoDB documentation

bulkWrite

Since server release

8.0

bulkWrite

ClientBulkWriteResult bulkWrite(List<? extends ClientNamespacedWriteModel> models,
 ClientBulkWriteOptions options)
                         throws ClientBulkWriteException

Executes a client-level bulk write operation.

This operation supports retryable writes. Depending on the number of models, encoded size of models, and the size limits in effect, executing this operation may require multiple bulkWrite commands. The eligibility for retries is determined per each bulkWrite command: ClientNamespacedUpdateManyModel, ClientNamespacedDeleteManyModel in a command render it non-retryable.

This operation is not supported by MongoDB Atlas Serverless instances.

Parameters:

models - The individual write operations.

options - The options.

Returns:

The ClientBulkWriteResult if the operation is successful.

Throws:

ClientBulkWriteException - If and only if the operation is unsuccessful or partially unsuccessful, and there is at least one of the following pieces of information to report: ClientBulkWriteException.getWriteConcernErrors(), ClientBulkWriteException.getWriteErrors(), ClientBulkWriteException.getPartialResult().

MongoException - Only if the operation is unsuccessful.

Since:

5.3

MongoDB documentation

bulkWrite

Since server release

8.0

bulkWrite

ClientBulkWriteResult bulkWrite(ClientSession clientSession,
 List<? extends ClientNamespacedWriteModel> models)
                         throws ClientBulkWriteException

Executes a client-level bulk write operation. This method is functionally equivalent to bulkWrite(ClientSession, List, ClientBulkWriteOptions) with the default options.

This operation supports retryable writes. Depending on the number of models, encoded size of models, and the size limits in effect, executing this operation may require multiple bulkWrite commands. The eligibility for retries is determined per each bulkWrite command: ClientNamespacedUpdateManyModel, ClientNamespacedDeleteManyModel in a command render it non-retryable.

This operation is not supported by MongoDB Atlas Serverless instances.

Parameters:

clientSession - The client session with which to associate this operation.

models - The individual write operations.

Returns:

The ClientBulkWriteResult if the operation is successful.

Throws:

ClientBulkWriteException - If and only if the operation is unsuccessful or partially unsuccessful, and there is at least one of the following pieces of information to report: ClientBulkWriteException.getWriteConcernErrors(), ClientBulkWriteException.getWriteErrors(), ClientBulkWriteException.getPartialResult().

MongoException - Only if the operation is unsuccessful.

Since:

5.3

MongoDB documentation

bulkWrite

Since server release

8.0

bulkWrite

ClientBulkWriteResult bulkWrite(ClientSession clientSession,
 List<? extends ClientNamespacedWriteModel> models,
 ClientBulkWriteOptions options)
                         throws ClientBulkWriteException

Executes a client-level bulk write operation.

This operation supports retryable writes. Depending on the number of models, encoded size of models, and the size limits in effect, executing this operation may require multiple bulkWrite commands. The eligibility for retries is determined per each bulkWrite command: ClientNamespacedUpdateManyModel, ClientNamespacedDeleteManyModel in a command render it non-retryable.

This operation is not supported by MongoDB Atlas Serverless instances.

Parameters:

clientSession - The client session with which to associate this operation.

models - The individual write operations.

options - The options.

Returns:

The ClientBulkWriteResult if the operation is successful.

Throws:

ClientBulkWriteException - If and only if the operation is unsuccessful or partially unsuccessful, and there is at least one of the following pieces of information to report: ClientBulkWriteException.getWriteConcernErrors(), ClientBulkWriteException.getWriteErrors(), ClientBulkWriteException.getPartialResult().

MongoException - Only if the operation is unsuccessful.

Since:

5.3

MongoDB documentation

bulkWrite

Since server release

8.0