com.mongodb

Class MongoClient

java.lang.Object

com.mongodb.Mongo

com.mongodb.MongoClient

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable

public class MongoClient
extends Mongo
implements java.io.Closeable

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:

 MongoClient mongoClient1 = new MongoClient();
 MongoClient mongoClient1 = new MongoClient("localhost");
 MongoClient mongoClient2 = new MongoClient("localhost", 27017);
 MongoClient mongoClient4 = new MongoClient(new ServerAddress("localhost"));
 MongoClient mongoClient5 = new MongoClient(new ServerAddress("localhost"), MongoClientOptions.builder().build());
 

You can connect to a replica set using the Java driver by passing a ServerAddress list to the MongoClient constructor. For example:

 MongoClient mongoClient = new MongoClient(Arrays.asList(
   new ServerAddress("localhost", 27017),
   new ServerAddress("localhost", 27018),
   new ServerAddress("localhost", 27019)));
 

You can connect to a sharded cluster using the same constructor. 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:

 mongoClient.setReadPreference(ReadPreference.secondaryPreferred());
 

By default, all write operations will wait for acknowledgment by the server, as the default write concern is WriteConcern.ACKNOWLEDGED.

Note: This class supersedes the Mongo class. While it extends Mongo, it differs from it in that the default write concern is to wait for acknowledgment from the server of all write operations. In addition, its constructors accept instances of MongoClientOptions and MongoClientURI, which both also set the same default write concern.

In general, users of this class will pick up all of the default options specified in MongoClientOptions. In particular, note that the default value of the connectionsPerHost option has been increased to 100 from the old default value of 10 used by the superseded Mongo class.

Since:

2.10.0

See Also:

ReadPreference.primary(), WriteConcern.ACKNOWLEDGED, MongoClientOptions, MongoClientURI

Nested Class Summary

Nested classes/interfaces inherited from class com.mongodb.Mongo

Mongo.Holder

Constructor Summary

Constructors

Constructor and Description
MongoClient() Creates an instance based on a (single) mongodb node (localhost, default port).
MongoClient(java.util.List<ServerAddress> seeds) Creates an instance based on a list of replica set members or mongos servers.
MongoClient(java.util.List<ServerAddress> seeds, java.util.List<MongoCredential> credentialsList) Deprecated. Prefer MongoClient(List, MongoCredential, MongoClientOptions)
MongoClient(java.util.List<ServerAddress> seeds, java.util.List<MongoCredential> credentialsList, MongoClientOptions options) Deprecated. Prefer MongoClient(List, MongoCredential, MongoClientOptions)
MongoClient(java.util.List<ServerAddress> seeds, java.util.List<MongoCredential> credentialsList, MongoClientOptions options, MongoDriverInformation mongoDriverInformation) Deprecated. Prefer MongoClient(List, MongoCredential, MongoClientOptions, MongoDriverInformation)
MongoClient(java.util.List<ServerAddress> seeds, MongoClientOptions options) Construct an instance based on a list of replica set members or mongos servers.
MongoClient(java.util.List<ServerAddress> seeds, MongoCredential credential, MongoClientOptions options) Creates an instance based on a list of replica set members or mongos servers.
MongoClient(java.util.List<ServerAddress> seeds, MongoCredential credential, MongoClientOptions options, MongoDriverInformation mongoDriverInformation) Creates a MongoClient
MongoClient(MongoClientURI uri) Creates a Mongo described by a URI.
MongoClient(MongoClientURI uri, MongoDriverInformation mongoDriverInformation) Creates a Mongo described by a URI.
MongoClient(ServerAddress addr) Creates a Mongo instance based on a (single) mongodb node
MongoClient(ServerAddress addr, java.util.List<MongoCredential> credentialsList) Deprecated. Prefer MongoClient(ServerAddress, MongoCredential, MongoClientOptions)
MongoClient(ServerAddress addr, java.util.List<MongoCredential> credentialsList, MongoClientOptions options) Deprecated. Prefer MongoClient(ServerAddress, MongoCredential, MongoClientOptions)
MongoClient(ServerAddress addr, java.util.List<MongoCredential> credentialsList, MongoClientOptions options, MongoDriverInformation mongoDriverInformation) Deprecated. Prefer MongoClient(ServerAddress, MongoCredential, MongoClientOptions, MongoDriverInformation)
MongoClient(ServerAddress addr, MongoClientOptions options) Creates a Mongo instance based on a (single) mongo node using a given ServerAddress and default options.
MongoClient(ServerAddress addr, MongoCredential credential, MongoClientOptions options) Creates a Mongo instance based on a (single) mongo node using a given server address, credential, and options
MongoClient(ServerAddress addr, MongoCredential credential, MongoClientOptions options, MongoDriverInformation mongoDriverInformation) Creates a MongoClient to a single node using a given ServerAddress.
MongoClient(java.lang.String host) Creates a Mongo instance based on a (single) mongodb node.
MongoClient(java.lang.String host, int port) Creates a Mongo instance based on a (single) mongodb node.
MongoClient(java.lang.String host, MongoClientOptions options) Creates a Mongo instance based on a (single) mongodb node (default port).

Method Summary

Modifier and Type	Method and Description
java.util.List<MongoCredential>	getCredentialsList() Gets the list of credentials that this client authenticates all connections with
MongoDatabase	getDatabase(java.lang.String databaseName)
static CodecRegistry	getDefaultCodecRegistry() Gets the default codec registry.
MongoClientOptions	getMongoClientOptions() Gets the options that this client uses to connect to server.
MongoIterable<java.lang.String>	listDatabaseNames() Get a list of the database names
MongoIterable<java.lang.String>	listDatabaseNames(ClientSession clientSession) Get a list of the database names
ListDatabasesIterable<Document>	listDatabases() Gets the list of databases
<T> ListDatabasesIterable<T>	listDatabases(java.lang.Class<T> clazz) Gets the list of databases
ListDatabasesIterable<Document>	listDatabases(ClientSession clientSession) Gets the list of databases
<T> ListDatabasesIterable<T>	listDatabases(ClientSession clientSession, java.lang.Class<T> clazz) Gets the list of databases
ClientSession	startSession() Creates a client session with default session options.
ClientSession	startSession(ClientSessionOptions options) Creates a client session.
ChangeStreamIterable<Document>	watch() Creates a change stream for this client.
<TResult> ChangeStreamIterable<TResult>	watch(java.lang.Class<TResult> resultClass) 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, java.lang.Class<TResult> resultClass) Creates a change stream for this client.
ChangeStreamIterable<Document>	watch(ClientSession clientSession, java.util.List<? extends Bson> pipeline) Creates a change stream for this client.
<TResult> ChangeStreamIterable<TResult>	watch(ClientSession clientSession, java.util.List<? extends Bson> pipeline, java.lang.Class<TResult> resultClass) Creates a change stream for this client.
ChangeStreamIterable<Document>	watch(java.util.List<? extends Bson> pipeline) Creates a change stream for this client.
<TResult> ChangeStreamIterable<TResult>	watch(java.util.List<? extends Bson> pipeline, java.lang.Class<TResult> resultClass) Creates a change stream for this client.

Methods inherited from class com.mongodb.Mongo

addOption, close, dropDatabase, fsync, fsyncAndLock, getAddress, getAllAddress, getConnectPoint, getDatabaseNames, getDB, getMaxBsonObjectSize, getMongoOptions, getOptions, getReadConcern, getReadPreference, getReplicaSetStatus, getServerAddressList, getUsedDatabases, getWriteConcern, isLocked, resetOptions, setOptions, setReadPreference, setWriteConcern, slaveOk, toString, unlock

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.io.Closeable

close

Constructor Detail

MongoClient

public MongoClient()

Creates an instance based on a (single) mongodb node (localhost, default port).

MongoClient

public MongoClient(java.lang.String host)

Creates a Mongo instance based on a (single) mongodb node.

Parameters:

host - server to connect to in format host[:port]

MongoClient

public MongoClient(java.lang.String host,
                   MongoClientOptions options)

Creates a Mongo instance based on a (single) mongodb node (default port).

Parameters:

host - server to connect to in format host[:port]

options - default query options

MongoClient

public MongoClient(java.lang.String host,
                   int port)

Creates a Mongo instance based on a (single) mongodb node.

Parameters:

host - the database's host address

port - the port on which the database is running

MongoClient

public MongoClient(ServerAddress addr)

Creates a Mongo instance based on a (single) mongodb node

Parameters:

addr - the database address

See Also:

ServerAddress

MongoClient

@Deprecated
public MongoClient(ServerAddress addr,
                               java.util.List<MongoCredential> credentialsList)

Deprecated. Prefer MongoClient(ServerAddress, MongoCredential, MongoClientOptions)

Creates a Mongo instance based on a (single) mongodb node and a list of credentials

Parameters:

addr - the database address

credentialsList - the list of credentials used to authenticate all connections

Since:

2.11.0

See Also:

ServerAddress

MongoClient

public MongoClient(ServerAddress addr,
                   MongoClientOptions options)

Creates a Mongo instance based on a (single) mongo node using a given ServerAddress and default options.

Parameters:

addr - the database address

options - default options

See Also:

ServerAddress

MongoClient

@Deprecated
public MongoClient(ServerAddress addr,
                               java.util.List<MongoCredential> credentialsList,
                               MongoClientOptions options)

Deprecated. Prefer MongoClient(ServerAddress, MongoCredential, MongoClientOptions)

Creates a Mongo instance based on a (single) mongo node using a given ServerAddress and default options.

Parameters:

addr - the database address

credentialsList - the list of credentials used to authenticate all connections

options - default options

Since:

2.11.0

See Also:

ServerAddress

MongoClient

public MongoClient(ServerAddress addr,
                   MongoCredential credential,
                   MongoClientOptions options)

Creates a Mongo instance based on a (single) mongo node using a given server address, credential, and options

Parameters:

addr - the database address

credential - the credential used to authenticate all connections

options - default options

Since:

3.6.0

See Also:

ServerAddress

MongoClient

public MongoClient(java.util.List<ServerAddress> seeds)

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:

MongoClientOptions.getLocalThreshold()

MongoClient

@Deprecated
public MongoClient(java.util.List<ServerAddress> seeds,
                               java.util.List<MongoCredential> credentialsList)

Deprecated. Prefer MongoClient(List, MongoCredential, MongoClientOptions)

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, List) 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.

credentialsList - the list of credentials used to authenticate all connections

Since:

2.11.0

See Also:

MongoClientOptions.getLocalThreshold()

MongoClient

public MongoClient(java.util.List<ServerAddress> seeds,
                   MongoClientOptions options)

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:

MongoClientOptions.getLocalThreshold()

MongoClient

@Deprecated
public MongoClient(java.util.List<ServerAddress> seeds,
                               java.util.List<MongoCredential> credentialsList,
                               MongoClientOptions options)

Deprecated. Prefer MongoClient(List, MongoCredential, MongoClientOptions)

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, List, 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.

credentialsList - the list of credentials used to authenticate all connections

options - the options

Since:

2.11.0

See Also:

MongoClientOptions.getLocalThreshold()

MongoClient

public MongoClient(java.util.List<ServerAddress> seeds,
                   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, List, 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 connections

options - the options

Since:

3.6.0

See Also:

MongoClientOptions.getLocalThreshold()

MongoClient

public MongoClient(MongoClientURI uri)

Creates a Mongo 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

public MongoClient(MongoClientURI uri,
                   MongoDriverInformation mongoDriverInformation)

Creates a Mongo described by a URI.

Note: Intended for driver and library authors to associate extra driver metadata with the connections.

Parameters:

uri - the URI

mongoDriverInformation - any driver information to associate with the MongoClient

Throws:

MongoException - if theres a failure

Since:

3.4

MongoClient

@Deprecated
public MongoClient(ServerAddress addr,
                               java.util.List<MongoCredential> credentialsList,
                               MongoClientOptions options,
                               MongoDriverInformation mongoDriverInformation)

Deprecated. Prefer MongoClient(ServerAddress, MongoCredential, MongoClientOptions, 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 address

credentialsList - the list of credentials used to authenticate all connections

options - default options

mongoDriverInformation - any driver information to associate with the MongoClient

Since:

3.4

See Also:

ServerAddress

MongoClient

public MongoClient(ServerAddress addr,
                   MongoCredential credential,
                   MongoClientOptions options,
                   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 address

credential - the credential used to authenticate all connections

options - default options

mongoDriverInformation - any driver information to associate with the MongoClient

Since:

3.6

See Also:

ServerAddress

MongoClient

@Deprecated
public MongoClient(java.util.List<ServerAddress> seeds,
                               java.util.List<MongoCredential> credentialsList,
                               MongoClientOptions options,
                               MongoDriverInformation mongoDriverInformation)

Deprecated. Prefer MongoClient(List, MongoCredential, MongoClientOptions, MongoDriverInformation)

Creates a MongoClient

Note: 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.

credentialsList - the list of credentials used to authenticate all connections

options - the options

mongoDriverInformation - any driver information to associate with the MongoClient

Since:

3.4

MongoClient

public MongoClient(java.util.List<ServerAddress> seeds,
                   MongoCredential credential,
                   MongoClientOptions options,
                   MongoDriverInformation mongoDriverInformation)

Creates a MongoClient

Note: 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 connections

options - the options

mongoDriverInformation - any driver information to associate with the MongoClient

Since:

3.6

Method Detail

getDefaultCodecRegistry

public static CodecRegistry getDefaultCodecRegistry()

Gets the default codec registry. It includes the following providers:

• ValueCodecProvider
• BsonValueCodecProvider
• DBRefCodecProvider
• DBObjectCodecProvider
• DocumentCodecProvider
• IterableCodecProvider
• MapCodecProvider
• GeoJsonCodecProvider
• GridFSFileCodecProvider
• Jsr310CodecProvider

Returns:

the default codec registry

Since:

3.0

See Also:

MongoClientOptions.getCodecRegistry()

getMongoClientOptions

public MongoClientOptions getMongoClientOptions()

Gets the options that this client uses to connect to server.

Note: MongoClientOptions is immutable.

Returns:

the options

getCredentialsList

public java.util.List<MongoCredential> getCredentialsList()

Gets the list of credentials that this client authenticates all connections with

Returns:

the list of credentials

Since:

2.11.0

listDatabaseNames

public MongoIterable<java.lang.String> listDatabaseNames()

Get a list of the database names

Returns:

an iterable containing all the names of all the databases

Since:

3.0

listDatabaseNames

public MongoIterable<java.lang.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

Since:

3.6

listDatabases

public ListDatabasesIterable<Document> listDatabases()

Gets the list of databases

Returns:

the list of databases

Since:

3.0

listDatabases

public <T> ListDatabasesIterable<T> listDatabases(java.lang.Class<T> clazz)

Gets the list of databases

Type Parameters:

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

Parameters:

clazz - the class to cast the database documents to

Returns:

the list of databases

Since:

3.0

listDatabases

public ListDatabasesIterable<Document> listDatabases(ClientSession clientSession)

Gets the list of databases

Parameters:

clientSession - the client session with which to associate this operation

Returns:

the list of databases

Since:

3.6

listDatabases

public <T> ListDatabasesIterable<T> listDatabases(ClientSession clientSession,
                                                  java.lang.Class<T> clazz)

Gets the list of databases

Type Parameters:

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

Parameters:

clientSession - the client session with which to associate this operation

clazz - the class to cast the database documents to

Returns:

the list of databases

Since:

3.6

getDatabase

public MongoDatabase getDatabase(java.lang.String databaseName)

Parameters:

databaseName - the name of the database to retrieve

Returns:

a MongoDatabase representing the specified database

Throws:

java.lang.IllegalArgumentException - if databaseName is invalid

See Also:

MongoNamespace.checkDatabaseNameValidity(String)

startSession

public ClientSession 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

startSession

public ClientSession startSession(ClientSessionOptions options)

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

watch

public ChangeStreamIterable<Document> watch()

Creates a change stream for this client.

Returns:

the change stream iterable

Since:

3.8

watch

public <TResult> ChangeStreamIterable<TResult> watch(java.lang.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

watch

public ChangeStreamIterable<Document> watch(java.util.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

watch

public <TResult> ChangeStreamIterable<TResult> watch(java.util.List<? extends Bson> pipeline,
                                                     java.lang.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

watch

public 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

watch

public <TResult> ChangeStreamIterable<TResult> watch(ClientSession clientSession,
                                                     java.lang.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

watch

public ChangeStreamIterable<Document> watch(ClientSession clientSession,
                                            java.util.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

watch

public <TResult> ChangeStreamIterable<TResult> watch(ClientSession clientSession,
                                                     java.util.List<? extends Bson> pipeline,
                                                     java.lang.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