com.mongodb

Class MongoClient

java.lang.Object

com.mongodb.Mongo

com.mongodb.MongoClient

public class MongoClient
extends Mongo

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"), new 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

Field Summary

Fields inherited from class com.mongodb.Mongo

MAJOR_VERSION, MINOR_VERSION

Constructor Summary

Constructors

Constructor and Description
MongoClient() Creates an instance based on a (single) mongodb node (localhost, default port).
MongoClient(List<ServerAddress> seeds) Creates a Mongo based on a list of replica set members or a list of mongos.
MongoClient(List<ServerAddress> seeds, List<MongoCredential> credentialsList) Creates a Mongo based on a list of replica set members or a list of mongos.
MongoClient(List<ServerAddress> seeds, List<MongoCredential> credentialsList, MongoClientOptions options) Creates a Mongo based on a list of replica set members or a list of mongos.
MongoClient(List<ServerAddress> seeds, MongoClientOptions options) Creates a Mongo based on a list of replica set members or a list of mongos.
MongoClient(MongoClientURI uri) Creates a Mongo described by a URI.
MongoClient(ServerAddress addr) Creates a Mongo instance based on a (single) mongodb node
MongoClient(ServerAddress addr, List<MongoCredential> credentialsList) Creates a Mongo instance based on a (single) mongodb node and a list of credentials
MongoClient(ServerAddress addr, List<MongoCredential> credentialsList, MongoClientOptions options) Creates a Mongo instance based on a (single) mongo node using a given ServerAddress and default options.
MongoClient(ServerAddress addr, MongoClientOptions options) Creates a Mongo instance based on a (single) mongo node using a given ServerAddress and default options.
MongoClient(String host) Creates a Mongo instance based on a (single) mongodb node.
MongoClient(String host, int port) Creates a Mongo instance based on a (single) mongodb node.
MongoClient(String host, MongoClientOptions options) Creates a Mongo instance based on a (single) mongodb node (default port).

Method Summary

Methods

Modifier and Type	Method and Description
List<MongoCredential>	getCredentialsList() Gets the list of credentials that this client authenticates all connections with
MongoClientOptions	getMongoClientOptions()

Methods inherited from class com.mongodb.Mongo

addOption, close, connect, debugString, dropDatabase, fsync, fsyncAndLock, getAddress, getAllAddress, getConnector, getConnectPoint, getDatabaseNames, getDB, getMajorVersion, getMaxBsonObjectSize, getMinorVersion, getMongoOptions, getOptions, getReadPreference, getReplicaSetStatus, getServerAddressList, getUsedDatabases, getVersion, getWriteConcern, isLocked, resetOptions, setOptions, setReadPreference, setWriteConcern, slaveOk, toString, unlock

Methods inherited from class java.lang.Object

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

Constructor Detail

MongoClient

public MongoClient()
            throws UnknownHostException

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

Throws:

UnknownHostException

MongoException

MongoClient

public MongoClient(String host)
            throws UnknownHostException

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

Parameters:

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

Throws:

UnknownHostException - if the database host cannot be resolved

MongoException

MongoClient

public MongoClient(String host,
           MongoClientOptions options)
            throws UnknownHostException

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

Throws:

UnknownHostException - if the database host cannot be resolved

MongoException

MongoClient

public MongoClient(String host,
           int port)
            throws UnknownHostException

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

Throws:

UnknownHostException - if the database host cannot be resolved

MongoException

MongoClient

public MongoClient(ServerAddress addr)

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

Parameters:

addr - the database address

Throws:

MongoException

See Also:

ServerAddress

MongoClient

public MongoClient(ServerAddress addr,
           List<MongoCredential> credentialsList)

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

Throws:

MongoException

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

Throws:

MongoException

See Also:

ServerAddress

MongoClient

public MongoClient(ServerAddress addr,
           List<MongoCredential> credentialsList,
           MongoClientOptions options)

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

Throws:

MongoException

Since:

2.11.0

See Also:

ServerAddress

MongoClient

public MongoClient(List<ServerAddress> seeds)

Creates a Mongo based on a list of replica set members or a list of mongos. It will find all members (the master will be used by default). If you pass in a single server in the list, the driver will still function as if it is a replica set. If you have a standalone server, use the Mongo(ServerAddress) constructor.

If this is a list of mongos servers, it will pick the closest (lowest ping time) one to send all requests to, and automatically fail over to the next server if the closest is down.

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.

Throws:

MongoException

See Also:

ServerAddress

MongoClient

public MongoClient(List<ServerAddress> seeds,
           List<MongoCredential> credentialsList)

Creates a Mongo based on a list of replica set members or a list of mongos. It will find all members (the master will be used by default). If you pass in a single server in the list, the driver will still function as if it is a replica set. If you have a standalone server, use the Mongo(ServerAddress) constructor.

If this is a list of mongos servers, it will pick the closest (lowest ping time) one to send all requests to, and automatically fail over to the next server if the closest is down.

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

Throws:

MongoException

Since:

2.11.0

See Also:

ServerAddress

MongoClient

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

Creates a Mongo based on a list of replica set members or a list of mongos. It will find all members (the master will be used by default). If you pass in a single server in the list, the driver will still function as if it is a replica set. If you have a standalone server, use the Mongo(ServerAddress) constructor.

If this is a list of mongos servers, it will pick the closest (lowest ping time) one to send all requests to, and automatically fail over to the next server if the closest is down.

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 - default options

Throws:

MongoException

See Also:

ServerAddress

MongoClient

public MongoClient(List<ServerAddress> seeds,
           List<MongoCredential> credentialsList,
           MongoClientOptions options)

Creates a Mongo based on a list of replica set members or a list of mongos. It will find all members (the master will be used by default). If you pass in a single server in the list, the driver will still function as if it is a replica set. If you have a standalone server, use the Mongo(ServerAddress) constructor.

If this is a list of mongos servers, it will pick the closest (lowest ping time) one to send all requests to, and automatically fail over to the next server if the closest is down.

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 - default options

Throws:

MongoException

Since:

2.11.0

See Also:

ServerAddress

MongoClient

public MongoClient(MongoClientURI uri)
            throws UnknownHostException

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

UnknownHostException

See Also:

MongoURI

MongoDB documentation

connections

Method Detail

getCredentialsList

public List<MongoCredential> getCredentialsList()

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

Returns:

the list of credentials

Since:

2.11.0

getMongoClientOptions

public MongoClientOptions getMongoClientOptions()