Class MongoClient
- All Implemented Interfaces:
Closeable
,AutoCloseable
A MongoDB client with internal connection pooling. For most applications, you should have one MongoClient instance for the entire JVM.
The following are equivalent, and all connect to the local database running on the default port:
new MongoClient() new MongoClient("mongodb://localhost") new MongoClient("mongodb://localhost:27017"); new MongoClient(MongoClientSettings.builder() .applyConnectionString("mongodb://localhost") .build())
You can connect to a replica set by passing a list of servers to a MongoClient constructor. For example:
new MongoClient("mongodb://localhost:27017,localhost:27018,localhost:27019") new MongoClient(MongoClientSettings.builder() .applyConnectionString("mongodb://localhost:27017,localhost:27018,localhost:27019") .build())
You can connect to a sharded cluster using the same constructor invocations. MongoClient will auto-detect whether the servers are a list of replica set members or a list of mongos servers.
By default, all read and write operations will be made on the primary, but it's possible to read from secondaries by changing the read preference:
new MongoClient("mongodb://localhost:27017,localhost:27018,localhost:27019?readPreference=primary") new MongoClient(MongoClientSettings.builder() .applyConnectionString("mongodb://localhost:27017,localhost:27018,localhost:27019/?readPreference=primary") .build()) new MongoClient(MongoClientSettings.builder() .applyConnectionString("mongodb://localhost:27017,localhost:27018,localhost:27019") .readPreference(ReadPreference.primary()) .build())
By default, all write operations will wait for acknowledgment by the server, as the default write concern is
WriteConcern.ACKNOWLEDGED
. It's possible to change this with a setting:
new MongoClient("mongodb://localhost:27017,localhost:27018,localhost:27019?w=majority") new MongoClient(MongoClientSettings.builder() .applyConnectionString("mongodb://localhost:27017,localhost:27018,localhost:27019/?w=majority") .build()) new MongoClient(MongoClientSettings.builder() .applyConnectionString("mongodb://localhost:27017,localhost:27018,localhost:27019") .writeConcern(WriteConcern.MAJORITY) .build())
In general, users of this class will pick up all of the default options specified in MongoClientSettings
.
- Since:
- 2.10.0
- See Also:
-
Constructor Summary
ConstructorDescriptionCreates an instance based on a (single) MongoDB server ("mongodb://127.0.0.1:27017"
).MongoClient
(ConnectionString connectionString) Create a new client with the given connection string.MongoClient
(ConnectionString connectionString, MongoDriverInformation mongoDriverInformation) Create a new client with the given connection string.MongoClient
(MongoClientSettings settings) Create a new client with the given client settings.MongoClient
(MongoClientSettings settings, MongoDriverInformation mongoDriverInformation) Creates a new client with the given client settings.Creates an instance described by a URI.MongoClient
(MongoClientURI uri, MongoDriverInformation mongoDriverInformation) Creates an instance described by a URI.MongoClient
(ServerAddress addr) Creates an instance based on a (single) mongodb nodeMongoClient
(ServerAddress addr, MongoClientOptions options) Creates an instance based on a (single) mongo node using a given ServerAddress and default options.MongoClient
(ServerAddress addr, MongoCredential credential, MongoClientOptions options) Creates an instance based on a (single) mongo node using a given server address, credential, and optionsMongoClient
(ServerAddress addr, MongoCredential credential, MongoClientOptions options, MongoDriverInformation mongoDriverInformation) Creates a MongoClient to a single node using a given ServerAddress.MongoClient
(String connectionString) Creates a MongoClient instance based on a connection string.MongoClient
(String host, int port) Creates an instance based on a (single) mongodb node.MongoClient
(String host, MongoClientOptions options) Creates an instance based on a (single) mongodb node (default port).MongoClient
(List<ServerAddress> seeds) Creates an instance based on a list of replica set members or mongos servers.MongoClient
(List<ServerAddress> seeds, MongoClientOptions options) Construct an instance based on a list of replica set members or mongos servers.MongoClient
(List<ServerAddress> seeds, MongoCredential credential, MongoClientOptions options) Creates an instance based on a list of replica set members or mongos servers.MongoClient
(List<ServerAddress> seeds, MongoCredential credential, MongoClientOptions options, MongoDriverInformation mongoDriverInformation) Creates a MongoClient -
Method Summary
Modifier and TypeMethodDescriptionvoid
close()
Closes all resources associated with this instance, in particular any open network connections.void
dropDatabase
(String dbName) Drops the database if it exists.Gets the current cluster description.Gets the credential that this client authenticates all connections withgetDatabase
(String databaseName) Deprecated.static CodecRegistry
Gets the default codec registry.Gets the options that this client uses to connect to server.Gets the read concernGets the default read preferenceGets the write concernGet a list of the database nameslistDatabaseNames
(ClientSession clientSession) Get a list of the database namesGets the list of databaseslistDatabases
(ClientSession clientSession) Gets the list of databases<T> ListDatabasesIterable<T>
listDatabases
(ClientSession clientSession, Class<T> clazz) Gets the list of databases<T> ListDatabasesIterable<T>
listDatabases
(Class<T> clazz) Gets the list of databasesCreates a client session with default session options.startSession
(ClientSessionOptions options) Creates a client session.toString()
watch()
Creates a change stream for this client.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.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>
Creates a change stream for this client.Creates a change stream for this client.<TResult> ChangeStreamIterable<TResult>
Creates a change stream for this client.
-
Constructor Details
-
MongoClient
public MongoClient()Creates an instance based on a (single) MongoDB server ("mongodb://127.0.0.1:27017"
). -
MongoClient
Creates a MongoClient instance based on a connection string.- Parameters:
connectionString
- server to connect to in connection string format. For backwards compatibility, the"mongodb://"
prefix can be omitted- See Also:
-
MongoClient
Create a new client with the given connection string.For each of the settings classed configurable via
MongoClientSettings
, the connection string is applied by calling theapplyConnectionString
method on an instance of setting's builder class, building the setting, and adding it to an instance ofMongoClientSettings.Builder
.- Parameters:
connectionString
- the connection string- Since:
- 4.2
- See Also:
-
MongoClient
public MongoClient(ConnectionString connectionString, @Nullable MongoDriverInformation mongoDriverInformation) Create a new client with the given connection string.For each of the settings classed configurable via
MongoClientSettings
, the connection string is applied by calling theapplyConnectionString
method on an instance of setting's builder class, building the setting, and adding it to an instance ofMongoClientSettings.Builder
.Note: Intended for driver and library authors to associate extra driver metadata with the connections.
- Parameters:
connectionString
- the settingsmongoDriverInformation
- any driver information to associate with the MongoClient- Since:
- 4.2
-
MongoClient
Create a new client with the given client settings.- Parameters:
settings
- the settings- Since:
- 4.2
-
MongoClient
public MongoClient(MongoClientSettings settings, @Nullable MongoDriverInformation mongoDriverInformation) Creates a new client with the given client settings.Note: Intended for driver and library authors to associate extra driver metadata with the connections.
- Parameters:
settings
- the settingsmongoDriverInformation
- any driver information to associate with the MongoClient- Since:
- 4.2
-
MongoClient
Creates an instance based on a (single) mongodb node (default port).- Parameters:
host
- server to connect to in format host[:port]options
- default query options
-
MongoClient
Creates an instance based on a (single) mongodb node.- Parameters:
host
- the database's host addressport
- the port on which the database is running
-
MongoClient
Creates an instance based on a (single) mongodb node- Parameters:
addr
- the database address- See Also:
-
MongoClient
Creates an instance based on a (single) mongo node using a given ServerAddress and default options.- Parameters:
addr
- the database addressoptions
- default options- See Also:
-
MongoClient
public MongoClient(ServerAddress addr, @Nullable MongoCredential credential, MongoClientOptions options) Creates an instance based on a (single) mongo node using a given server address, credential, and options- Parameters:
addr
- the database addresscredential
- the credential used to authenticate all connectionsoptions
- default options- Since:
- 3.6
- See Also:
-
MongoClient
Creates an instance based on a list of replica set members or mongos servers. For a replica set it will discover all members. For a list with a single seed, the driver will still discover all members of the replica set. For a direct connection to a replica set member, with no discovery, use the
MongoClient(ServerAddress)
constructor instead.When there is more than one server to choose from based on the type of request (read or write) and the read preference (if it's a read request), the driver will randomly select a server to send a request. This applies to both replica sets and sharded clusters. The servers to randomly select from are further limited by the local threshold. See
MongoClientOptions.getLocalThreshold()
- Parameters:
seeds
- Put as many servers as you can in the list and the system will figure out the rest. This can either be a list of mongod servers in the same replica set or a list of mongos servers in the same sharded cluster.- See Also:
-
MongoClient
Construct an instance based on a list of replica set members or mongos servers. For a replica set it will discover all members. For a list with a single seed, the driver will still discover all members of the replica set. For a direct connection to a replica set member, with no discovery, use the
MongoClient(ServerAddress, MongoClientOptions)
constructor instead.When there is more than one server to choose from based on the type of request (read or write) and the read preference (if it's a read request), the driver will randomly select a server to send a request. This applies to both replica sets and sharded clusters. The servers to randomly select from are further limited by the local threshold. See
MongoClientOptions.getLocalThreshold()
- Parameters:
seeds
- Put as many servers as you can in the list and the system will figure out the rest. This can either be a list of mongod servers in the same replica set or a list of mongos servers in the same sharded cluster.options
- the options- See Also:
-
MongoClient
public MongoClient(List<ServerAddress> seeds, @Nullable MongoCredential credential, MongoClientOptions options) Creates an instance based on a list of replica set members or mongos servers. For a replica set it will discover all members. For a list with a single seed, the driver will still discover all members of the replica set. For a direct connection to a replica set member, with no discovery, use the
MongoClient(ServerAddress, MongoCredential, MongoClientOptions)
constructor instead.When there is more than one server to choose from based on the type of request (read or write) and the read preference (if it's a read request), the driver will randomly select a server to send a request. This applies to both replica sets and sharded clusters. The servers to randomly select from are further limited by the local threshold. See
MongoClientOptions.getLocalThreshold()
- Parameters:
seeds
- Put as many servers as you can in the list and the system will figure out the rest. This can either be a list of mongod servers in the same replica set or a list of mongos servers in the same sharded cluster.credential
- the credential used to authenticate all connectionsoptions
- the options- Since:
- 3.6
- See Also:
-
MongoClient
Creates an instance described by a URI. If only one address is used it will only connect to that node, otherwise it will discover all nodes.- Parameters:
uri
- the URI- Throws:
MongoException
- if theres a failure
-
MongoClient
Creates an instance described by a URI.Note: Intended for driver and library authors to associate extra driver metadata with the connections.
- Parameters:
uri
- the URImongoDriverInformation
- any driver information to associate with the MongoClient- Throws:
MongoException
- if theres a failure- Since:
- 3.4
-
MongoClient
public MongoClient(ServerAddress addr, @Nullable MongoCredential credential, MongoClientOptions options, @Nullable MongoDriverInformation mongoDriverInformation) Creates a MongoClient to a single node using a given ServerAddress.Note: Intended for driver and library authors to associate extra driver metadata with the connections.
- Parameters:
addr
- the database addresscredential
- the credential used to authenticate all connectionsoptions
- default optionsmongoDriverInformation
- any driver information to associate with the MongoClient- Since:
- 3.6
- See Also:
-
MongoClient
public MongoClient(List<ServerAddress> seeds, @Nullable MongoCredential credential, MongoClientOptions options, @Nullable MongoDriverInformation mongoDriverInformation) Creates a MongoClientNote: Intended for driver and library authors to associate extra driver metadata with the connections.
- Parameters:
seeds
- Put as many servers as you can in the list and the system will figure out the rest. This can either be a list of mongod servers in the same replica set or a list of mongos servers in the same sharded cluster.credential
- the credential used to authenticate all connectionsoptions
- the optionsmongoDriverInformation
- any driver information to associate with the MongoClient- Since:
- 3.6
-
-
Method Details
-
getDefaultCodecRegistry
Gets the default codec registry. It includes the following providers:- Returns:
- the default codec registry
- Since:
- 3.0
- See Also:
-
getMongoClientOptions
Gets the options that this client uses to connect to server.Note:
MongoClientOptions
is immutable.- Returns:
- the options
-
getCredential
Gets the credential that this client authenticates all connections with- Returns:
- the credential, which may be null in unsecured deployments
- Since:
- 3.9
-
listDatabaseNames
Get a list of the database names- Returns:
- an iterable containing all the names of all the databases
- Since:
- 3.0
- MongoDB documentation
- List Databases
-
listDatabaseNames
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
- Since:
- 3.6
- MongoDB documentation
- List Databases
- Since server release
- 3.6
-
listDatabases
Gets the list of databases- Returns:
- the list of databases
- Since:
- 3.0
-
listDatabases
Gets the list of databases- Type Parameters:
T
- the type of the class to use instead ofDocument
.- Parameters:
clazz
- the class to cast the database documents to- Returns:
- the list of databases
- Since:
- 3.0
-
listDatabases
Gets the list of databases- Parameters:
clientSession
- the client session with which to associate this operation- Returns:
- the list of databases
- Since:
- 3.6
- Since server release
- 3.6
-
listDatabases
Gets the list of databases- Type Parameters:
T
- the type of the class to use instead ofDocument
.- Parameters:
clientSession
- the client session with which to associate this operationclazz
- the class to cast the database documents to- Returns:
- the list of databases
- Since:
- 3.6
- Since server release
- 3.6
-
getDatabase
- Parameters:
databaseName
- the name of the database to retrieve- Returns:
- a
MongoDatabase
representing the specified database - Throws:
IllegalArgumentException
- if databaseName is invalid- See Also:
-
startSession
Creates a client session with default session options.- Returns:
- the client session
- Throws:
MongoClientException
- if the MongoDB cluster to which this client is connected does not support sessions- Since:
- 3.8
- Since server release
- 3.6
-
startSession
Creates a client session.- Parameters:
options
- the options for the client session- Returns:
- the client session
- Throws:
MongoClientException
- if the MongoDB cluster to which this client is connected does not support sessions- Since:
- 3.6
- Since server release
- 3.6
-
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
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
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
public <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 streamresultClass
- 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
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
public <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 operationresultClass
- 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
public 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 operationpipeline
- 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
public <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 operationpipeline
- the aggregation pipeline to apply to the change streamresultClass
- the class to decode each document into- Returns:
- the change stream iterable
- Since:
- 3.8
- MongoDB documentation
- Change Streams
- Since server release
- 4.0
-
getClusterDescription
Gets the current cluster description.This method will not block, meaning that it may return a
ClusterDescription
whoseclusterType
is unknown and whoseServerDescription
s are all in the connecting state. If the application requires notifications after the driver has connected to a member of the cluster, it should register aClusterListener
via theClusterSettings
inMongoClientSettings
.- Returns:
- the current cluster description
- Since:
- 4.2
- See Also:
-
getWriteConcern
Gets the write concern- Returns:
- the write concern
-
getReadConcern
Gets the read concern- Returns:
- the read concern
-
getReadPreference
Gets the default read preference- Returns:
- the default read preference
-
getDB
Deprecated.This method is not currently scheduled for removal, but prefergetDatabase(String)
for new code. Note thatDB
andMongoDatabase
can be used together in the same application, with the same instance.Gets a database object. Users should usegetDatabase(String)
instead.The
DB
class has been superseded byMongoDatabase
. The deprecation of this method effectively deprecates theDB
,DBCollection
, andDBCursor
classes, among others; but in order to give users time to migrate to the new API without experiencing a huge number of compiler warnings, those classes have not yet been formally deprecated.- Parameters:
dbName
- the name of the database to retrieve- Returns:
- a DB representing the specified database
- Throws:
IllegalArgumentException
- if the name is invalid- See Also:
-
dropDatabase
Drops the database if it exists.- Parameters:
dbName
- name of database to drop- Throws:
MongoException
- if the operation fails
-
close
public void close()Closes all resources associated with this instance, in particular any open network connections. Once called, this instance and any databases obtained from it can no longer be used.- Specified by:
close
in interfaceAutoCloseable
- Specified by:
close
in interfaceCloseable
-
toString
-
getDatabase(String)
for new code.