Class Collection


  • public class Collection
    extends Object
    The Collection provides blocking, synchronous access to all collection APIs.

    If asynchronous access is needed, we recommend looking at the ReactiveCollection and if the last drop of performance is needed the AsyncCollection. This blocking API itself is just a small layer on top of the AsyncCollection which blocks the current thread until the request completes with a response.

    Since:
    3.0.0
    • Method Detail

      • name

        public String name()
        Returns the name of this collection.
      • bucketName

        public String bucketName()
        Returns the name of the bucket associated with this collection.
      • scopeName

        public String scopeName()
        Returns the name of the scope associated with this collection.
      • get

        public GetResult get​(String id)
        Fetches the full document from this collection.
        Parameters:
        id - the document id which is used to uniquely identify it.
        Returns:
        a GetResult once the document has been loaded.
        Throws:
        DocumentNotFoundException - the given document id is not found in the collection.
        TimeoutException - if the operation times out before getting a result.
        CouchbaseException - for all other error reasons (acts as a base type and catch-all).
      • get

        public GetResult get​(String id,
                             GetOptions options)
        Fetches the full document from this collection with custom options.
        Parameters:
        id - the document id which is used to uniquely identify it.
        options - options to customize the get request.
        Returns:
        a GetResult once the document has been loaded.
        Throws:
        DocumentNotFoundException - the given document id is not found in the collection.
        TimeoutException - if the operation times out before getting a result.
        CouchbaseException - for all other error reasons (acts as a base type and catch-all).
      • getAndLock

        public GetResult getAndLock​(String id,
                                    Duration lockTime)
        Fetches a full document and write-locks it for the given duration.
        Parameters:
        id - the document id which is used to uniquely identify it.
        lockTime - how long to lock the document for (values over 30 seconds will be capped).
        Returns:
        a GetResult once the document has been locked and loaded.
        Throws:
        DocumentNotFoundException - the given document id is not found in the collection.
        TimeoutException - if the operation times out before getting a result.
        CouchbaseException - for all other error reasons (acts as a base type and catch-all).
      • getAndLock

        public GetResult getAndLock​(String id,
                                    Duration lockTime,
                                    GetAndLockOptions options)
        Fetches a full document and write-locks it for the given duration with custom options.
        Parameters:
        id - the document id which is used to uniquely identify it.
        lockTime - how long to lock the document for (values over 30 seconds will be capped).
        options - options to customize the get and lock request.
        Returns:
        a GetResult once the document has been loaded.
        Throws:
        DocumentNotFoundException - the given document id is not found in the collection.
        TimeoutException - if the operation times out before getting a result.
        CouchbaseException - for all other error reasons (acts as a base type and catch-all).
      • getAndTouch

        public GetResult getAndTouch​(String id,
                                     Duration expiry)
        Fetches a full document and resets its expiration time to the expiry provided.
        Parameters:
        id - the document id which is used to uniquely identify it.
        expiry - the new expiration time for the document.
        Returns:
        a GetResult once the document has been loaded.
        Throws:
        DocumentNotFoundException - the given document id is not found in the collection.
        TimeoutException - if the operation times out before getting a result.
        CouchbaseException - for all other error reasons (acts as a base type and catch-all).
      • getAndTouch

        public GetResult getAndTouch​(String id,
                                     Duration expiry,
                                     GetAndTouchOptions options)
        Fetches a full document and resets its expiration time to the expiry provided with custom options.
        Parameters:
        id - the document id which is used to uniquely identify it.
        expiry - the new expiration time for the document.
        options - options to customize the get and touch request.
        Returns:
        a GetResult once the document has been loaded.
        Throws:
        DocumentNotFoundException - the given document id is not found in the collection.
        TimeoutException - if the operation times out before getting a result.
        CouchbaseException - for all other error reasons (acts as a base type and catch-all).
      • getAllReplicas

        public Stream<GetReplicaResult> getAllReplicas​(String id)
        Reads from all available replicas and the active node and returns the results as a stream.

        Note that individual errors are ignored, so you can think of this API as a best effort approach which explicitly emphasises availability over consistency.

        Parameters:
        id - the document id which is used to uniquely identify it.
        Returns:
        a stream of results from the active and the replica.
        Throws:
        TimeoutException - if the operation times out before getting a result.
        CouchbaseException - for all other error reasons (acts as a base type and catch-all).
      • getAllReplicas

        public Stream<GetReplicaResult> getAllReplicas​(String id,
                                                       GetAllReplicasOptions options)
        Reads all available or one replica and returns the results as a stream with custom options.

        By default all available replicas and the active node will be asked and returned as an async stream. If configured differently in the options

        Parameters:
        id - the document id which is used to uniquely identify it.
        options - the custom options.
        Returns:
        a stream of results from the active and the replica depending on the options.
        Throws:
        TimeoutException - if the operation times out before getting a result.
        CouchbaseException - for all other error reasons (acts as a base type and catch-all).
      • getAnyReplica

        public GetReplicaResult getAnyReplica​(String id)
        Reads all available replicas, and returns the first found.
        Parameters:
        id - the document id which is used to uniquely identify it.
        Returns:
        the first available result, might be the active or a replica.
        Throws:
        DocumentUnretrievableException - no document retrievable with a successful status.
        TimeoutException - if the operation times out before getting a result.
        CouchbaseException - for all other error reasons (acts as a base type and catch-all).
      • getAnyReplica

        public GetReplicaResult getAnyReplica​(String id,
                                              GetAnyReplicaOptions options)
        Reads all available replicas, and returns the first found with custom options.
        Parameters:
        id - the document id which is used to uniquely identify it.
        options - the custom options.
        Returns:
        the first available result, might be the active or a replica.
        Throws:
        DocumentUnretrievableException - no document retrievable with a successful status.
        TimeoutException - if the operation times out before getting a result.
        CouchbaseException - for all other error reasons (acts as a base type and catch-all).
      • exists

        public ExistsResult exists​(String id)
        Checks if the given document ID exists on the active partition.
        Parameters:
        id - the document id which is used to uniquely identify it.
        Returns:
        a ExistsResult completing once loaded or failed.
        Throws:
        TimeoutException - if the operation times out before getting a result.
        CouchbaseException - for all other error reasons (acts as a base type and catch-all).
      • exists

        public ExistsResult exists​(String id,
                                   ExistsOptions options)
        Checks if the given document ID exists on the active partition with custom options.
        Parameters:
        id - the document id which is used to uniquely identify it.
        Returns:
        a ExistsResult completing once loaded or failed.
        Throws:
        TimeoutException - if the operation times out before getting a result.
        CouchbaseException - for all other error reasons (acts as a base type and catch-all).
      • remove

        public MutationResult remove​(String id,
                                     RemoveOptions options)
        Removes a Document from a collection with custom options.
        Parameters:
        id - the document id which is used to uniquely identify it.
        options - custom options to change the default behavior.
        Returns:
        a MutationResult once removed.
        Throws:
        DocumentNotFoundException - the given document id is not found in the collection.
        CasMismatchException - if the document has been concurrently modified on the server.
        TimeoutException - if the operation times out before getting a result.
        CouchbaseException - for all other error reasons (acts as a base type and catch-all).
      • insert

        public MutationResult insert​(String id,
                                     Object content)
        Inserts a full document which does not exist yet.
        Parameters:
        id - the document id which is used to uniquely identify it.
        content - the document content to insert.
        Returns:
        a MutationResult once inserted.
        Throws:
        DocumentExistsException - the given document id is already present in the collection.
        TimeoutException - if the operation times out before getting a result.
        CouchbaseException - for all other error reasons (acts as a base type and catch-all).
      • insert

        public MutationResult insert​(String id,
                                     Object content,
                                     InsertOptions options)
        Inserts a full document which does not exist yet with custom options.
        Parameters:
        id - the document id which is used to uniquely identify it.
        content - the document content to insert.
        options - custom options to customize the insert behavior.
        Returns:
        a MutationResult once inserted.
        Throws:
        DocumentExistsException - the given document id is already present in the collection.
        TimeoutException - if the operation times out before getting a result.
        CouchbaseException - for all other error reasons (acts as a base type and catch-all).
      • upsert

        public MutationResult upsert​(String id,
                                     Object content)
        Upserts a full document which might or might not exist yet.
        Parameters:
        id - the document id which is used to uniquely identify it.
        content - the document content to upsert.
        Returns:
        a MutationResult once upserted.
        Throws:
        TimeoutException - if the operation times out before getting a result.
        CouchbaseException - for all other error reasons (acts as a base type and catch-all).
      • upsert

        public MutationResult upsert​(String id,
                                     Object content,
                                     UpsertOptions options)
        Upserts a full document which might or might not exist yet with custom options.
        Parameters:
        id - the document id which is used to uniquely identify it.
        content - the document content to upsert.
        options - custom options to customize the upsert behavior.
        Returns:
        a MutationResult once upserted.
        Throws:
        TimeoutException - if the operation times out before getting a result.
        CouchbaseException - for all other error reasons (acts as a base type and catch-all).
      • replace

        public MutationResult replace​(String id,
                                      Object content)
        Replaces a full document which already exists.
        Parameters:
        id - the document id which is used to uniquely identify it.
        content - the document content to replace.
        Returns:
        a MutationResult once replaced.
        Throws:
        DocumentNotFoundException - the given document id is not found in the collection.
        CasMismatchException - if the document has been concurrently modified on the server.
        TimeoutException - if the operation times out before getting a result.
        CouchbaseException - for all other error reasons (acts as a base type and catch-all).
      • replace

        public MutationResult replace​(String id,
                                      Object content,
                                      ReplaceOptions options)
        Replaces a full document which already exists with custom options.
        Parameters:
        id - the document id which is used to uniquely identify it.
        content - the document content to replace.
        options - custom options to customize the replace behavior.
        Returns:
        a MutationResult once replaced.
        Throws:
        DocumentNotFoundException - the given document id is not found in the collection.
        CasMismatchException - if the document has been concurrently modified on the server.
        TimeoutException - if the operation times out before getting a result.
        CouchbaseException - for all other error reasons (acts as a base type and catch-all).
      • touch

        public MutationResult touch​(String id,
                                    Duration expiry)
        Updates the expiry of the document with the given id.
        Parameters:
        id - the document id which is used to uniquely identify it.
        expiry - the new expiry for the document.
        Returns:
        a MutationResult once the operation completes.
        Throws:
        DocumentNotFoundException - the given document id is not found in the collection.
        TimeoutException - if the operation times out before getting a result.
        CouchbaseException - for all other error reasons (acts as a base type and catch-all).
      • touch

        public MutationResult touch​(String id,
                                    Duration expiry,
                                    TouchOptions options)
        Updates the expiry of the document with the given id with custom options.
        Parameters:
        id - the document id which is used to uniquely identify it.
        expiry - the new expiry for the document.
        options - the custom options.
        Returns:
        a MutationResult once the operation completes.
        Throws:
        DocumentNotFoundException - the given document id is not found in the collection.
        TimeoutException - if the operation times out before getting a result.
        CouchbaseException - for all other error reasons (acts as a base type and catch-all).
      • unlock

        public void unlock​(String id,
                           long cas)
        Unlocks a document if it has been locked previously.
        Parameters:
        id - the document id which is used to uniquely identify it.
        cas - the CAS value which is needed to unlock it.
        Throws:
        DocumentNotFoundException - the given document id is not found in the collection.
        CasMismatchException - if the document has been concurrently modified on the server.
        TimeoutException - if the operation times out before getting a result.
        CouchbaseException - for all other error reasons (acts as a base type and catch-all).
      • unlock

        public void unlock​(String id,
                           long cas,
                           UnlockOptions options)
        Unlocks a document if it has been locked previously, with custom options.
        Parameters:
        id - the document id which is used to uniquely identify it.
        cas - the CAS value which is needed to unlock it.
        options - the options to customize.
        Throws:
        DocumentNotFoundException - the given document id is not found in the collection.
        CasMismatchException - if the document has been concurrently modified on the server.
        TimeoutException - if the operation times out before getting a result.
        CouchbaseException - for all other error reasons (acts as a base type and catch-all).
      • lookupIn

        public LookupInResult lookupIn​(String id,
                                       List<LookupInSpec> specs)
        Performs lookups to document fragments with default options.
        Parameters:
        id - the document id which is used to uniquely identify it.
        specs - the spec which specifies the type of lookups to perform.
        Returns:
        the LookupInResult once the lookup has been performed or failed.
        Throws:
        DocumentNotFoundException - the given document id is not found in the collection.
        TimeoutException - if the operation times out before getting a result.
        CouchbaseException - for all other error reasons (acts as a base type and catch-all).
      • lookupIn

        public LookupInResult lookupIn​(String id,
                                       List<LookupInSpec> specs,
                                       LookupInOptions options)
        Performs lookups to document fragments with custom options.
        Parameters:
        id - the document id which is used to uniquely identify it.
        specs - the spec which specifies the type of lookups to perform.
        options - custom options to modify the lookup options.
        Returns:
        the LookupInResult once the lookup has been performed or failed.
        Throws:
        DocumentNotFoundException - the given document id is not found in the collection.
        TimeoutException - if the operation times out before getting a result.
        CouchbaseException - for all other error reasons (acts as a base type and catch-all).
      • mutateIn

        public MutateInResult mutateIn​(String id,
                                       List<MutateInSpec> specs)
        Performs mutations to document fragments with default options.
        Parameters:
        id - the outer document ID.
        specs - the spec which specifies the type of mutations to perform.
        Returns:
        the MutateInResult once the mutation has been performed or failed.
        Throws:
        DocumentNotFoundException - the given document id is not found in the collection and replace mode is selected.
        DocumentExistsException - the given document id is already present in the collection and insert is was selected.
        TimeoutException - if the operation times out before getting a result.
        CouchbaseException - for all other error reasons (acts as a base type and catch-all).
      • mutateIn

        public MutateInResult mutateIn​(String id,
                                       List<MutateInSpec> specs,
                                       MutateInOptions options)
        Performs mutations to document fragments with custom options.
        Parameters:
        id - the outer document ID.
        specs - the spec which specifies the type of mutations to perform.
        options - custom options to modify the mutation options.
        Returns:
        the MutateInResult once the mutation has been performed or failed.
        Throws:
        DocumentNotFoundException - the given document id is not found in the collection and replace mode is selected.
        DocumentExistsException - the given document id is already present in the collection and insert is was selected.
        TimeoutException - if the operation times out before getting a result.
        CouchbaseException - for all other error reasons (acts as a base type and catch-all).
      • list

        public <T> List<T> list​(String id,
                                Class<T> entityType)
        Returns a CouchbaseArrayList backed by this collection, creating a new empty one if none exists already
        Parameters:
        id - the list's document id.
        entityType - the class of the values contained in the set
        Returns:
        a CouchbaseArrayList.
        Throws:
        TimeoutException - if the operation times out before getting a result.
        CouchbaseException - for all other error reasons (acts as a base type and catch-all).
      • set

        public <T> Set<T> set​(String id,
                              Class<T> entityType)
        Returns a CouchbaseArraySet backed by this collection, create a new empty one if none exists already.
        Parameters:
        id - the set's document id.
        entityType - the class of the values contained in the set
        Returns:
        a CouchbaseArraySet.
        Throws:
        TimeoutException - if the operation times out before getting a result.
        CouchbaseException - for all other error reasons (acts as a base type and catch-all).
      • set

        public <T> Set<T> set​(String id,
                              Class<T> entityType,
                              ArraySetOptions options)
        Returns a CouchbaseArraySet backed by this collection, create a new empty one if none exists already.
        Parameters:
        id - the set's document id.
        entityType - the class of the values contained in the set
        options - a ArraySetOptions to use for all operations on this instance of the set.
        Returns:
        a CouchbaseArraySet.
        Throws:
        TimeoutException - if the operation times out before getting a result.
        CouchbaseException - for all other error reasons (acts as a base type and catch-all).
      • map

        public <T> Map<String,​T> map​(String id,
                                           Class<T> entityType)
        Returns a CouchbaseMap backed by this collection, creating a new empty one if none exists already. This map will have String keys, and values of Class
        Parameters:
        id - the map's document id.
        entityType - the class of the values contained the map, the keys are Strings.
        Returns:
        a CouchbaseMap.
        Throws:
        TimeoutException - if the operation times out before getting a result.
        CouchbaseException - for all other error reasons (acts as a base type and catch-all).
      • map

        public <T> Map<String,​T> map​(String id,
                                           Class<T> entityType,
                                           MapOptions options)
        Returns a CouchbaseMap backed by this collection, creating a new empty one if none exists already. This map will have String keys, and values of Class
        Parameters:
        id - the map's document id.
        entityType - the class of the values contained the map, the keys are Strings.
        options - a MapOptions to use for all operations on this instance of the map.
        Returns:
        a CouchbaseMap.
        Throws:
        TimeoutException - if the operation times out before getting a result.
        CouchbaseException - for all other error reasons (acts as a base type and catch-all).
      • queue

        public <T> Queue<T> queue​(String id,
                                  Class<T> entityType)
        Returns a CouchbaseQueue backed by this collection, creating a new empty one if none exists.
        Parameters:
        id - the queue's document id.
        entityType - the class of the values contained in the queue.
        Returns:
        a CouchbaseQueue.
        Throws:
        TimeoutException - if the operation times out before getting a result.
        CouchbaseException - for all other error reasons (acts as a base type and catch-all).
      • queue

        public <T> Queue<T> queue​(String id,
                                  Class<T> entityType,
                                  QueueOptions options)
        Returns a CouchbaseQueue backed by this collection, creating a new empty one if none exists.
        Parameters:
        id - the queue's document id.
        entityType - the class of the values contained in the queue.
        options - a QueueOptions to use for all operations on this instance of the queue.
        Returns:
        a CouchbaseQueue.
        Throws:
        TimeoutException - if the operation times out before getting a result.
        CouchbaseException - for all other error reasons (acts as a base type and catch-all).