Package io.vertx.ext.mongo

Interface MongoClient

  • public interface MongoClient
    A Vert.x service used to interact with MongoDB server instances.

    Some of the operations might change _id field of passed JsonObject document.

    Author:
    Tim Fox

    • Method Detail

      • create

        static MongoClient create​(Vertx vertx,
                          JsonObject config)
        Create a Mongo client which maintains its own data source.
        Parameters:
        vertx - the Vert.x instance
        config - the configuration
        Returns:
        the client

      • createShared

        static MongoClient createShared​(Vertx vertx,
                                JsonObject config,
                                String dataSourceName)
        Create a Mongo client which shares its data source with any other Mongo clients created with the same data source name
        Parameters:
        vertx - the Vert.x instance
        config - the configuration
        dataSourceName - the data source name
        Returns:
        the client

      • createWithMongoSettings

        static MongoClient createWithMongoSettings​(Vertx vertx,
                                           JsonObject config,
                                           String dataSourceName,
                                           com.mongodb.MongoClientSettings settings)
        Constructor targeting the jvm, like standard constructor createShared(Vertx, JsonObject, String), but it accepts default mongoClientSettings to configure mongo
        Parameters:
        vertx - the Vert.x instance
        config - the configuration use only to provide objectId and database name
        dataSourceName - the data source name
        settings - the native java mongo settings
        Returns:
        the client

      • save

        Future<String> save​(String collection,
                    JsonObject document)
        Save a document in the specified collection

        This operation might change _id field of document parameter

        Parameters:
        collection - the collection
        document - the document
        Returns:
        a future provided with the id if document didn't already have one

      • saveWithOptions

        Future<String> saveWithOptions​(String collection,
                               JsonObject document,
                               WriteOption writeOption)
        Save a document in the specified collection with the specified write option

        This operation might change _id field of document parameter

        Parameters:
        collection - the collection
        document - the document
        writeOption - the write option to use
        Returns:
        a future provided with the id if document didn't already have one

      • insert

        Future<String> insert​(String collection,
                      JsonObject document)
        Insert a document in the specified collection

        This operation might change _id field of document parameter

        Parameters:
        collection - the collection
        document - the document
        Returns:
        a future provided with the id if document didn't already have one

      • insertWithOptions

        Future<String> insertWithOptions​(String collection,
                                 JsonObject document,
                                 WriteOption writeOption)
        Insert a document in the specified collection with the specified write option

        This operation might change _id field of document parameter

        Parameters:
        collection - the collection
        document - the document
        writeOption - the write option to use
        Returns:
        a future provided with the id if document didn't already have one

      • updateCollection

        Future<MongoClientUpdateResult> updateCollection​(String collection,
                                                 JsonObject query,
                                                 JsonObject update)
        Update matching documents in the specified collection and return the handler with MongoClientUpdateResult result
        Parameters:
        collection - the collection
        query - query used to match the documents
        update - used to describe how the documents will be updated
        Returns:
        a future notified with a MongoClientUpdateResult when complete

      • updateCollection

        Future<MongoClientUpdateResult> updateCollection​(String collection,
                                                 JsonObject query,
                                                 JsonArray update)
        Use an aggregation pipeline to update documents in the specified collection and return the handler with MongoClientUpdateResult result
        Parameters:
        collection - the collection
        query - query used to match the documents
        update - used to describe how the documents will be updated
        Returns:
        a future notified with a MongoClientUpdateResult when complete

      • updateCollectionWithOptions

        Future<MongoClientUpdateResult> updateCollectionWithOptions​(String collection,
                                                            JsonObject query,
                                                            JsonObject update,
                                                            UpdateOptions options)
        Update matching documents in the specified collection, specifying options and return the handler with MongoClientUpdateResult result
        Parameters:
        collection - the collection
        query - query used to match the documents
        update - used to describe how the documents will be updated
        options - options to configure the update
        Returns:
        a future notified with a MongoClientUpdateResult when complete

      • updateCollectionWithOptions

        Future<MongoClientUpdateResult> updateCollectionWithOptions​(String collection,
                                                            JsonObject query,
                                                            JsonArray update,
                                                            UpdateOptions options)
        Use an aggregation pipeline to update documents in the specified collection, specifying options and return the handler with MongoClientUpdateResult result
        Parameters:
        collection - the collection
        query - query used to match the documents
        update - aggregation pipeline used to describe how documents will be updated
        options - options to configure the update
        Returns:
        a future notified with a MongoClientUpdateResult when complete

      • replaceDocuments

        Future<MongoClientUpdateResult> replaceDocuments​(String collection,
                                                 JsonObject query,
                                                 JsonObject replace)
        Replace matching documents in the specified collection and return the handler with MongoClientUpdateResult result
        Parameters:
        collection - the collection
        query - query used to match the documents
        replace - all matching documents will be replaced with this
        Returns:
        a future notified with a MongoClientUpdateResult when complete

      • replaceDocumentsWithOptions

        Future<MongoClientUpdateResult> replaceDocumentsWithOptions​(String collection,
                                                            JsonObject query,
                                                            JsonObject replace,
                                                            UpdateOptions options)
        Replace matching documents in the specified collection, specifying options and return the handler with MongoClientUpdateResult result
        Parameters:
        collection - the collection
        query - query used to match the documents
        replace - all matching documents will be replaced with this
        options - options to configure the replace
        Returns:
        a future notified with a MongoClientUpdateResult when complete

      • bulkWriteWithOptions

        Future<MongoClientBulkWriteResult> bulkWriteWithOptions​(String collection,
                                                        List<BulkOperation> operations,
                                                        BulkWriteOptions bulkWriteOptions)
        Execute a bulk operation with the specified write options. Can insert, update, replace, and/or delete multiple documents with one request.
        Parameters:
        collection - the collection
        operations - the operations to execute
        bulkWriteOptions - the write options
        Returns:
        a future notified with a MongoClientBulkWriteResult when complete

      • find

        Future<List<JsonObject>> find​(String collection,
                              JsonObject query)
        Find matching documents in the specified collection
        Parameters:
        collection - the collection
        query - query used to match documents
        Returns:
        a future provided with list of documents

      • findBatch

        ReadStream<JsonObject> findBatch​(String collection,
                                 JsonObject query)
        Find matching documents in the specified collection. This method use batchCursor for returning each found document.
        Parameters:
        collection - the collection
        query - query used to match documents
        Returns:
        a ReadStream emitting found documents

      • findWithOptions

        Future<List<JsonObject>> findWithOptions​(String collection,
                                         JsonObject query,
                                         FindOptions options)
        Find matching documents in the specified collection, specifying options
        Parameters:
        collection - the collection
        query - query used to match documents
        options - options to configure the find
        Returns:
        a future provided with list of documents

      • findBatchWithOptions

        ReadStream<JsonObject> findBatchWithOptions​(String collection,
                                            JsonObject query,
                                            FindOptions options)
        Find matching documents in the specified collection, specifying options. This method use batchCursor for returning each found document.
        Parameters:
        collection - the collection
        query - query used to match documents
        options - options to configure the find
        Returns:
        a ReadStream emitting found documents

      • findOne

        Future<JsonObject> findOne​(String collection,
                           JsonObject query,
                           JsonObject fields)
        Find a single matching document in the specified collection

        This operation might change _id field of query parameter

        Parameters:
        collection - the collection
        query - the query used to match the document
        fields - the fields
        Returns:
        a future provided with the document, if any

      • findOneAndUpdate

        Future<JsonObject> findOneAndUpdate​(String collection,
                                    JsonObject query,
                                    JsonObject update)
        Find a single matching document in the specified collection and update it.

        This operation might change _id field of query parameter

        Parameters:
        collection - the collection
        query - the query used to match the document
        update - used to describe how the documents will be updated
        Returns:
        a future provided with the document, if any

      • findOneAndUpdateWithOptions

        Future<JsonObject> findOneAndUpdateWithOptions​(String collection,
                                               JsonObject query,
                                               JsonObject update,
                                               FindOptions findOptions,
                                               UpdateOptions updateOptions)
        Find a single matching document in the specified collection and update it.

        This operation might change _id field of query parameter

        Parameters:
        collection - the collection
        query - the query used to match the document
        update - used to describe how the documents will be updated
        findOptions - options to configure the find
        updateOptions - options to configure the update
        Returns:
        a future provided with the document, if any

      • findOneAndReplace

        Future<JsonObject> findOneAndReplace​(String collection,
                                     JsonObject query,
                                     JsonObject replace)
        Find a single matching document in the specified collection and replace it.

        This operation might change _id field of query parameter

        Parameters:
        collection - the collection
        query - the query used to match the document
        replace - the replacement document
        Returns:
        a future provided with the document, if any

      • findOneAndReplaceWithOptions

        Future<JsonObject> findOneAndReplaceWithOptions​(String collection,
                                                JsonObject query,
                                                JsonObject replace,
                                                FindOptions findOptions,
                                                UpdateOptions updateOptions)
        Find a single matching document in the specified collection and replace it.

        This operation might change _id field of query parameter

        Parameters:
        collection - the collection
        query - the query used to match the document
        replace - the replacement document
        findOptions - options to configure the find
        updateOptions - options to configure the update
        Returns:
        a future provided with the document, if any

      • findOneAndDelete

        Future<JsonObject> findOneAndDelete​(String collection,
                                    JsonObject query)
        Find a single matching document in the specified collection and delete it.

        This operation might change _id field of query parameter

        Parameters:
        collection - the collection
        query - the query used to match the document
        Returns:
        a future provided with the deleted document, if any

      • findOneAndDeleteWithOptions

        Future<JsonObject> findOneAndDeleteWithOptions​(String collection,
                                               JsonObject query,
                                               FindOptions findOptions)
        Find a single matching document in the specified collection and delete it.

        This operation might change _id field of query parameter

        Parameters:
        collection - the collection
        query - the query used to match the document
        findOptions - options to configure the find
        Returns:
        a future provided with the deleted document, if any

      • count

        Future<Long> count​(String collection,
                   JsonObject query)
        Count matching documents in a collection.
        Parameters:
        collection - the collection
        query - query used to match documents
        Returns:
        a future provided with the number of matching documents

      • countWithOptions

        Future<Long> countWithOptions​(String collection,
                              JsonObject query,
                              CountOptions countOptions)
        Count matching documents in a collection.
        Parameters:
        collection - the collection
        query - query used to match documents
        countOptions -
        Returns:
        a future provided with the number of matching documents

      • removeDocuments

        Future<MongoClientDeleteResult> removeDocuments​(String collection,
                                                JsonObject query)
        Remove matching documents from a collection and return the handler with MongoClientDeleteResult result
        Parameters:
        collection - the collection
        query - query used to match documents
        Returns:
        a future notified with a MongoClientDeleteResult when complete

      • removeDocumentsWithOptions

        Future<MongoClientDeleteResult> removeDocumentsWithOptions​(String collection,
                                                           JsonObject query,
                                                           WriteOption writeOption)
        Remove matching documents from a collection with the specified write option and return the handler with MongoClientDeleteResult result
        Parameters:
        collection - the collection
        query - query used to match documents
        writeOption - the write option to use
        Returns:
        a future notified with a MongoClientDeleteResult when complete

      • removeDocument

        Future<MongoClientDeleteResult> removeDocument​(String collection,
                                               JsonObject query)
        Remove a single matching document from a collection and return the handler with MongoClientDeleteResult result
        Parameters:
        collection - the collection
        query - query used to match document
        Returns:
        a future notified with a MongoClientDeleteResult when complete

      • removeDocumentWithOptions

        Future<MongoClientDeleteResult> removeDocumentWithOptions​(String collection,
                                                          JsonObject query,
                                                          WriteOption writeOption)
        Remove a single matching document from a collection with the specified write option and return the handler with MongoClientDeleteResult result
        Parameters:
        collection - the collection
        query - query used to match document
        writeOption - the write option to use
        Returns:
        a future notified with a MongoClientDeleteResult when complete

      • createCollection

        Future<Void> createCollection​(String collectionName)
        Create a new collection
        Parameters:
        collectionName - the name of the collection
        Returns:
        a future notified once complete

      • createCollectionWithOptions

        Future<Void> createCollectionWithOptions​(String collectionName,
                                         CreateCollectionOptions collectionOptions)
        Create a new collection with options
        Parameters:
        collectionName - the name of the collection
        collectionOptions - options of the collection
        Returns:
        a future notified once complete

      • getCollections

        Future<List<String>> getCollections()
        Get a list of all collections in the database.
        Returns:
        a future notified with a list of collections.

      • dropCollection

        Future<Void> dropCollection​(String collection)
        Drop a collection
        Parameters:
        collection - the collection
        Returns:
        a future notified when complete

      • renameCollection

        Future<Void> renameCollection​(String oldCollectionName,
                              String newCollectionName)
        Rename a collection
        Parameters:
        oldCollectionName - the name of the collection
        newCollectionName - the new name of the collection
        Returns:
        a future notified when complete

      • renameCollectionWithOptions

        Future<Void> renameCollectionWithOptions​(String oldCollectionName,
                                         String newCollectionName,
                                         RenameCollectionOptions collectionOptions)
        Rename a collection
        Parameters:
        oldCollectionName - the name of the collection
        newCollectionName - the new name of the collection
        collectionOptions - options of the collection
        Returns:
        a future notified when complete

      • createIndex

        Future<Void> createIndex​(String collection,
                         JsonObject key)
        Creates an index.
        Parameters:
        collection - the collection
        key - A document that contains the field and value pairs where the field is the index key and the value describes the type of index for that field. For an ascending index on a field, specify a value of 1; for descending index, specify a value of -1.
        Returns:
        a future notified when complete

      • createIndexWithOptions

        Future<Void> createIndexWithOptions​(String collection,
                                    JsonObject key,
                                    IndexOptions options)
        Creates an index.
        Parameters:
        collection - the collection
        key - A document that contains the field and value pairs where the field is the index key and the value describes the type of index for that field. For an ascending index on a field, specify a value of 1; for descending index, specify a value of -1.
        options - the options for the index
        Returns:
        a future notified when complete

      • createIndexes

        Future<Void> createIndexes​(String collection,
                           List<IndexModel> indexes)
        creates an indexes
        Parameters:
        collection - the collection
        indexes - A model that contains pairs of document and indexOptions, document contains the field and value pairs where the field is the index key and the value describes the type of index for that field. For an ascending index on a field, specify a value of 1; for descending index, specify a value of -1.
        Returns:
        a future notified when complete

      • listIndexes

        Future<JsonArray> listIndexes​(String collection)
        Get all the indexes in this collection.
        Parameters:
        collection - the collection
        Returns:
        a future notified when complete

      • dropIndex

        Future<Void> dropIndex​(String collection,
                       String indexName)
        Drops the index given its name.
        Parameters:
        collection - the collection
        indexName - the name of the index to remove
        Returns:
        a future notified when complete

      • dropIndex

        Future<Void> dropIndex​(String collection,
                       JsonObject key)
        Drops the index given the keys used to create it.
        Parameters:
        collection - the collection
        key - the key(s) of the index to remove
        Returns:
        a future notified when complete

      • runCommand

        Future<JsonObject> runCommand​(String commandName,
                              JsonObject command)
        Run an arbitrary MongoDB command.
        Parameters:
        commandName - the name of the command
        command - the command
        Returns:
        a future notified with the result.

      • distinct

        Future<JsonArray> distinct​(String collection,
                           String fieldName,
                           String resultClassname)
        Gets the distinct values of the specified field name. Return a JsonArray containing distinct values (eg: [ 1 , 89 ])
        Parameters:
        collection - the collection
        fieldName - the field name
        Returns:
        a future provided with array of values.

      • distinct

        Future<JsonArray> distinct​(String collection,
                           String fieldName,
                           String resultClassname,
                           DistinctOptions distinctOptions)
        Gets the distinct values of the specified field name. Return a JsonArray containing distinct values (eg: [ 1 , 89 ])
        Parameters:
        collection - the collection
        fieldName - the field name
        distinctOptions - options (e.g. collation)
        Returns:
        a future provided with array of values.

      • distinctWithQuery

        Future<JsonArray> distinctWithQuery​(String collection,
                                    String fieldName,
                                    String resultClassname,
                                    JsonObject query)
        Gets the distinct values of the specified field name filtered by specified query. Return a JsonArray containing distinct values (eg: [ 1 , 89 ])
        Parameters:
        collection - the collection
        fieldName - the field name
        query - the query
        Returns:
        a future provided with array of values.

      • distinctWithQuery

        Future<JsonArray> distinctWithQuery​(String collection,
                                    String fieldName,
                                    String resultClassname,
                                    JsonObject query,
                                    DistinctOptions distinctOptions)
        Gets the distinct values of the specified field name filtered by specified query. Return a JsonArray containing distinct values (eg: [ 1 , 89 ])
        Parameters:
        collection - the collection
        fieldName - the field name
        query - the query
        distinctOptions - options (e.g. collation)
        Returns:
        a future provided with array of values.

      • distinctBatch

        ReadStream<JsonObject> distinctBatch​(String collection,
                                     String fieldName,
                                     String resultClassname)
        Gets the distinct values of the specified field name. This method use batchCursor for returning each found value. Each value is a json fragment with fieldName key (eg: {"num": 1}).
        Parameters:
        collection - the collection
        fieldName - the field name
        Returns:
        a ReadStream emitting json fragments

      • distinctBatch

        ReadStream<JsonObject> distinctBatch​(String collection,
                                     String fieldName,
                                     String resultClassname,
                                     DistinctOptions distinctOptions)
        Gets the distinct values of the specified field name. This method use batchCursor for returning each found value. Each value is a json fragment with fieldName key (eg: {"num": 1}).
        Parameters:
        collection - the collection
        fieldName - the field name
        distinctOptions - options (e.g. collation)
        Returns:
        a ReadStream emitting json fragments

      • distinctBatchWithQuery

        ReadStream<JsonObject> distinctBatchWithQuery​(String collection,
                                              String fieldName,
                                              String resultClassname,
                                              JsonObject query)
        Gets the distinct values of the specified field name filtered by specified query. This method use batchCursor for returning each found value. Each value is a json fragment with fieldName key (eg: {"num": 1}).
        Parameters:
        collection - the collection
        fieldName - the field name
        query - the query
        Returns:
        a ReadStream emitting json fragments

      • distinctBatchWithQuery

        ReadStream<JsonObject> distinctBatchWithQuery​(String collection,
                                              String fieldName,
                                              String resultClassname,
                                              JsonObject query,
                                              DistinctOptions distinctOptions)
        Gets the distinct values of the specified field name filtered by specified query. This method use batchCursor for returning each found value. Each value is a json fragment with fieldName key (eg: {"num": 1}).
        Parameters:
        collection - the collection
        fieldName - the field name
        query - the query
        distinctOptions - options (e.g. collation)
        Returns:
        a ReadStream emitting json fragments

      • distinctBatchWithQuery

        ReadStream<JsonObject> distinctBatchWithQuery​(String collection,
                                              String fieldName,
                                              String resultClassname,
                                              JsonObject query,
                                              int batchSize)
        Gets the distinct values of the specified field name filtered by specified query. This method use batchCursor for returning each found value. Each value is a json fragment with fieldName key (eg: {"num": 1}).
        Parameters:
        collection - the collection
        fieldName - the field name
        query - the query
        batchSize - the number of documents to load in a batch
        Returns:
        a ReadStream emitting json fragments

      • distinctBatchWithQuery

        ReadStream<JsonObject> distinctBatchWithQuery​(String collection,
                                              String fieldName,
                                              String resultClassname,
                                              JsonObject query,
                                              int batchSize,
                                              DistinctOptions distinctOptions)
        Gets the distinct values of the specified field name filtered by specified query. This method use batchCursor for returning each found value. Each value is a json fragment with fieldName key (eg: {"num": 1}).
        Parameters:
        collection - the collection
        fieldName - the field name
        query - the query
        batchSize - the number of documents to load in a batch
        distinctOptions - options (e.g. collation)
        Returns:
        a ReadStream emitting json fragments

      • aggregateWithOptions

        ReadStream<JsonObject> aggregateWithOptions​(String collection,
                                            JsonArray pipeline,
                                            AggregateOptions options)
        Run aggregate MongoDB command.
        Parameters:
        collection - the collection
        pipeline - aggregation pipeline to be executed
        options - options to configure the aggregation command

      • watch

        ReadStream<com.mongodb.client.model.changestream.ChangeStreamDocument<JsonObject>> watch​(String collection,
                                                                                         JsonArray pipeline,
                                                                                         boolean withUpdatedDoc,
                                                                                         int batchSize)
        Watch the collection change.
        Parameters:
        collection - the collection
        pipeline - watching pipeline to be executed
        withUpdatedDoc - whether to get updated fullDocument for "update" operation
        batchSize - the number of documents to load in a batch

      • createGridFsBucketService

        Future<MongoGridFsClient> createGridFsBucketService​(String bucketName)
        Creates a MongoGridFsClient used to interact with Mongo GridFS.
        Parameters:
        bucketName - the name of the GridFS bucket
        Returns:
        a future notified with the MongoGridFsClient to interact with the bucket named bucketName

      • close

        Future<Void> close()
        Close the client and release its resources