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 Summary

Modifier and Type	Method and Description
AsyncCollection	async() Provides access to the underlying AsyncCollection.
BinaryCollection	binary() Provides access to the binary APIs, not used for JSON documents.
String	bucketName() Returns the name of the bucket associated with this collection.
Core	core() Provides access to the underlying Core.
ClusterEnvironment	environment() Provides access to the underlying ClusterEnvironment.
ExistsResult	exists(String id) Checks if the given document ID exists on the active partition.
ExistsResult	exists(String id, ExistsOptions options) Checks if the given document ID exists on the active partition with custom options.
GetResult	get(String id) Fetches the full document from this collection.
GetResult	get(String id, GetOptions options) Fetches the full document from this collection with custom options.
Stream<GetReplicaResult>	getAllReplicas(String id) Reads from all available replicas and the active node and returns the results as a stream.
Stream<GetReplicaResult>	getAllReplicas(String id, GetAllReplicasOptions options) Reads all available or one replica and returns the results as a stream with custom options.
GetResult	getAndLock(String id, Duration lockTime) Fetches a full document and write-locks it for the given duration.
GetResult	getAndLock(String id, Duration lockTime, GetAndLockOptions options) Fetches a full document and write-locks it for the given duration with custom options.
GetResult	getAndTouch(String id, Duration expiry) Fetches a full document and resets its expiration time to the expiry provided.
GetResult	getAndTouch(String id, Duration expiry, GetAndTouchOptions options) Fetches a full document and resets its expiration time to the expiry provided with custom options.
GetReplicaResult	getAnyReplica(String id) Reads all available replicas, and returns the first found.
GetReplicaResult	getAnyReplica(String id, GetAnyReplicaOptions options) Reads all available replicas, and returns the first found with custom options.
MutationResult	insert(String id, Object content) Inserts a full document which does not exist yet.
MutationResult	insert(String id, Object content, InsertOptions options) Inserts a full document which does not exist yet with custom options.
<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
<T> List<T>	list(String id, Class<T> entityType, ArrayListOptions options) Returns a CouchbaseArrayList backed by this collection, creating a new empty one if none exists already
LookupInResult	lookupIn(String id, List<LookupInSpec> specs) Performs lookups to document fragments with default options.
LookupInResult	lookupIn(String id, List<LookupInSpec> specs, LookupInOptions options) Performs lookups to document fragments with custom options.
<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.
<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.
MutateInResult	mutateIn(String id, List<MutateInSpec> specs) Performs mutations to document fragments with default options.
MutateInResult	mutateIn(String id, List<MutateInSpec> specs, MutateInOptions options) Performs mutations to document fragments with custom options.
String	name() Returns the name of this collection.
<T> Queue<T>	queue(String id, Class<T> entityType) Returns a CouchbaseQueue backed by this collection, creating a new empty one if none exists.
<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.
ReactiveCollection	reactive() Provides access to the underlying ReactiveCollection.
MutationResult	remove(String id) Removes a Document from a collection.
MutationResult	remove(String id, RemoveOptions options) Removes a Document from a collection with custom options.
MutationResult	replace(String id, Object content) Replaces a full document which already exists.
MutationResult	replace(String id, Object content, ReplaceOptions options) Replaces a full document which already exists with custom options.
String	scopeName() Returns the name of the scope associated with this collection.
<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.
<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.
MutationResult	touch(String id, Duration expiry) Updates the expiry of the document with the given id.
MutationResult	touch(String id, Duration expiry, TouchOptions options) Updates the expiry of the document with the given id with custom options.
void	unlock(String id, long cas) Unlocks a document if it has been locked previously.
void	unlock(String id, long cas, UnlockOptions options) Unlocks a document if it has been locked previously, with custom options.
MutationResult	upsert(String id, Object content) Upserts a full document which might or might not exist yet.
MutationResult	upsert(String id, Object content, UpsertOptions options) Upserts a full document which might or might not exist yet with custom options.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

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

@Stability.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 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).

list

public <T> List<T> list(String id,
                        Class<T> entityType,
                        ArrayListOptions options)

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

options - a ArrayListOptions to use for all operations on this instance of the list.

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