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 Summary

Modifier and Type	Method	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 with default options.
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 a full Document from a collection with default options.
GetResult	get(String id, GetOptions options)	Fetches a full Document from a 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.
GetResult	getAndLock(String id, Duration lockTime)	Fetches a full document and write-locks it for the given duration with default options.
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 value provided with default options.
GetResult	getAndTouch(String id, Duration expiry, GetAndTouchOptions options)	Fetches a full document and resets its expiration time to the value 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.
MutationResult	insert(String id, Object content)	Inserts a full document which does not exist yet with default options.
MutationResult	insert(String id, Object content, InsertOptions options)	Inserts a full document which does not exist yet with custom options.
<T> CouchbaseArrayList<T>	list(String id, Class<T> entityType)	Returns a CouchbaseArrayList backed by this collection, creating a new empty one if none exists already
<T> CouchbaseArrayList<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> CouchbaseMap<T>	map(String id, Class<T> entityType)	Returns a CouchbaseMap backed by this collection, creating a new empty one if none exists already.
<T> CouchbaseMap<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> CouchbaseQueue<T>	queue(String id, Class<T> entityType)	Returns a CouchbaseQueue backed by this collection, creating a new empty one if none exists.
<T> CouchbaseQueue<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 with default options.
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 with default options.
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> CouchbaseArraySet<T>	set(String id, Class<T> entityType)	Returns a CouchbaseArraySet backed by this collection, create a new empty one if none exists already.
<T> CouchbaseArraySet<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 with default options.
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, with default options.
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 with default options.
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

@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 a full Document from a collection with default options.

Parameters:

id - the document id which is used to uniquely identify it.

Returns:

a GetResult once the document has been loaded.

get

public GetResult get(String id,
                     GetOptions options)

Fetches a full 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 GetResult once the document has been loaded.

getAndLock

public GetResult getAndLock(String id,
                            Duration lockTime)

Fetches a full document and write-locks it for the given duration with default options.

Parameters:

id - the document id which is used to uniquely identify it.

lockTime - how long to lock the document for. Any values above 30 seconds will be treated as 30 seconds.

Returns:

a GetResult once the document has been loaded.

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. Any values above 30 seconds will be treated as 30 seconds.

options - custom options to change the default behavior.

Returns:

a GetResult once the document has been loaded.

getAndTouch

public GetResult getAndTouch(String id,
                             Duration expiry)

Fetches a full document and resets its expiration time to the value provided with default options.

Parameters:

id - the document id which is used to uniquely identify it.

expiry - the new expiration time for the document.

Returns:

a GetResult completing once loaded or failed.

getAndTouch

public GetResult getAndTouch(String id,
                             Duration expiry,
                             GetAndTouchOptions options)

Fetches a full document and resets its expiration time to the value 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 - custom options to change the default behavior.

Returns:

a GetResult completing once loaded or failed.

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.

Returns:

a stream of results from the active and the replica.

getAllReplicas

public Stream<GetReplicaResult> getAllReplicas(String id,
                                               GetAllReplicasOptions options)

Reads all available or one replica and returns the results as a stream.

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.

options - the custom options.

Returns:

a stream of results from the active and the replica depending on the options.

getAnyReplica

public GetReplicaResult getAnyReplica(String id)

Reads all available replicas, and returns the first found.

Parameters:

id - the document id.

Returns:

the first available replica.

getAnyReplica

public GetReplicaResult getAnyReplica(String id,
                                      GetAnyReplicaOptions options)

Reads all available replicas, and returns the first found.

Parameters:

id - the document id.

options - the custom options.

Returns:

the first available replica.

exists

public ExistsResult exists(String id)

Checks if the given document ID exists on the active partition with default options.

Parameters:

id - the document ID

Returns:

a ExistsResult completing once loaded or failed.

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

Returns:

a ExistsResult completing once loaded or failed.

remove

public MutationResult remove(String id)

Removes a Document from a collection with default options.

Parameters:

id - the id of the document to remove.

Returns:

a MutationResult once removed.

remove

public MutationResult remove(String id,
                             RemoveOptions options)

Removes a Document from a collection with custom options.

Parameters:

id - the id of the document to remove.

options - custom options to change the default behavior.

Returns:

a MutationResult once removed.

insert

public MutationResult insert(String id,
                             Object content)

Inserts a full document which does not exist yet with default options.

Parameters:

id - the document id to insert.

content - the document content to insert.

Returns:

a MutationResult once inserted.

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 to insert.

content - the document content to insert.

options - custom options to customize the insert behavior.

Returns:

a MutationResult once inserted.

upsert

public MutationResult upsert(String id,
                             Object content)

Upserts a full document which might or might not exist yet with default options.

Parameters:

id - the document id to upsert.

content - the document content to upsert.

Returns:

a MutationResult once upserted.

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 to upsert.

content - the document content to upsert.

options - custom options to customize the upsert behavior.

Returns:

a MutationResult once upserted.

replace

public MutationResult replace(String id,
                              Object content)

Replaces a full document which already exists with default options.

Parameters:

id - the document id to replace.

content - the document content to replace.

Returns:

a MutationResult once replaced.

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 to replace.

content - the document content to replace.

options - custom options to customize the replace behavior.

Returns:

a MutationResult once replaced.

touch

public MutationResult touch(String id,
                            Duration expiry)

Updates the expiry of the document with the given id with default options.

Parameters:

id - the id of the document to update.

expiry - the new expiry for the document.

Returns:

a MutationResult once the operation completes.

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 id of the document to update.

expiry - the new expiry for the document.

options - the custom options.

Returns:

a MutationResult once the operation completes.

unlock

public void unlock(String id,
                   long cas)

Unlocks a document if it has been locked previously, with default options.

Parameters:

id - the id of the document.

cas - the CAS value which is needed to unlock it.

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 id of the document.

cas - the CAS value which is needed to unlock it.

options - the options to customize.

lookupIn

public LookupInResult lookupIn(String id,
                               List<LookupInSpec> specs)

Performs lookups to document fragments with default options.

Parameters:

id - the outer document ID.

specs - the spec which specifies the type of lookups to perform.

Returns:

the LookupInResult once the lookup has been performed or failed.

lookupIn

public LookupInResult lookupIn(String id,
                               List<LookupInSpec> specs,
                               LookupInOptions options)

Performs lookups to document fragments with custom options.

Parameters:

id - the outer document ID.

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.

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.

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.

list

public <T> CouchbaseArrayList<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.

list

public <T> CouchbaseArrayList<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. \

set

public <T> CouchbaseArraySet<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.

set

public <T> CouchbaseArraySet<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.

map

public <T> CouchbaseMap<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.

map

public <T> CouchbaseMap<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.

queue

public <T> CouchbaseQueue<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.

queue

public <T> CouchbaseQueue<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.