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

  • Field Details

  • Method Details

    • 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

    • createShared

      static MongoClient createShared(Vertx vertx, JsonObject config)
      Like createShared(io.vertx.core.Vertx, JsonObject, String) but with the default data source name
      Parameters:
      vertx - the Vert.x instance
      config - the configuration
      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

    • bulkWrite

      Future<MongoClientBulkWriteResult> bulkWrite(String collection, List<BulkOperation> operations)
      Execute a bulk operation. Can insert, update, replace, and/or delete multiple documents with one request.
      Parameters:
      collection - the collection
      operations - the operations to execute
      Returns:
      a future notified with a MongoClientBulkWriteResult 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

    • aggregate

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

    • 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

    • createDefaultGridFsBucketService

      Future<MongoGridFsClient> createDefaultGridFsBucketService()
      Creates a MongoGridFsClient used to interact with Mongo GridFS.
      Returns:
      a future notified with the MongoGridFsClient to interact with the bucket named bucketName

    • 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