com.mongodb.MongoClient Maven / Gradle / Ivy
Show all versions of mongo-java-driver Show documentation
/*
* Copyright 2008-present MongoDB, Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.mongodb;
import com.mongodb.client.ChangeStreamIterable;
import com.mongodb.client.ClientSession;
import com.mongodb.client.ListDatabasesIterable;
import com.mongodb.client.MongoDatabase;
import com.mongodb.client.MongoIterable;
import com.mongodb.client.internal.MongoDatabaseImpl;
import com.mongodb.client.internal.MongoIterables;
import com.mongodb.client.model.changestream.ChangeStreamLevel;
import com.mongodb.lang.Nullable;
import org.bson.BsonDocument;
import org.bson.Document;
import org.bson.codecs.configuration.CodecRegistry;
import org.bson.conversions.Bson;
import java.io.Closeable;
import java.util.Collections;
import java.util.List;
import static com.mongodb.assertions.Assertions.notNull;
import static com.mongodb.internal.connection.ServerAddressHelper.createServerAddress;
import static java.util.Collections.singletonList;
/**
* 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 {@code
* WriteConcern.ACKNOWLEDGED}.
*
* Note: This class supersedes the {@code Mongo} class. While it extends {@code 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 {@code
* MongoClientOptions} and {@code 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 {@code 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
* {@code Mongo} class.
*
* @see ReadPreference#primary()
* @see com.mongodb.WriteConcern#ACKNOWLEDGED
* @see MongoClientOptions
* @see MongoClientURI
* @since 2.10.0
*/
@SuppressWarnings("deprecation")
public class MongoClient extends Mongo implements Closeable {
/**
* Gets the default codec registry. It includes the following providers:
*
*
* - {@link org.bson.codecs.ValueCodecProvider}
* - {@link org.bson.codecs.BsonValueCodecProvider}
* - {@link com.mongodb.DBRefCodecProvider}
* - {@link com.mongodb.DBObjectCodecProvider}
* - {@link org.bson.codecs.DocumentCodecProvider}
* - {@link org.bson.codecs.IterableCodecProvider}
* - {@link org.bson.codecs.MapCodecProvider}
* - {@link com.mongodb.client.model.geojson.codecs.GeoJsonCodecProvider}
* - {@link com.mongodb.client.gridfs.codecs.GridFSFileCodecProvider}
* - {@link org.bson.codecs.jsr310.Jsr310CodecProvider}
*
*
* @return the default codec registry
* @see MongoClientOptions#getCodecRegistry()
* @since 3.0
*/
public static CodecRegistry getDefaultCodecRegistry() {
return com.mongodb.MongoClientSettings.getDefaultCodecRegistry();
}
/**
* Creates an instance based on a (single) mongodb node (localhost, default port).
*/
public MongoClient() {
this(new ServerAddress());
}
/**
* Creates a Mongo instance based on a (single) mongodb node.
*
* @param host server to connect to in format host[:port]
*/
public MongoClient(final String host) {
this(createServerAddress(host));
}
/**
* Creates a Mongo instance based on a (single) mongodb node (default port).
*
* @param host server to connect to in format host[:port]
* @param options default query options
*/
public MongoClient(final String host, final MongoClientOptions options) {
this(createServerAddress(host), options);
}
/**
* Creates a Mongo instance based on a (single) mongodb node.
*
* @param host the database's host address
* @param port the port on which the database is running
*/
public MongoClient(final String host, final int port) {
this(createServerAddress(host, port));
}
/**
* Creates a Mongo instance based on a (single) mongodb node
*
* @param addr the database address
* @see com.mongodb.ServerAddress
*/
public MongoClient(final ServerAddress addr) {
this(addr, new MongoClientOptions.Builder().build());
}
/**
* Creates a Mongo instance based on a (single) mongodb node and a list of credentials
*
* @param addr the database address
* @param credentialsList the list of credentials used to authenticate all connections
* @see com.mongodb.ServerAddress
* @since 2.11.0
* @deprecated Prefer {@link #MongoClient(ServerAddress, MongoCredential, MongoClientOptions)}
*/
@Deprecated
public MongoClient(final ServerAddress addr, final List credentialsList) {
this(addr, credentialsList, MongoClientOptions.builder().build());
}
/**
* Creates a Mongo instance based on a (single) mongo node using a given ServerAddress and default options.
*
* @param addr the database address
* @param options default options
* @see com.mongodb.ServerAddress
*/
public MongoClient(final ServerAddress addr, final MongoClientOptions options) {
super(addr, options);
}
/**
* Creates a Mongo instance based on a (single) mongo node using a given ServerAddress and default options.
*
* @param addr the database address
* @param credentialsList the list of credentials used to authenticate all connections
* @param options default options
* @see com.mongodb.ServerAddress
* @since 2.11.0
* @deprecated Prefer {@link #MongoClient(ServerAddress, MongoCredential, MongoClientOptions)}
*/
@Deprecated
public MongoClient(final ServerAddress addr, final List credentialsList, final MongoClientOptions options) {
super(addr, credentialsList, options);
}
/**
* Creates a Mongo instance based on a (single) mongo node using a given server address, credential, and options
*
* @param addr the database address
* @param credential the credential used to authenticate all connections
* @param options default options
* @see com.mongodb.ServerAddress
* @since 3.6.0
*/
public MongoClient(final ServerAddress addr, final MongoCredential credential, final MongoClientOptions options) {
super(addr, singletonList(credential), 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 {@link #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
* {@link MongoClientOptions#getLocalThreshold()}
*
* @param 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 MongoClientOptions#getLocalThreshold()
*/
public MongoClient(final List seeds) {
this(seeds, new MongoClientOptions.Builder().build());
}
/**
* 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 {@link #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
* {@link MongoClientOptions#getLocalThreshold()}
*
* @param 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.
* @param credentialsList the list of credentials used to authenticate all connections
* @see MongoClientOptions#getLocalThreshold()
* @since 2.11.0
* @deprecated Prefer {@link #MongoClient(List, MongoCredential, MongoClientOptions)}
*/
@Deprecated
public MongoClient(final List seeds, final List credentialsList) {
this(seeds, credentialsList, new MongoClientOptions.Builder().build());
}
/**
* 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 {@link #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
* {@link MongoClientOptions#getLocalThreshold()}
*
* @param 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.
* @param options the options
* @see MongoClientOptions#getLocalThreshold()
*/
public MongoClient(final List seeds, final MongoClientOptions options) {
super(seeds, 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 {@link #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
* {@link MongoClientOptions#getLocalThreshold()}
*
* @param 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.
* @param credentialsList the list of credentials used to authenticate all connections
* @param options the options
* @see MongoClientOptions#getLocalThreshold()
* @since 2.11.0
* @deprecated Prefer {@link #MongoClient(List, MongoCredential, MongoClientOptions)}
*/
@Deprecated
public MongoClient(final List seeds, final List credentialsList, final MongoClientOptions options) {
super(seeds, credentialsList, 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 {@link #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
* {@link MongoClientOptions#getLocalThreshold()}
*
* @param 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.
* @param credential the credential used to authenticate all connections
* @param options the options
* @see MongoClientOptions#getLocalThreshold()
* @since 3.6.0
*/
public MongoClient(final List seeds, final MongoCredential credential, final MongoClientOptions options) {
super(seeds, singletonList(credential), options);
}
/**
* 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.
*
* @param uri the URI
* @throws MongoException if theres a failure
*/
public MongoClient(final MongoClientURI uri) {
super(uri);
}
/**
* Creates a Mongo described by a URI.
*
* Note: Intended for driver and library authors to associate extra driver metadata with the connections.
*
* @param uri the URI
* @param mongoDriverInformation any driver information to associate with the MongoClient
* @throws MongoException if theres a failure
* @since 3.4
*/
public MongoClient(final MongoClientURI uri, final MongoDriverInformation mongoDriverInformation) {
super(uri, 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.
*
* @param addr the database address
* @param credentialsList the list of credentials used to authenticate all connections
* @param options default options
* @param mongoDriverInformation any driver information to associate with the MongoClient
* @see com.mongodb.ServerAddress
* @since 3.4
* @deprecated Prefer {@link #MongoClient(ServerAddress, MongoCredential, MongoClientOptions, MongoDriverInformation)}
*/
@Deprecated
public MongoClient(final ServerAddress addr, final List credentialsList, final MongoClientOptions options,
final MongoDriverInformation mongoDriverInformation) {
super(addr, credentialsList, options, 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.
*
* @param addr the database address
* @param credential the credential used to authenticate all connections
* @param options default options
* @param mongoDriverInformation any driver information to associate with the MongoClient
* @see com.mongodb.ServerAddress
* @since 3.6
*/
public MongoClient(final ServerAddress addr, final MongoCredential credential, final MongoClientOptions options,
final MongoDriverInformation mongoDriverInformation) {
super(addr, singletonList(credential), options, mongoDriverInformation);
}
/**
* Creates a MongoClient
*
* Note: Intended for driver and library authors to associate extra driver metadata with the connections.
*
* @param 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.
* @param credentialsList the list of credentials used to authenticate all connections
* @param options the options
* @param mongoDriverInformation any driver information to associate with the MongoClient
* @since 3.4
* @deprecated Prefer {@link #MongoClient(List, MongoCredential, MongoClientOptions, MongoDriverInformation)}
*/
@Deprecated
public MongoClient(final List seeds, final List credentialsList, final MongoClientOptions options,
final MongoDriverInformation mongoDriverInformation) {
super(seeds, credentialsList, options, mongoDriverInformation);
}
/**
* Creates a MongoClient
*
* Note: Intended for driver and library authors to associate extra driver metadata with the connections.
*
* @param 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.
* @param credential the credential used to authenticate all connections
* @param options the options
* @param mongoDriverInformation any driver information to associate with the MongoClient
* @since 3.6
*/
public MongoClient(final List seeds, final MongoCredential credential, final MongoClientOptions options,
final MongoDriverInformation mongoDriverInformation) {
super(seeds, singletonList(credential), options, mongoDriverInformation);
}
/**
* Gets the options that this client uses to connect to server.
*
* Note: {@link MongoClientOptions} is immutable.
*
* @return the options
*/
public MongoClientOptions getMongoClientOptions() {
return super.getMongoClientOptions();
}
/**
* Gets the credential that this client authenticates all connections with
*
* @return the credential, which may be null in unsecured deployments
* @since 3.9
*/
@Nullable
public MongoCredential getCredential() {
if (getCredentialsList().size() > 1) {
throw new IllegalStateException("Instance constructed with more than one MongoCredential");
} else if (getCredentialsList().isEmpty()) {
return null;
} else {
return getCredentialsList().get(0);
}
}
/**
* Gets the list of credentials that this client authenticates all connections with
*
* @return the list of credentials
* @since 2.11.0
* @deprecated Prefer {@link #getCredential()}
*/
@Deprecated
public List getCredentialsList() {
return super.getCredentialsList();
}
/**
* Get a list of the database names
*
* @mongodb.driver.manual reference/command/listDatabases List Databases
* @return an iterable containing all the names of all the databases
* @since 3.0
*/
public MongoIterable listDatabaseNames() {
return createListDatabaseNamesIterable(null);
}
/**
* Get a list of the database names
*
* @param clientSession the client session with which to associate this operation
* @return an iterable containing all the names of all the databases
* @since 3.6
* @mongodb.server.release 3.6
* @mongodb.driver.manual reference/command/listDatabases List Databases
*/
public MongoIterable listDatabaseNames(final ClientSession clientSession) {
notNull("clientSession", clientSession);
return createListDatabaseNamesIterable(clientSession);
}
private MongoIterable createListDatabaseNamesIterable(@Nullable final ClientSession clientSession) {
return createListDatabasesIterable(clientSession, BsonDocument.class).nameOnly(true).map(new Function() {
@Override
public String apply(final BsonDocument result) {
return result.getString("name").getValue();
}
});
}
/**
* Gets the list of databases
*
* @return the list of databases
* @since 3.0
*/
public ListDatabasesIterable listDatabases() {
return listDatabases(Document.class);
}
/**
* Gets the list of databases
*
* @param clazz the class to cast the database documents to
* @param the type of the class to use instead of {@code Document}.
* @return the list of databases
* @since 3.0
*/
public ListDatabasesIterable listDatabases(final Class clazz) {
return createListDatabasesIterable(null, clazz);
}
/**
* Gets the list of databases
*
* @param clientSession the client session with which to associate this operation
* @return the list of databases
* @since 3.6
* @mongodb.server.release 3.6
*/
public ListDatabasesIterable listDatabases(final ClientSession clientSession) {
return listDatabases(clientSession, Document.class);
}
/**
* Gets the list of databases
*
* @param clientSession the client session with which to associate this operation
* @param clazz the class to cast the database documents to
* @param the type of the class to use instead of {@code Document}.
* @return the list of databases
* @since 3.6
* @mongodb.server.release 3.6
*/
public ListDatabasesIterable listDatabases(final ClientSession clientSession, final Class clazz) {
notNull("clientSession", clientSession);
return createListDatabasesIterable(clientSession, clazz);
}
private ListDatabasesIterable createListDatabasesIterable(@Nullable final ClientSession clientSession, final Class clazz) {
return MongoIterables.listDatabasesOf(clientSession, clazz, getMongoClientOptions().getCodecRegistry(),
ReadPreference.primary(), createOperationExecutor());
}
/**
* @param databaseName the name of the database to retrieve
* @return a {@code MongoDatabase} representing the specified database
* @throws IllegalArgumentException if databaseName is invalid
* @see MongoNamespace#checkDatabaseNameValidity(String)
*/
public MongoDatabase getDatabase(final String databaseName) {
MongoClientOptions clientOptions = getMongoClientOptions();
return new MongoDatabaseImpl(databaseName, clientOptions.getCodecRegistry(), clientOptions.getReadPreference(),
clientOptions.getWriteConcern(), clientOptions.getRetryWrites(), clientOptions.getReadConcern(), createOperationExecutor());
}
/**
* Creates a client session with default session options.
*
* @return the client session
* @throws MongoClientException if the MongoDB cluster to which this client is connected does not support sessions
* @mongodb.server.release 3.6
* @since 3.8
*/
public ClientSession startSession() {
return startSession(ClientSessionOptions.builder().build());
}
/**
* Creates a client session.
*
* @param options the options for the client session
* @return the client session
* @throws MongoClientException if the MongoDB cluster to which this client is connected does not support sessions
* @mongodb.server.release 3.6
* @since 3.6
*/
public ClientSession startSession(final ClientSessionOptions options) {
ClientSession clientSession = createClientSession(notNull("options", options));
if (clientSession == null) {
throw new MongoClientException("Sessions are not supported by the MongoDB cluster to which this client is connected");
}
return clientSession;
}
/**
* Creates a change stream for this client.
*
* @return the change stream iterable
* @since 3.8
* @mongodb.server.release 4.0
* @mongodb.driver.dochub core/changestreams Change Streams
*/
public ChangeStreamIterable watch() {
return watch(Collections.emptyList());
}
/**
* Creates a change stream for this client.
*
* @param resultClass the class to decode each document into
* @param the target document type of the iterable.
* @return the change stream iterable
* @since 3.8
* @mongodb.server.release 4.0
* @mongodb.driver.dochub core/changestreams Change Streams
*/
public ChangeStreamIterable watch(final Class resultClass) {
return watch(Collections.emptyList(), resultClass);
}
/**
* Creates a change stream for this client.
*
* @param pipeline the aggregation pipeline to apply to the change stream
* @return the change stream iterable
* @since 3.8
* @mongodb.server.release 4.0
* @mongodb.driver.dochub core/changestreams Change Streams
*/
public ChangeStreamIterable watch(final List pipeline) {
return watch(pipeline, Document.class);
}
/**
* Creates a change stream for this client.
*
* @param pipeline the aggregation pipeline to apply to the change stream
* @param resultClass the class to decode each document into
* @param the target document type of the iterable.
* @return the change stream iterable
* @since 3.8
* @mongodb.server.release 4.0
* @mongodb.driver.dochub core/changestreams Change Streams
*/
public ChangeStreamIterable watch(final List pipeline, final Class resultClass) {
return createChangeStreamIterable(null, pipeline, resultClass);
}
/**
* Creates a change stream for this client.
*
* @param clientSession the client session with which to associate this operation
* @return the change stream iterable
* @since 3.8
* @mongodb.server.release 4.0
* @mongodb.driver.dochub core/changestreams Change Streams
*/
public ChangeStreamIterable watch(final ClientSession clientSession) {
return watch(clientSession, Collections.emptyList(), Document.class);
}
/**
* Creates a change stream for this client.
*
* @param clientSession the client session with which to associate this operation
* @param resultClass the class to decode each document into
* @param the target document type of the iterable.
* @return the change stream iterable
* @since 3.8
* @mongodb.server.release 4.0
* @mongodb.driver.dochub core/changestreams Change Streams
*/
public ChangeStreamIterable watch(final ClientSession clientSession, final Class resultClass) {
return watch(clientSession, Collections.emptyList(), resultClass);
}
/**
* Creates a change stream for this client.
*
* @param clientSession the client session with which to associate this operation
* @param pipeline the aggregation pipeline to apply to the change stream
* @return the change stream iterable
* @since 3.8
* @mongodb.server.release 4.0
* @mongodb.driver.dochub core/changestreams Change Streams
*/
public ChangeStreamIterable watch(final ClientSession clientSession, final List pipeline) {
return watch(clientSession, pipeline, Document.class);
}
/**
* Creates a change stream for this client.
*
* @param clientSession the client session with which to associate this operation
* @param pipeline the aggregation pipeline to apply to the change stream
* @param resultClass the class to decode each document into
* @param the target document type of the iterable.
* @return the change stream iterable
* @since 3.8
* @mongodb.server.release 4.0
* @mongodb.driver.dochub core/changestreams Change Streams
*/
public ChangeStreamIterable watch(final ClientSession clientSession, final List pipeline,
final Class resultClass) {
notNull("clientSession", clientSession);
return createChangeStreamIterable(clientSession, pipeline, resultClass);
}
/**
* 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.
*/
public void close() {
super.close();
}
private ChangeStreamIterable createChangeStreamIterable(@Nullable final ClientSession clientSession,
final List pipeline,
final Class resultClass) {
MongoClientOptions clientOptions = getMongoClientOptions();
return MongoIterables.changeStreamOf(clientSession, "admin",
clientOptions.getCodecRegistry(), clientOptions.getReadPreference(), clientOptions.getReadConcern(),
createOperationExecutor(), pipeline, resultClass, ChangeStreamLevel.CLIENT);
}
static DBObjectCodec getCommandCodec() {
return new DBObjectCodec(getDefaultCodecRegistry());
}
}