Class Collection
- java.lang.Object
-
- com.couchbase.client.java.Collection
-
public class Collection extends Object
TheCollectionprovides blocking, synchronous access to all collection APIs.If asynchronous access is needed, we recommend looking at the
ReactiveCollectionand if the last drop of performance is needed theAsyncCollection. This blocking API itself is just a small layer on top of theAsyncCollectionwhich blocks the current thread until the request completes with a response.- Since:
- 3.0.0
-
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description AsyncCollectionasync()Provides access to the underlyingAsyncCollection.BinaryCollectionbinary()Provides access to the binary APIs, not used for JSON documents.StringbucketName()Returns the name of the bucket associated with this collection.Corecore()Provides access to the underlyingCore.ClusterEnvironmentenvironment()Provides access to the underlyingClusterEnvironment.ExistsResultexists(String id)Checks if the given document ID exists on the active partition.ExistsResultexists(String id, ExistsOptions options)Checks if the given document ID exists on the active partition with custom options.GetResultget(String id)Fetches the full document from this collection.GetResultget(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.GetResultgetAndLock(String id, Duration lockTime)Fetches a full document and write-locks it for the given duration.GetResultgetAndLock(String id, Duration lockTime, GetAndLockOptions options)Fetches a full document and write-locks it for the given duration with custom options.GetResultgetAndTouch(String id, Duration expiry)Fetches a full document and resets its expiration time to the expiry provided.GetResultgetAndTouch(String id, Duration expiry, GetAndTouchOptions options)Fetches a full document and resets its expiration time to the expiry provided with custom options.GetReplicaResultgetAnyReplica(String id)Reads all available replicas, and returns the first found.GetReplicaResultgetAnyReplica(String id, GetAnyReplicaOptions options)Reads all available replicas, and returns the first found with custom options.MutationResultinsert(String id, Object content)Inserts a full document which does not exist yet.MutationResultinsert(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 aCouchbaseArrayListbacked by this collection, creating a new empty one if none exists already<T> List<T>list(String id, Class<T> entityType, ArrayListOptions options)Returns aCouchbaseArrayListbacked by this collection, creating a new empty one if none exists alreadyLookupInResultlookupIn(String id, List<LookupInSpec> specs)Performs lookups to document fragments with default options.LookupInResultlookupIn(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 aCouchbaseMapbacked 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 aCouchbaseMapbacked by this collection, creating a new empty one if none exists already.MutateInResultmutateIn(String id, List<MutateInSpec> specs)Performs mutations to document fragments with default options.MutateInResultmutateIn(String id, List<MutateInSpec> specs, MutateInOptions options)Performs mutations to document fragments with custom options.Stringname()Returns the name of this collection.CollectionQueryIndexManagerqueryIndexes()Provides access to query index management at the Collection level.<T> Queue<T>queue(String id, Class<T> entityType)Returns aCouchbaseQueuebacked by this collection, creating a new empty one if none exists.<T> Queue<T>queue(String id, Class<T> entityType, QueueOptions options)Returns aCouchbaseQueuebacked by this collection, creating a new empty one if none exists.ReactiveCollectionreactive()Provides access to the underlyingReactiveCollection.MutationResultremove(String id)Removes a Document from a collection.MutationResultremove(String id, RemoveOptions options)Removes a Document from a collection with custom options.MutationResultreplace(String id, Object content)Replaces a full document which already exists.MutationResultreplace(String id, Object content, ReplaceOptions options)Replaces a full document which already exists with custom options.Stream<ScanResult>scan(ScanType scanType)Returns a stream ofScanResultsperforming a Key-Value range scan with default options.Stream<ScanResult>scan(ScanType scanType, ScanOptions options)Returns a stream ofScanResultsperforming a Key-Value range scan with custom options.StringscopeName()Returns the name of the scope associated with this collection.<T> Set<T>set(String id, Class<T> entityType)Returns aCouchbaseArraySetbacked by this collection, create a new empty one if none exists already.<T> Set<T>set(String id, Class<T> entityType, ArraySetOptions options)Returns aCouchbaseArraySetbacked by this collection, create a new empty one if none exists already.MutationResulttouch(String id, Duration expiry)Updates the expiry of the document with the given id.MutationResulttouch(String id, Duration expiry, TouchOptions options)Updates the expiry of the document with the given id with custom options.voidunlock(String id, long cas)Unlocks a document if it has been locked previously.voidunlock(String id, long cas, UnlockOptions options)Unlocks a document if it has been locked previously, with custom options.MutationResultupsert(String id, Object content)Upserts a full document which might or might not exist yet.MutationResultupsert(String id, Object content, UpsertOptions options)Upserts a full document which might or might not exist yet with custom options.
-
-
-
Method Detail
-
async
public AsyncCollection async()
Provides access to the underlyingAsyncCollection.- Returns:
- returns the underlying
AsyncCollection.
-
reactive
public ReactiveCollection reactive()
Provides access to the underlyingReactiveCollection.- 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.
-
environment
public ClusterEnvironment environment()
Provides access to the underlyingClusterEnvironment.
-
binary
public BinaryCollection binary()
Provides access to the binary APIs, not used for JSON documents.- Returns:
- the
BinaryCollection.
-
queryIndexes
@Volatile public CollectionQueryIndexManager queryIndexes()
Provides access to query index management at the Collection level.
-
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
GetResultonce 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
GetResultonce 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
DurationlockTime. 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
GetResultonce 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
DurationlockTime. 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
GetResultonce 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
GetResultonce 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
GetResultonce 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
ExistsResultcompleting 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
ExistsResultcompleting 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
MutationResultonce 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
MutationResultonce 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
MutationResultonce 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
MutationResultonce 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
MutationResultonce 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
MutationResultonce 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
MutationResultonce 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
MutationResultonce 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
MutationResultonce 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
MutationResultonce 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
LookupInResultonce 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
LookupInResultonce 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
MutateInResultonce 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
MutateInResultonce 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 aCouchbaseArrayListbacked 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 aCouchbaseArrayListbacked 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 setoptions- aArrayListOptionsto 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 aCouchbaseArraySetbacked 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 aCouchbaseArraySetbacked 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 setoptions- aArraySetOptionsto 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 aCouchbaseMapbacked by this collection, creating a new empty one if none exists already. This map will haveStringkeys, and values of Class- Parameters:
id- the map's document id.entityType- the class of the values contained the map, the keys areStrings.- 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 aCouchbaseMapbacked by this collection, creating a new empty one if none exists already. This map will haveStringkeys, and values of Class- Parameters:
id- the map's document id.entityType- the class of the values contained the map, the keys areStrings.options- aMapOptionsto 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 aCouchbaseQueuebacked 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 aCouchbaseQueuebacked 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- aQueueOptionsto 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).
-
scan
@Volatile public Stream<ScanResult> scan(ScanType scanType)
Returns a stream ofScanResultsperforming a Key-Value range scan with default options.- Parameters:
scanType- the type or range scan to perform.- Returns:
- a stream of
ScanResults(potentially empty). - 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).
-
scan
@Volatile public Stream<ScanResult> scan(ScanType scanType, ScanOptions options)
Returns a stream ofScanResultsperforming a Key-Value range scan with custom options.- Parameters:
scanType- the type or range scan to perform.options- aScanOptionsto customize the behavior of the scan operation.- Returns:
- a stream of
ScanResults(potentially empty). - 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).
-
-