Package com.mongodb

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

     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.

    Since:
    2.10.0
    See Also:
    ReadPreference.primary(), WriteConcern.ACKNOWLEDGED, MongoClientOptions, MongoClientURI

    • Constructor Summary

      Constructors 
      Constructor Description
      MongoClient()
      Creates an instance based on a (single) mongodb node (localhost, default port).
      MongoClient​(MongoClientURI uri)
      Creates an instance described by a URI.
      MongoClient​(MongoClientURI uri, com.mongodb.MongoDriverInformation mongoDriverInformation)
      Creates an instance described by a URI.
      MongoClient​(com.mongodb.ServerAddress addr)
      Creates an instance based on a (single) mongodb node
      MongoClient​(com.mongodb.ServerAddress addr, MongoClientOptions options)
      Creates an instance based on a (single) mongo node using a given ServerAddress and default options.
      MongoClient​(com.mongodb.ServerAddress addr, com.mongodb.MongoCredential credential, MongoClientOptions options)
      Creates an instance based on a (single) mongo node using a given server address, credential, and options
      MongoClient​(com.mongodb.ServerAddress addr, com.mongodb.MongoCredential credential, MongoClientOptions options, com.mongodb.MongoDriverInformation mongoDriverInformation)
      Creates a MongoClient to a single node using a given ServerAddress.
      MongoClient​(String host)
      Creates a MongoClient instance based on a (single) mongodb node.
      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<com.mongodb.ServerAddress> seeds)
      Creates an instance based on a list of replica set members or mongos servers.
      MongoClient​(List<com.mongodb.ServerAddress> seeds, MongoClientOptions options)
      Construct an instance based on a list of replica set members or mongos servers.
      MongoClient​(List<com.mongodb.ServerAddress> seeds, com.mongodb.MongoCredential credential, MongoClientOptions options)
      Creates an instance based on a list of replica set members or mongos servers.
      MongoClient​(List<com.mongodb.ServerAddress> seeds, com.mongodb.MongoCredential credential, MongoClientOptions options, com.mongodb.MongoDriverInformation mongoDriverInformation)
      Creates a MongoClient

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      void close()
      Closes all resources associated with this instance, in particular any open network connections.
      void dropDatabase​(String dbName)
      Drops the database if it exists.
      com.mongodb.MongoCredential getCredential()
      Gets the credential that this client authenticates all connections with
      com.mongodb.client.MongoDatabase getDatabase​(String databaseName)  
      DB getDB​(String dbName)
      Deprecated.
      This method is not currently scheduled for removal, but prefer getDatabase(String) for new code.
      static org.bson.codecs.configuration.CodecRegistry getDefaultCodecRegistry()
      Gets the default codec registry.
      MongoClientOptions getMongoClientOptions()
      Gets the options that this client uses to connect to server.
      com.mongodb.ReadConcern getReadConcern()
      Gets the read concern
      com.mongodb.ReadPreference getReadPreference()
      Gets the default read preference
      com.mongodb.WriteConcern getWriteConcern()
      Gets the write concern
      com.mongodb.client.MongoIterable<String> listDatabaseNames()
      Get a list of the database names
      com.mongodb.client.MongoIterable<String> listDatabaseNames​(com.mongodb.client.ClientSession clientSession)
      Get a list of the database names
      com.mongodb.client.ListDatabasesIterable<org.bson.Document> listDatabases()
      Gets the list of databases
      com.mongodb.client.ListDatabasesIterable<org.bson.Document> listDatabases​(com.mongodb.client.ClientSession clientSession)
      Gets the list of databases
      <T> com.mongodb.client.ListDatabasesIterable<T> listDatabases​(com.mongodb.client.ClientSession clientSession, Class<T> clazz)
      Gets the list of databases
      <T> com.mongodb.client.ListDatabasesIterable<T> listDatabases​(Class<T> clazz)
      Gets the list of databases
      com.mongodb.client.ClientSession startSession()
      Creates a client session with default session options.
      com.mongodb.client.ClientSession startSession​(com.mongodb.ClientSessionOptions options)
      Creates a client session.
      String toString()  
      com.mongodb.client.ChangeStreamIterable<org.bson.Document> watch()
      Creates a change stream for this client.
      com.mongodb.client.ChangeStreamIterable<org.bson.Document> watch​(com.mongodb.client.ClientSession clientSession)
      Creates a change stream for this client.
      <TResult> com.mongodb.client.ChangeStreamIterable<TResult> watch​(com.mongodb.client.ClientSession clientSession, Class<TResult> resultClass)
      Creates a change stream for this client.
      com.mongodb.client.ChangeStreamIterable<org.bson.Document> watch​(com.mongodb.client.ClientSession clientSession, List<? extends org.bson.conversions.Bson> pipeline)
      Creates a change stream for this client.
      <TResult> com.mongodb.client.ChangeStreamIterable<TResult> watch​(com.mongodb.client.ClientSession clientSession, List<? extends org.bson.conversions.Bson> pipeline, Class<TResult> resultClass)
      Creates a change stream for this client.
      <TResult> com.mongodb.client.ChangeStreamIterable<TResult> watch​(Class<TResult> resultClass)
      Creates a change stream for this client.
      com.mongodb.client.ChangeStreamIterable<org.bson.Document> watch​(List<? extends org.bson.conversions.Bson> pipeline)
      Creates a change stream for this client.
      <TResult> com.mongodb.client.ChangeStreamIterable<TResult> watch​(List<? extends org.bson.conversions.Bson> pipeline, Class<TResult> resultClass)
      Creates a change stream for this client.

    • Constructor Detail

      • MongoClient

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

      • MongoClient

        public MongoClient​(String host)
        Creates a MongoClient instance based on a (single) mongodb node.
        Parameters:
        host - server to connect to in format host[:port]

      • 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​(com.mongodb.ServerAddress addr)
        Creates an instance based on a (single) mongodb node
        Parameters:
        addr - the database address
        See Also:
        ServerAddress

      • MongoClient

        public MongoClient​(com.mongodb.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:
        ServerAddress

      • MongoClient

        public MongoClient​(com.mongodb.ServerAddress addr,
                   com.mongodb.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.0
        See Also:
        ServerAddress

      • MongoClient

        public MongoClient​(List<com.mongodb.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

        public MongoClient​(List<com.mongodb.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

        public MongoClient​(List<com.mongodb.ServerAddress> seeds,
                   com.mongodb.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.0
        See Also:
        MongoClientOptions.getLocalThreshold()

      • 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:
        com.mongodb.MongoException - if theres a failure

      • MongoClient

        public MongoClient​(MongoClientURI uri,
                   com.mongodb.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:
        com.mongodb.MongoException - if theres a failure
        Since:
        3.4

      • MongoClient

        public MongoClient​(com.mongodb.ServerAddress addr,
                   com.mongodb.MongoCredential credential,
                   MongoClientOptions options,
                   com.mongodb.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

        public MongoClient​(List<com.mongodb.ServerAddress> seeds,
                   com.mongodb.MongoCredential credential,
                   MongoClientOptions options,
                   com.mongodb.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 org.bson.codecs.configuration.CodecRegistry getDefaultCodecRegistry()
        Gets the default codec registry. It includes the following providers:
        • ValueCodecProvider
        • BsonValueCodecProvider
        • DBRefCodecProvider
        • DBObjectCodecProvider
        • DocumentCodecProvider
        • IterableCodecProvider
        • MapCodecProvider
        • GeoJsonCodecProvider
        • GridFSFileCodecProvider
        • Jsr310CodecProvider
        • BsonCodecProvider
        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

      • getCredential

        @Nullable
public com.mongodb.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 com.mongodb.client.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 com.mongodb.client.MongoIterable<String> listDatabaseNames​(com.mongodb.client.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 com.mongodb.client.ListDatabasesIterable<org.bson.Document> listDatabases()
        Gets the list of databases
        Returns:
        the list of databases
        Since:
        3.0

      • listDatabases

        public <T> com.mongodb.client.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 com.mongodb.client.ListDatabasesIterable<org.bson.Document> listDatabases​(com.mongodb.client.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> com.mongodb.client.ListDatabasesIterable<T> listDatabases​(com.mongodb.client.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 com.mongodb.client.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:
        MongoNamespace.checkDatabaseNameValidity(String)

      • startSession

        public com.mongodb.client.ClientSession startSession()
        Creates a client session with default session options.
        Returns:
        the client session
        Throws:
        com.mongodb.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 com.mongodb.client.ClientSession startSession​(com.mongodb.ClientSessionOptions options)
        Creates a client session.
        Parameters:
        options - the options for the client session
        Returns:
        the client session
        Throws:
        com.mongodb.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 com.mongodb.client.ChangeStreamIterable<org.bson.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> com.mongodb.client.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 com.mongodb.client.ChangeStreamIterable<org.bson.Document> watch​(List<? extends org.bson.conversions.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> com.mongodb.client.ChangeStreamIterable<TResult> watch​(List<? extends org.bson.conversions.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 com.mongodb.client.ChangeStreamIterable<org.bson.Document> watch​(com.mongodb.client.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> com.mongodb.client.ChangeStreamIterable<TResult> watch​(com.mongodb.client.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 com.mongodb.client.ChangeStreamIterable<org.bson.Document> watch​(com.mongodb.client.ClientSession clientSession,
                                                                        List<? extends org.bson.conversions.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> com.mongodb.client.ChangeStreamIterable<TResult> watch​(com.mongodb.client.ClientSession clientSession,
                                                                        List<? extends org.bson.conversions.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

      • getWriteConcern

        public com.mongodb.WriteConcern getWriteConcern()
        Gets the write concern
        Returns:
        the write concern

      • getReadConcern

        public com.mongodb.ReadConcern getReadConcern()
        Gets the read concern
        Returns:
        the read concern

      • getReadPreference

        public com.mongodb.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:
        MongoNamespace.checkDatabaseNameValidity(String)

      • dropDatabase

        public void dropDatabase​(String dbName)
        Drops the database if it exists.
        Parameters:
        dbName - name of database to drop
        Throws:
        com.mongodb.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