/*
 * 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.client;

import com.mongodb.ClientSessionOptions;
import com.mongodb.MongoNamespace;
import com.mongodb.annotations.Immutable;
import com.mongodb.connection.ClusterDescription;
import com.mongodb.connection.ClusterSettings;
import com.mongodb.event.ClusterListener;
import org.bson.Document;
import org.bson.conversions.Bson;

import java.io.Closeable;
import java.util.List;

A client-side representation of a MongoDB cluster.  Instances can represent either a standalone MongoDB instance, a replica set,
or a sharded cluster.  Instance of this class are responsible for maintaining an up-to-date state of the cluster,
and possibly cache resources related to this, including background threads for monitoring, and connection pools.
 Instances of this class serve as factories for MongoDatabase instances. 
 Instances of this class can be created via the MongoClients factory. 
See Also:
MongoClients
Since:
3.7/**
 * A client-side representation of a MongoDB cluster.  Instances can represent either a standalone MongoDB instance, a replica set,
 * or a sharded cluster.  Instance of this class are responsible for maintaining an up-to-date state of the cluster,
 * and possibly cache resources related to this, including background threads for monitoring, and connection pools.
 * <p>
 * Instances of this class serve as factories for {@link MongoDatabase} instances.
 * </p>
 * <p>
 * Instances of this class can be created via the {@link MongoClients} factory.
 * </p>
 * @see MongoClients
 * @since 3.7
 */
@Immutable
public interface MongoClient extends Closeable {

    
Gets a MongoDatabase instance for the given database name. 
Params:
databaseName – the name of the database to retrieve
Throws:
IllegalArgumentException – if databaseName is invalid
See Also:
MongoNamespace.checkDatabaseNameValidity(String)
Returns:
a MongoDatabase representing the specified database/**
     * Gets a {@link MongoDatabase} instance for the given database name.
     *
     * @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)
     */
    MongoDatabase getDatabase(String databaseName);

    
Creates a client session with default options.
Note: A ClientSession instance can not be used concurrently in multiple operations.
Returns:
the client session
@mongodb.server.release
3.6/**
     * Creates a client session with default options.
     *
     * <p>Note: A ClientSession instance can not be used concurrently in multiple operations.</p>
     *
     * @return the client session
     * @mongodb.server.release 3.6
     */
    ClientSession startSession();

    
Creates a client session.
Note: A ClientSession instance can not be used concurrently in multiple operations.
Params:
options –  the options for the client session
Returns:
the client session
@mongodb.server.release
3.6/**
     * Creates a client session.
     *
     * <p>Note: A ClientSession instance can not be used concurrently in multiple operations.</p>
     *
     * @param options  the options for the client session
     * @return the client session
     * @mongodb.server.release 3.6
     */
    ClientSession startSession(ClientSessionOptions options);

    
Close the client, which will close all underlying cached resources, including, for example,
sockets and background monitoring threads.
/**
     * Close the client, which will close all underlying cached resources, including, for example,
     * sockets and background monitoring threads.
     */
    void close();

    
Get a list of the database names
Returns:
an iterable containing all the names of all the databases
@mongodb.driver.manual
reference/command/listDatabases List Databases/**
     * Get a list of the database names
     *
     * @return an iterable containing all the names of all the databases
     * @mongodb.driver.manual reference/command/listDatabases List Databases
     */
    MongoIterable<String> listDatabaseNames();

    
Get a list of the database names
Params:
clientSession – the client session with which to associate this operation
Returns:
an iterable containing all the names of all the databases
@mongodb.driver.manual
reference/command/listDatabases List Databases
@mongodb.server.release
3.6/**
     * 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
     * @mongodb.driver.manual reference/command/listDatabases List Databases
     * @mongodb.server.release 3.6
     */
    MongoIterable<String> listDatabaseNames(ClientSession clientSession);

    
Gets the list of databases
Returns:
the list databases iterable interface/**
     * Gets the list of databases
     *
     * @return the list databases iterable interface
     */
    ListDatabasesIterable<Document> listDatabases();

    
Gets the list of databases
Params:
clientSession – the client session with which to associate this operation
Returns:
the list databases iterable interface
@mongodb.driver.manual
reference/command/listDatabases List Databases
@mongodb.server.release
3.6/**
     * Gets the list of databases
     *
     * @param clientSession the client session with which to associate this operation
     * @return the list databases iterable interface
     * @mongodb.driver.manual reference/command/listDatabases List Databases
     * @mongodb.server.release 3.6
     */
    ListDatabasesIterable<Document> listDatabases(ClientSession clientSession);

    
Gets the list of databases
Params:
resultClass – the class to cast the database documents to
Type parameters:
<TResult> –  the type of the class to use instead of Document.
Returns:
the list databases iterable interface/**
     * Gets the list of databases
     *
     * @param resultClass the class to cast the database documents to
     * @param <TResult>   the type of the class to use instead of {@code Document}.
     * @return the list databases iterable interface
     */
    <TResult> ListDatabasesIterable<TResult> listDatabases(Class<TResult> resultClass);

    
Gets the list of databases
Params:
clientSession – the client session with which to associate this operation
resultClass – the class to cast the database documents to
Type parameters:
<TResult> –  the type of the class to use instead of Document.
Returns:
the list databases iterable interface
@mongodb.driver.manual
reference/command/listDatabases List Databases
@mongodb.server.release
3.6/**
     * Gets the list of databases
     *
     * @param clientSession the client session with which to associate this operation
     * @param resultClass the class to cast the database documents to
     * @param <TResult>   the type of the class to use instead of {@code Document}.
     * @return the list databases iterable interface
     * @mongodb.driver.manual reference/command/listDatabases List Databases
     * @mongodb.server.release 3.6
     */
    <TResult> ListDatabasesIterable<TResult> listDatabases(ClientSession clientSession, Class<TResult> resultClass);

    
Creates a change stream for this client.
Returns:
the change stream iterable
@mongodb.driver.dochub
core/changestreams Change Streams
Since:
3.8
@mongodb.server.release
4.0/**
     * Creates a change stream for this client.
     *
     * @return the change stream iterable
     * @mongodb.driver.dochub core/changestreams Change Streams
     * @since 3.8
     * @mongodb.server.release 4.0
     */
    ChangeStreamIterable<Document> watch();

    
Creates a change stream for this client.
Params:
resultClass – the class to decode each document into
Type parameters:
<TResult> –   the target document type of the iterable.
Returns:
the change stream iterable
@mongodb.driver.dochub
core/changestreams Change Streams
Since:
3.8
@mongodb.server.release
4.0/**
     * Creates a change stream for this client.
     *
     * @param resultClass the class to decode each document into
     * @param <TResult>   the target document type of the iterable.
     * @return the change stream iterable
     * @mongodb.driver.dochub core/changestreams Change Streams
     * @since 3.8
     * @mongodb.server.release 4.0
     */
    <TResult> ChangeStreamIterable<TResult> watch(Class<TResult> resultClass);

    
Creates a change stream for this client.
Params:
pipeline – the aggregation pipeline to apply to the change stream.
Returns:
the change stream iterable
@mongodb.driver.dochub
core/changestreams Change Streams
Since:
3.8
@mongodb.server.release
4.0/**
     * Creates a change stream for this client.
     *
     * @param pipeline the aggregation pipeline to apply to the change stream.
     * @return the change stream iterable
     * @mongodb.driver.dochub core/changestreams Change Streams
     * @since 3.8
     * @mongodb.server.release 4.0
     */
    ChangeStreamIterable<Document> watch(List<? extends Bson> pipeline);

    
Creates a change stream for this client.
Params:
pipeline –    the aggregation pipeline to apply to the change stream
resultClass – the class to decode each document into
Type parameters:
<TResult> –   the target document type of the iterable.
Returns:
the change stream iterable
@mongodb.driver.dochub
core/changestreams Change Streams
Since:
3.8
@mongodb.server.release
4.0/**
     * 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 <TResult>   the target document type of the iterable.
     * @return the change stream iterable
     * @mongodb.driver.dochub core/changestreams Change Streams
     * @since 3.8
     * @mongodb.server.release 4.0
     */
    <TResult> ChangeStreamIterable<TResult> watch(List<? extends Bson> pipeline, Class<TResult> resultClass);

    
Creates a change stream for this client.
Params:
clientSession – the client session with which to associate this operation
Returns:
the change stream iterable
Since:
3.8
@mongodb.server.release
4.0
@mongodb.driver.dochub
core/changestreams Change Streams/**
     * 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
     */
    ChangeStreamIterable<Document> watch(ClientSession clientSession);

    
Creates a change stream for this client.
Params:
clientSession – the client session with which to associate this operation
resultClass – the class to decode each document into
Type parameters:
<TResult> –   the target document type of the iterable.
Returns:
the change stream iterable
Since:
3.8
@mongodb.server.release
4.0
@mongodb.driver.dochub
core/changestreams Change Streams/**
     * 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 <TResult>   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
     */
    <TResult> ChangeStreamIterable<TResult> watch(ClientSession clientSession, Class<TResult> resultClass);

    
Creates a change stream for this client.
Params:
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.server.release
4.0
@mongodb.driver.dochub
core/changestreams Change Streams/**
     * 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
     */
    ChangeStreamIterable<Document> watch(ClientSession clientSession, List<? extends Bson> pipeline);

    
Creates a change stream for this client.
Params:
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
Type parameters:
<TResult> –   the target document type of the iterable.
Returns:
the change stream iterable
Since:
3.8
@mongodb.server.release
4.0
@mongodb.driver.dochub
core/changestreams Change Streams/**
     * 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 <TResult>   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
     */
    <TResult> ChangeStreamIterable<TResult> watch(ClientSession clientSession, List<? extends Bson> pipeline, Class<TResult> resultClass);

    
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. 
See Also:
Builder.addClusterListener(ClusterListener)
Builder.applyToClusterSettings(Block<Builder>)
Returns:
the current cluster description
Since:
3.11/**
     * Gets the current cluster description.
     *
     * <p>
     * This method will not block, meaning that it may return a {@link ClusterDescription} whose {@code clusterType} is unknown
     * and whose {@link com.mongodb.connection.ServerDescription}s 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 {@link ClusterListener} via
     * the {@link ClusterSettings} in {@link com.mongodb.MongoClientSettings}.
     * </p>
     *
     * @return the current cluster description
     * @see ClusterSettings.Builder#addClusterListener(ClusterListener)
     * @see com.mongodb.MongoClientSettings.Builder#applyToClusterSettings(com.mongodb.Block)
     * @since 3.11
     */
    ClusterDescription getClusterDescription();
}