Package com.mongodb

Class MongoClient

java.lang.Object
com.mongodb.MongoClient
All Implemented Interfaces:
Closeable, AutoCloseable
public class MongoClient extends Object implements 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:

 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 Details

    • MongoClient

      public MongoClient()
      Creates an instance based on a (single) MongoDB server ("mongodb://127.0.0.1:27017").

    • MongoClient

      public MongoClient(String connectionString)
      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

      public MongoClient(ConnectionString connectionString)
      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 the applyConnectionString method on an instance of setting's builder class, building the setting, and adding it to an instance of MongoClientSettings.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 the applyConnectionString method on an instance of setting's builder class, building the setting, and adding it to an instance of MongoClientSettings.Builder.

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

      Parameters:
      connectionString - the settings
      mongoDriverInformation - any driver information to associate with the MongoClient
      Since:
      4.2

    • MongoClient

      public MongoClient(MongoClientSettings settings)
      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 settings
      mongoDriverInformation - any driver information to associate with the MongoClient
      Since:
      4.2

    • MongoClient

      public MongoClient(String host, MongoClientOptions options)
      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

      public MongoClient(String host, int port)
      Creates an 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 an instance based on a (single) mongodb node
      Parameters:
      addr - the database address
      See Also:

    • MongoClient

      public MongoClient(ServerAddress addr, MongoClientOptions options)
      Creates an instance based on a (single) mongo node using a given ServerAddress and default options.
      Parameters:
      addr - the database address
      options - 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 address
      credential - the credential used to authenticate all connections
      options - default options
      Since:
      3.6
      See Also:

    • MongoClient

      public MongoClient(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:

    • MongoClient

      public MongoClient(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:

    • 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 connections
      options - the options
      Since:
      3.6
      See Also:

    • MongoClient

      public MongoClient(MongoClientURI uri)
      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

      public MongoClient(MongoClientURI uri, @Nullable MongoDriverInformation mongoDriverInformation)
      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 URI
      mongoDriverInformation - 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 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:

    • MongoClient

      public MongoClient(List<ServerAddress> seeds, @Nullable MongoCredential credential, MongoClientOptions options, @Nullable 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 Details

    • getDefaultCodecRegistry

      public static CodecRegistry getDefaultCodecRegistry()
      Gets the default codec registry. It includes the following providers:
      Returns:
      the default codec registry
      Since:
      3.0
      See Also:

    • getMongoClientOptions

      public MongoClientOptions getMongoClientOptions()
      Gets the options that this client uses to connect to server.

      Note: MongoClientOptions is immutable.

      Returns:
      the options

    • getCredential

      @Nullable public MongoCredential 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

      public MongoIterable<String> 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

      public 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
      Since:
      3.6
      MongoDB documentation
      List Databases
      Since server release
      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(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
      Since server release
      3.6

    • listDatabases

      public <T> ListDatabasesIterable<T> listDatabases(ClientSession clientSession, 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
      Since server release
      3.6

    • getDatabase

      public MongoDatabase getDatabase(String databaseName)
      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

      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
      Since server release
      3.6

    • 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
      Since server release
      3.6

    • watch

      public 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

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

      public 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

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

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

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

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

    • getClusterDescription

      public ClusterDescription getClusterDescription()
      Gets the current cluster description.

      This method will not block, meaning that it may return a ClusterDescription whose clusterType is unknown and whose ServerDescriptions 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 a ClusterListener via the ClusterSettings in MongoClientSettings.

      Returns:
      the current cluster description
      Since:
      4.2
      See Also:

    • getWriteConcern

      public WriteConcern getWriteConcern()
      Gets the write concern
      Returns:
      the write concern

    • getReadConcern

      public ReadConcern getReadConcern()
      Gets the read concern
      Returns:
      the read concern

    • getReadPreference

      public ReadPreference getReadPreference()
      Gets the default read preference
      Returns:
      the default read preference

    • getDB

      @Deprecated public DB getDB(String dbName)
      Deprecated.
      This method is not currently scheduled for removal, but prefer getDatabase(String) for new code. Note that DB and MongoDatabase can be used together in the same application, with the same instance.
      Gets a database object. Users should use getDatabase(String) instead.

      The DB class has been superseded by MongoDatabase. The deprecation of this method effectively deprecates the DB, DBCollection, and DBCursor 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

      public void dropDatabase(String dbName)
      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 interface AutoCloseable
      Specified by:
      close in interface Closeable

    • toString

      public String toString()
      Overrides:
      toString in class Object