Package com.couchbase.client.java

Class Collection

java.lang.Object
com.couchbase.client.java.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 Details

    • async

      public AsyncCollection async()
      Provides access to the underlying AsyncCollection.
      Returns:
      returns the underlying AsyncCollection.

    • reactive

      public ReactiveCollection reactive()
      Provides access to the underlying ReactiveCollection.
      Returns:
      returns the underlying ReactiveCollection.

    • 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.

    • core

      @Volatile public Core core()
      Provides access to the underlying Core.

    • environment

      public ClusterEnvironment environment()
      Provides access to the underlying ClusterEnvironment.

    • binary

      public BinaryCollection binary()
      Provides access to the binary APIs, not used for JSON documents.
      Returns:
      the BinaryCollection.

    • 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.

      Note that the client does not enforce an upper limit on the Duration lockTime. The maximum lock time by default on the server is 30 seconds. Any value larger than 30 seconds will be capped down by the server to the default lock time, which is 15 seconds unless modified on the server side.

      Parameters:
      id - the document id which is used to uniquely identify it.
      lockTime - how long to write-lock the document for (any duration > 30s will be capped to server default of 15s).
      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.

      Note that the client does not enforce an upper limit on the Duration lockTime. The maximum lock time by default on the server is 30 seconds. Any value larger than 30 seconds will be capped down by the server to the default lock time, which is 15 seconds unless modified on the server side.

      Parameters:
      id - the document id which is used to uniquely identify it.
      lockTime - how long to write-lock the document for (any duration > 30s will be capped to server default of 15s).
      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)
      Removes a Document from a collection.
      Parameters:
      id - the document id which is used to uniquely identify it.
      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).

    • 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<T> 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<T>.
      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).

    • list

      public <T> List<T> list​(String id, Class<T> entityType, ArrayListOptions options)
      Returns a CouchbaseArrayList<T> 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
      options - a ArrayListOptions to use for all operations on this instance of the list.
      Returns:
      a CouchbaseArrayList<T>.
      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<T> 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<T>.
      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<T> 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<T>.
      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<T> 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<T>.
      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<T> 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<T>.
      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<T> 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<T>.
      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<T> 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<T>.
      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).