Package io.realm.mongodb.mongo

Class MongoCollection<DocumentT>

  • Type Parameters:
    DocumentT - The type that this collection will encode documents from and decode documents to.
    public class MongoCollection<DocumentT>
extends Object
    The MongoCollection interface provides read and write access to documents.

    Use MongoDatabase.getCollection(java.lang.String) to get a collection instance.

    Before any access is possible, there must be an active, logged-in user.

    See Also:
    MongoDatabase

    • Method Detail

      • getNamespace

        public MongoNamespace getNamespace()
        Gets the namespace of this collection, i.e. the database and collection names together.
        Returns:
        the namespace

      • getName

        public String getName()
        Gets the name of this collection
        Returns:
        the name

      • getCodecRegistry

        public CodecRegistry getCodecRegistry()
        Gets the codec registry for the MongoCollection.
        Returns:
        the CodecRegistry for this collection

      • withDocumentClass

        public <NewDocumentT> MongoCollection<NewDocumentT> withDocumentClass​(Class<NewDocumentT> clazz)
        Creates a new MongoCollection instance with a different default class to cast any documents returned from the database into.
        Type Parameters:
        NewDocumentT - The type that the new collection will encode documents from and decode documents to.
        Parameters:
        clazz - the default class to which any documents returned from the database will be cast.
        Returns:
        a new MongoCollection instance with the different default class

      • withCodecRegistry

        public MongoCollection<DocumentT> withCodecRegistry​(CodecRegistry codecRegistry)
        Creates a new MongoCollection instance with a different codec registry.
        Parameters:
        codecRegistry - the new CodecRegistry for the collection.
        Returns:
        a new MongoCollection instance with the different codec registry

      • count

        public RealmResultTask<Long> count()
        Counts the number of documents in the collection.
        Returns:
        a task containing the number of documents in the collection

      • count

        public RealmResultTask<Long> count​(Bson filter)
        Counts the number of documents in the collection according to the given options.
        Parameters:
        filter - the query filter
        Returns:
        a task containing the number of documents in the collection

      • count

        public RealmResultTask<Long> count​(Bson filter,
                                   CountOptions options)
        Counts the number of documents in the collection according to the given options.
        Parameters:
        filter - the query filter
        options - the options describing the count
        Returns:
        a task containing the number of documents in the collection

      • findOne

        public RealmResultTask<DocumentT> findOne()
        Finds a document in the collection.
        Returns:
        a task containing the result of the find one operation

      • findOne

        public <ResultT> RealmResultTask<ResultT> findOne​(Class<ResultT> resultClass)
        Finds a document in the collection.
        Type Parameters:
        ResultT - the target document type
        Parameters:
        resultClass - the class to decode each document into
        Returns:
        a task containing the result of the find one operation

      • findOne

        public RealmResultTask<DocumentT> findOne​(Bson filter)
        Finds a document in the collection.
        Parameters:
        filter - the query filter
        Returns:
        a task containing the result of the find one operation

      • findOne

        public <ResultT> RealmResultTask<ResultT> findOne​(Bson filter,
                                                  Class<ResultT> resultClass)
        Finds a document in the collection.
        Type Parameters:
        ResultT - the target document type of the iterable.
        Parameters:
        filter - the query filter
        resultClass - the class to decode each document into
        Returns:
        a task containing the result of the find one operation

      • findOne

        public RealmResultTask<DocumentT> findOne​(Bson filter,
                                          FindOptions options)
        Finds a document in the collection.
        Parameters:
        filter - the query filter
        options - a FindOptions struct
        Returns:
        a task containing the result of the find one operation

      • findOne

        public <ResultT> RealmResultTask<ResultT> findOne​(Bson filter,
                                                  FindOptions options,
                                                  Class<ResultT> resultClass)
        Finds a document in the collection.
        Type Parameters:
        ResultT - the target document type of the iterable.
        Parameters:
        filter - the query filter
        options - a FindOptions struct
        resultClass - the class to decode each document into
        Returns:
        a task containing the result of the find one operation

      • find

        public FindIterable<DocumentT> find()
        Finds all documents in the collection.

        All documents will be delivered in the form of a FindIterable from which individual elements can be extracted.

        Returns:
        an iterable containing the result of the find operation

      • find

        public FindIterable<DocumentT> find​(FindOptions options)
        Finds all documents in the collection using FindOptions to build the query.

        All documents will be delivered in the form of a FindIterable from which individual elements can be extracted.

        Parameters:
        options - a FindOptions struct for building the query
        Returns:
        an iterable containing the result of the find operation

      • find

        public <ResultT> FindIterable<ResultT> find​(Class<ResultT> resultClass)
        Finds all documents in the collection specifying an output class.

        All documents will be delivered in the form of a FindIterable from which individual elements can be extracted.

        Type Parameters:
        ResultT - the target document type of the iterable.
        Parameters:
        resultClass - the class to decode each document into
        Returns:
        an iterable containing the result of the find operation

      • find

        public <ResultT> FindIterable<ResultT> find​(Class<ResultT> resultClass,
                                            FindOptions options)
        Finds all documents in the collection specifying an output class and also using FindOptions to build the query.

        All documents will be delivered in the form of a FindIterable from which individual elements can be extracted.

        Type Parameters:
        ResultT - the target document type of the iterable.
        Parameters:
        resultClass - the class to decode each document into
        options - a FindOptions struct for building the query
        Returns:
        an iterable containing the result of the find operation

      • find

        public FindIterable<DocumentT> find​(Bson filter)
        Finds all documents in the collection that match the given filter.

        All documents will be delivered in the form of a FindIterable from which individual elements can be extracted.

        Parameters:
        filter - the query filter
        Returns:
        an iterable containing the result of the find operation

      • find

        public FindIterable<DocumentT> find​(Bson filter,
                                    FindOptions options)
        Finds all documents in the collection that match the given filter using FindOptions to build the query.

        All documents will be delivered in the form of a FindIterable from which individual elements can be extracted.

        Parameters:
        filter - the query filter
        options - a FindOptions struct
        Returns:
        an iterable containing the result of the find operation

      • find

        public <ResultT> FindIterable<ResultT> find​(Bson filter,
                                            Class<ResultT> resultClass)
        Finds all documents in the collection that match the given filter specifying an output class.

        All documents will be delivered in the form of a FindIterable from which individual elements can be extracted.

        Type Parameters:
        ResultT - the target document type of the iterable.
        Parameters:
        filter - the query filter
        resultClass - the class to decode each document into
        Returns:
        an iterable containing the result of the find operation

      • find

        public <ResultT> FindIterable<ResultT> find​(Bson filter,
                                            Class<ResultT> resultClass,
                                            FindOptions options)
        Finds all documents in the collection that match the given filter specifying an output class and also using FindOptions to build the query.

        All documents will be delivered in the form of a FindIterable from which individual elements can be extracted.

        Type Parameters:
        ResultT - the target document type of the iterable.
        Parameters:
        filter - the query filter
        resultClass - the class to decode each document into
        options - a FindOptions struct
        Returns:
        an iterable containing the result of the find operation

      • aggregate

        public AggregateIterable<DocumentT> aggregate​(List<? extends Bson> pipeline)
        Aggregates documents according to the specified aggregation pipeline.

        All documents will be delivered in the form of an AggregateIterable from which individual elements can be extracted.

        Parameters:
        pipeline - the aggregation pipeline
        Returns:
        an AggregateIterable from which the results can be extracted

      • aggregate

        public <ResultT> AggregateIterable<ResultT> aggregate​(List<? extends Bson> pipeline,
                                                      Class<ResultT> resultClass)
        Aggregates documents according to the specified aggregation pipeline specifying an output class.

        All documents will be delivered in the form of an AggregateIterable from which individual elements can be extracted.

        Type Parameters:
        ResultT - the target document type of the iterable.
        Parameters:
        pipeline - the aggregation pipeline
        resultClass - the class to decode each document into
        Returns:
        an AggregateIterable from which the results can be extracted

      • insertOne

        public RealmResultTask<InsertOneResult> insertOne​(DocumentT document)
        Inserts the provided document. If the document is missing an identifier, the client should generate one.
        Parameters:
        document - the document to insert
        Returns:
        a task containing the result of the insert one operation

      • insertMany

        public RealmResultTask<InsertManyResult> insertMany​(List<? extends DocumentT> documents)
        Inserts one or more documents.
        Parameters:
        documents - the documents to insert
        Returns:
        a task containing the result of the insert many operation

      • deleteOne

        public RealmResultTask<DeleteResult> deleteOne​(Bson filter)
        Removes at most one document from the collection that matches the given filter. If no documents match, the collection is not modified.
        Parameters:
        filter - the query filter to apply the the delete operation
        Returns:
        a task containing the result of the remove one operation

      • deleteMany

        public RealmResultTask<DeleteResult> deleteMany​(Bson filter)
        Removes all documents from the collection that match the given query filter. If no documents match, the collection is not modified.
        Parameters:
        filter - the query filter to apply the the delete operation
        Returns:
        a task containing the result of the remove many operation

      • updateOne

        public RealmResultTask<UpdateResult> updateOne​(Bson filter,
                                               Bson update)
        Update a single document in the collection according to the specified arguments.
        Parameters:
        filter - a document describing the query filter, which may not be null.
        update - a document describing the update, which may not be null. The update to apply must include only update operators.
        Returns:
        a task containing the result of the update one operation

      • updateOne

        public RealmResultTask<UpdateResult> updateOne​(Bson filter,
                                               Bson update,
                                               UpdateOptions updateOptions)
        Update a single document in the collection according to the specified arguments.
        Parameters:
        filter - a document describing the query filter, which may not be null.
        update - a document describing the update, which may not be null. The update to apply must include only update operators.
        updateOptions - the options to apply to the update operation
        Returns:
        a task containing the result of the update one operation

      • updateMany

        public RealmResultTask<UpdateResult> updateMany​(Bson filter,
                                                Bson update)
        Update all documents in the collection according to the specified arguments.
        Parameters:
        filter - a document describing the query filter, which may not be null.
        update - a document describing the update, which may not be null. The update to apply must include only update operators.
        Returns:
        a task containing the result of the update many operation

      • updateMany

        public RealmResultTask<UpdateResult> updateMany​(Bson filter,
                                                Bson update,
                                                UpdateOptions updateOptions)
        Update all documents in the collection according to the specified arguments.
        Parameters:
        filter - a document describing the query filter, which may not be null.
        update - a document describing the update, which may not be null. The update to apply must include only update operators.
        updateOptions - the options to apply to the update operation
        Returns:
        a task containing the result of the update many operation

      • findOneAndUpdate

        public RealmResultTask<DocumentT> findOneAndUpdate​(Bson filter,
                                                   Bson update)
        Finds a document in the collection and performs the given update.
        Parameters:
        filter - the query filter
        update - the update document
        Returns:
        a task containing the resulting document

      • findOneAndUpdate

        public <ResultT> RealmResultTask<ResultT> findOneAndUpdate​(Bson filter,
                                                           Bson update,
                                                           Class<ResultT> resultClass)
        Finds a document in the collection and performs the given update.
        Type Parameters:
        ResultT - the target document type of the iterable.
        Parameters:
        filter - the query filter
        update - the update document
        resultClass - the class to decode each document into
        Returns:
        a task containing the resulting document

      • findOneAndUpdate

        public <ResultT> RealmResultTask<ResultT> findOneAndUpdate​(Bson filter,
                                                           Bson update,
                                                           FindOneAndModifyOptions options,
                                                           Class<ResultT> resultClass)
        Finds a document in the collection and performs the given update.
        Type Parameters:
        ResultT - the target document type of the iterable.
        Parameters:
        filter - the query filter
        update - the update document
        options - a FindOneAndModifyOptions struct
        resultClass - the class to decode each document into
        Returns:
        a task containing the resulting document

      • findOneAndReplace

        public RealmResultTask<DocumentT> findOneAndReplace​(Bson filter,
                                                    Bson replacement)
        Finds a document in the collection and replaces it with the given document.
        Parameters:
        filter - the query filter
        replacement - the document to replace the matched document with
        Returns:
        a task containing the resulting document

      • findOneAndReplace

        public <ResultT> RealmResultTask<ResultT> findOneAndReplace​(Bson filter,
                                                            Bson replacement,
                                                            Class<ResultT> resultClass)
        Finds a document in the collection and replaces it with the given document.
        Type Parameters:
        ResultT - the target document type of the iterable.
        Parameters:
        filter - the query filter
        replacement - the document to replace the matched document with
        resultClass - the class to decode each document into
        Returns:
        a task containing the resulting document

      • findOneAndReplace

        public RealmResultTask<DocumentT> findOneAndReplace​(Bson filter,
                                                    Bson replacement,
                                                    FindOneAndModifyOptions options)
        Finds a document in the collection and replaces it with the given document.
        Parameters:
        filter - the query filter
        replacement - the document to replace the matched document with
        options - a FindOneAndModifyOptions struct
        Returns:
        a task containing the resulting document

      • findOneAndReplace

        public <ResultT> RealmResultTask<ResultT> findOneAndReplace​(Bson filter,
                                                            Bson replacement,
                                                            FindOneAndModifyOptions options,
                                                            Class<ResultT> resultClass)
        Finds a document in the collection and replaces it with the given document.
        Type Parameters:
        ResultT - the target document type of the iterable.
        Parameters:
        filter - the query filter
        replacement - the document to replace the matched document with
        options - a FindOneAndModifyOptions struct
        resultClass - the class to decode each document into
        Returns:
        a task containing the resulting document

      • findOneAndDelete

        public RealmResultTask<DocumentT> findOneAndDelete​(Bson filter)
        Finds a document in the collection and delete it.
        Parameters:
        filter - the query filter
        Returns:
        a task containing the resulting document

      • findOneAndDelete

        public <ResultT> RealmResultTask<ResultT> findOneAndDelete​(Bson filter,
                                                           Class<ResultT> resultClass)
        Finds a document in the collection and delete it.
        Type Parameters:
        ResultT - the target document type of the iterable.
        Parameters:
        filter - the query filter
        resultClass - the class to decode each document into
        Returns:
        a task containing the resulting document

      • findOneAndDelete

        public <ResultT> RealmResultTask<ResultT> findOneAndDelete​(Bson filter,
                                                           FindOneAndModifyOptions options,
                                                           Class<ResultT> resultClass)
        Finds a document in the collection and delete it.
        Type Parameters:
        ResultT - the target document type of the iterable.
        Parameters:
        filter - the query filter
        options - a FindOneAndModifyOptions struct
        resultClass - the class to decode each document into
        Returns:
        a task containing the resulting document

      • watch

        public RealmEventStreamTask<DocumentT> watch()
        Watches a collection. The resulting stream will be notified of all events on this collection that the active user is authorized to see based on the configured MongoDB Realm rules.
        Returns:
        a task that provides access to the stream of change events.

      • watch

        public RealmEventStreamTask<DocumentT> watch​(BsonValue... ids)
        Watches specified IDs in a collection.
        Parameters:
        ids - the ids to watch.
        Returns:
        a task that provides access to the stream of change events.

      • watch

        public RealmEventStreamTask<DocumentT> watch​(ObjectId... ids)
        Watches specified IDs in a collection. This convenience overload supports the use case of non-BsonValue instances of ObjectId by wrapping them in BsonObjectId instances for the user.
        Parameters:
        ids - unique object identifiers of the IDs to watch.
        Returns:
        a task that provides access to the stream of change events.

      • watchAsync

        public RealmEventStreamAsyncTask<DocumentT> watchAsync()
        Watches a collection asynchronously. The resulting stream will be notified of all events on this collection that the active user is authorized to see based on the configured MongoDB Realm rules.
        Returns:
        a task that provides access to the stream of change events.

      • watchAsync

        public RealmEventStreamAsyncTask<DocumentT> watchAsync​(BsonValue... ids)
        Watches specified IDs in a collection asynchronously.
        Parameters:
        ids - the ids to watch.
        Returns:
        a task that provides access to the stream of change events.

      • watchAsync

        public RealmEventStreamAsyncTask<DocumentT> watchAsync​(ObjectId... ids)
        Watches specified IDs in a collection asynchronously. This convenience overload supports the use case of non-BsonValue instances of ObjectId by wrapping them in BsonObjectId instances for the user.
        Parameters:
        ids - unique object identifiers of the IDs to watch.
        Returns:
        a task that provides access to the stream of change events.

      • watchWithFilterAsync

        public RealmEventStreamAsyncTask<DocumentT> watchWithFilterAsync​(Document matchFilter)
        Watches a collection asynchronously. The provided document will be used as a match expression filter on the change events coming from the stream. This convenience overload supports the use of non-BsonDocument instances for the user.

        See how to define a match filter.

        Defining the match expression to filter ChangeEvents is similar to how to define the match expression for triggers

        Parameters:
        matchFilter - the $match filter to apply to incoming change events
        Returns:
        a task that provides access to the stream of change events.