@InterfaceStability.Committed @InterfaceAudience.Public public class AsyncMutateInBuilder extends Object
execute()
method. Operations are performed asynchronously (see MutateInBuilder
for a synchronous
version).
Instances of this builder should be obtained through AsyncBucket.mutateIn(String)
rather than directly
constructed.Modifier and Type | Field and Description |
---|---|
protected long |
cas |
protected String |
docId |
protected int |
expiry |
protected boolean |
insertDocument |
protected List<MutationSpec> |
mutationSpecs |
protected PersistTo |
persistTo |
protected ReplicateTo |
replicateTo |
protected boolean |
upsertDocument |
Constructor and Description |
---|
AsyncMutateInBuilder(ClusterFacade core,
String bucketName,
CouchbaseEnvironment environment,
FragmentTranscoder transcoder,
String docId)
Instances of this builder should be obtained through
AsyncBucket.mutateIn(String) rather than directly
constructed. |
Modifier and Type | Method and Description |
---|---|
<T> AsyncMutateInBuilder |
arrayAddUnique(String path,
T value)
Insert a value in an existing array only if the value
isn't already contained in the array (by way of string comparison).
|
<T> AsyncMutateInBuilder |
arrayAddUnique(String path,
T value,
boolean createPath)
Deprecated.
Use
arrayAddUnique(String, Object, SubdocOptionsBuilder) instead. |
<T> AsyncMutateInBuilder |
arrayAddUnique(String path,
T value,
SubdocOptionsBuilder optionsBuilder)
Insert a value in an existing array only if the value
isn't already contained in the array (by way of string comparison).
|
<T> AsyncMutateInBuilder |
arrayAppend(String path,
T value)
Append to an existing array, pushing the value to the back/last position in
the array.
|
<T> AsyncMutateInBuilder |
arrayAppend(String path,
T value,
boolean createPath)
Deprecated.
Use
arrayAppend(String, Object, SubdocOptionsBuilder) instead. |
<T> AsyncMutateInBuilder |
arrayAppend(String path,
T value,
SubdocOptionsBuilder optionsBuilder)
Append to an existing array, pushing the value to the back/last position in
the array.
|
<T> AsyncMutateInBuilder |
arrayAppendAll(String path,
Collection<T> values,
boolean createPath)
Deprecated.
|
<T> AsyncMutateInBuilder |
arrayAppendAll(String path,
Collection<T> values,
SubdocOptionsBuilder optionsBuilder)
Append multiple values at once in an existing array, pushing all values in the collection's iteration order to
the back/end of the array.
|
<T> AsyncMutateInBuilder |
arrayAppendAll(String path,
T... values)
Append multiple values at once in an existing array, pushing all values to the back/end of the array.
|
<T> AsyncMutateInBuilder |
arrayInsert(String path,
T value)
Insert into an existing array at a specific position
(denoted in the path, eg.
|
<T> AsyncMutateInBuilder |
arrayInsert(String path,
T value,
SubdocOptionsBuilder optionsBuilder)
Insert into an existing array at a specific position
(denoted in the path, eg.
|
<T> AsyncMutateInBuilder |
arrayInsertAll(String path,
Collection<T> values)
Insert multiple values at once in an existing array at a specified position (denoted in the
path, eg.
|
<T> AsyncMutateInBuilder |
arrayInsertAll(String path,
Collection<T> values,
SubdocOptionsBuilder optionsBuilder)
Insert multiple values at once in an existing array at a specified position (denoted in the
path, eg.
|
<T> AsyncMutateInBuilder |
arrayInsertAll(String path,
T... values)
Insert multiple values at once in an existing array at a specified position (denoted in the
path, eg.
|
<T> AsyncMutateInBuilder |
arrayPrepend(String path,
T value)
Prepend to an existing array, pushing the value to the front/first position in
the array.
|
<T> AsyncMutateInBuilder |
arrayPrepend(String path,
T value,
boolean createPath)
Deprecated.
Use
arrayPrepend(String, Object, SubdocOptionsBuilder) instead. |
<T> AsyncMutateInBuilder |
arrayPrepend(String path,
T value,
SubdocOptionsBuilder optionsBuilder)
Prepend to an existing array, pushing the value to the front/first position in
the array.
|
<T> AsyncMutateInBuilder |
arrayPrependAll(String path,
Collection<T> values,
boolean createPath)
Deprecated.
|
<T> AsyncMutateInBuilder |
arrayPrependAll(String path,
Collection<T> values,
SubdocOptionsBuilder optionsBuilder)
Prepend multiple values at once in an existing array, pushing all values in the collection's iteration order to
the front/start of the array.
|
<T> AsyncMutateInBuilder |
arrayPrependAll(String path,
T... values)
Prepend multiple values at once in an existing array, pushing all values to the front/start of the array.
|
AsyncMutateInBuilder |
counter(String path,
long delta)
Increment/decrement a numerical fragment in a JSON document.
|
AsyncMutateInBuilder |
counter(String path,
long delta,
boolean createPath)
Deprecated.
Use
counter(String, long, SubdocOptionsBuilder) instead. |
AsyncMutateInBuilder |
counter(String path,
long delta,
SubdocOptionsBuilder optionsBuilder)
Increment/decrement a numerical fragment in a JSON document.
|
AsyncMutateInBuilder |
createDocument(boolean createDocument)
Deprecated.
Use
upsertDocument(boolean) instead. |
protected rx.Observable<DocumentFragment<Mutation>> |
doMultiMutate(long timeout,
TimeUnit timeUnit) |
protected rx.Observable<DocumentFragment<Mutation>> |
doSingleMutate(MutationSpec spec,
long timeout,
TimeUnit timeUnit) |
rx.Observable<DocumentFragment<Mutation>> |
execute()
Perform several
mutation operations inside a single existing JSON document . |
rx.Observable<DocumentFragment<Mutation>> |
execute(long timeout,
TimeUnit timeUnit)
Perform several
mutation operations inside a single existing JSON document . |
rx.Observable<DocumentFragment<Mutation>> |
execute(PersistTo persistTo)
Perform several
mutation operations inside a single existing JSON document
and watch for durability requirements. |
rx.Observable<DocumentFragment<Mutation>> |
execute(PersistTo persistTo,
long timeout,
TimeUnit timeUnit)
Perform several
mutation operations inside a single existing JSON document
and watch for durability requirements. |
rx.Observable<DocumentFragment<Mutation>> |
execute(PersistTo persistTo,
ReplicateTo replicateTo)
Perform several
mutation operations inside a single existing JSON document
and watch for durability requirements. |
rx.Observable<DocumentFragment<Mutation>> |
execute(PersistTo persistTo,
ReplicateTo replicateTo,
long timeout,
TimeUnit timeUnit)
Perform several
mutation operations inside a single existing JSON document
and watch for durability requirements. |
rx.Observable<DocumentFragment<Mutation>> |
execute(ReplicateTo replicateTo)
Perform several
mutation operations inside a single existing JSON document
and watch for durability requirements. |
rx.Observable<DocumentFragment<Mutation>> |
execute(ReplicateTo replicateTo,
long timeout,
TimeUnit timeUnit)
Perform several
mutation operations inside a single existing JSON document
and watch for durability requirements. |
<T> AsyncMutateInBuilder |
insert(String path,
T fragment)
Insert a fragment, provided the last element of the path doesn't exist.
|
<T> AsyncMutateInBuilder |
insert(String path,
T fragment,
boolean createPath)
Deprecated.
Use
insert(String, Object, SubdocOptionsBuilder) instead. |
<T> AsyncMutateInBuilder |
insert(String path,
T fragment,
SubdocOptionsBuilder optionsBuilder)
Insert a fragment, provided the last element of the path doesn't exist.
|
AsyncMutateInBuilder |
insertDocument(boolean insertDocument)
Set insertDocument to true, if the document has to be created only if it does not exist
|
<T> AsyncMutateInBuilder |
remove(String path)
Remove an entry in a JSON document (scalar, array element, dictionary entry,
whole array or dictionary, depending on the path).
|
<T> AsyncMutateInBuilder |
remove(String path,
SubdocOptionsBuilder optionsBuilder)
Remove an entry in a JSON document (scalar, array element, dictionary entry,
whole array or dictionary, depending on the path).
|
<T> AsyncMutateInBuilder |
replace(String path,
T fragment)
Replace an existing value by the given fragment.
|
<T> AsyncMutateInBuilder |
replace(String path,
T fragment,
SubdocOptionsBuilder optionsBuilder)
Replace an existing value by the given fragment.
|
String |
toString() |
AsyncMutateInBuilder |
upsert(JsonObject content)
Upsert a full JSON document.
|
<T> AsyncMutateInBuilder |
upsert(String path,
T fragment)
Insert a fragment, replacing the old value if the path exists.
|
<T> AsyncMutateInBuilder |
upsert(String path,
T fragment,
boolean createPath)
Deprecated.
Use
upsert(String, Object, SubdocOptionsBuilder) instead. |
<T> AsyncMutateInBuilder |
upsert(String path,
T fragment,
SubdocOptionsBuilder optionsBuilder)
Insert a fragment, replacing the old value if the path exists.
|
AsyncMutateInBuilder |
upsertDocument(boolean upsertDocument)
Set upsertDocument to true, if the document has to be created
|
AsyncMutateInBuilder |
withCas(long cas)
Apply the whole mutation using optimistic locking, checking against the provided CAS value.
|
AsyncMutateInBuilder |
withDurability(PersistTo persistTo)
Set a persistence durability constraint for the whole mutation.
|
AsyncMutateInBuilder |
withDurability(PersistTo persistTo,
ReplicateTo replicateTo)
Set both a persistence and a replication durability constraints for the whole mutation.
|
AsyncMutateInBuilder |
withDurability(ReplicateTo replicateTo)
Set a replication durability constraint for the whole mutation.
|
AsyncMutateInBuilder |
withExpiry(int expiry)
Change the expiry of the enclosing document as part of the mutation.
|
protected final String docId
protected final List<MutationSpec> mutationSpecs
protected int expiry
protected long cas
protected PersistTo persistTo
protected ReplicateTo replicateTo
protected boolean upsertDocument
protected boolean insertDocument
@InterfaceAudience.Private public AsyncMutateInBuilder(ClusterFacade core, String bucketName, CouchbaseEnvironment environment, FragmentTranscoder transcoder, String docId)
AsyncBucket.mutateIn(String)
rather than directly
constructed.public rx.Observable<DocumentFragment<Mutation>> execute()
mutation
operations inside a single existing JSON document
.
The list of mutations and paths to mutate in the JSON is added through builder methods like
arrayInsert(String, Object)
.
Multi-mutations are applied as a whole, atomically at the document level. That means that if one of the mutations
fails, none of the mutations are applied. Otherwise, all mutations can be considered successful and the whole
operation will receive a DocumentFragment
with the updated cas (and optionally MutationToken
).
The subdocument API has the benefit of only transmitting the fragment of the document you want to mutate
on the wire, instead of the whole document.
This Observable most notable error conditions are:
- The enclosing document does not exist: DocumentDoesNotExistException
- The enclosing document is not JSON: DocumentNotJsonException
- No mutation was defined through the builder API: IllegalArgumentException
- A mutation spec couldn't be encoded and the whole operation was cancelled: TranscodingException
- The multi-mutation failed: MultiMutationException
- CAS was provided but optimistic locking failed: CASMismatchException
When receiving a MultiMutationException
, one can inspect the exception to find the zero-based index and
error status code
of the first failing Mutation
. Subsequent mutations may have
also failed had they been attempted, but a single spec failing causes the whole operation to be cancelled.
Other top-level error conditions are similar to those encountered during a document-level AsyncBucket.replace(Document)
.Observable
of a single DocumentFragment
(if successful) containing updated cas metadata.
Note that some individual results could also bear a value, like counter operations.public rx.Observable<DocumentFragment<Mutation>> execute(long timeout, TimeUnit timeUnit)
mutation
operations inside a single existing JSON document
.
The list of mutations and paths to mutate in the JSON is added through builder methods like
arrayInsert(String, Object)
.
Multi-mutations are applied as a whole, atomically at the document level. That means that if one of the mutations
fails, none of the mutations are applied. Otherwise, all mutations can be considered successful and the whole
operation will receive a DocumentFragment
with the updated cas (and optionally MutationToken
).
The subdocument API has the benefit of only transmitting the fragment of the document you want to mutate
on the wire, instead of the whole document.
This Observable most notable error conditions are:
- The enclosing document does not exist: DocumentDoesNotExistException
- The enclosing document is not JSON: DocumentNotJsonException
- No mutation was defined through the builder API: IllegalArgumentException
- A mutation spec couldn't be encoded and the whole operation was cancelled: TranscodingException
- The multi-mutation failed: MultiMutationException
- CAS was provided but optimistic locking failed: CASMismatchException
When receiving a MultiMutationException
, one can inspect the exception to find the zero-based index and
error status code
of the first failing Mutation
. Subsequent mutations may have
also failed had they been attempted, but a single spec failing causes the whole operation to be cancelled.
Other top-level error conditions are similar to those encountered during a document-level AsyncBucket.replace(Document)
.timeout
- the specific timeout to apply for the operation.timeUnit
- the time unit for the timeout.Observable
of a single DocumentFragment
(if successful) containing updated cas metadata.
Note that some individual results could also bear a value, like counter operations.public rx.Observable<DocumentFragment<Mutation>> execute(PersistTo persistTo, ReplicateTo replicateTo)
mutation
operations inside a single existing JSON document
and watch for durability requirements.
The list of mutations and paths to mutate in the JSON is added through builder methods like
arrayInsert(String, Object)
.
Multi-mutations are applied as a whole, atomically at the document level. That means that if one of the mutations
fails, none of the mutations are applied. Otherwise, all mutations can be considered successful and the whole
operation will receive a DocumentFragment
with the updated cas (and optionally MutationToken
).
The subdocument API has the benefit of only transmitting the fragment of the document you want to mutate
on the wire, instead of the whole document.
This Observable most notable error conditions are:
- The enclosing document does not exist: DocumentDoesNotExistException
- The enclosing document is not JSON: DocumentNotJsonException
- No mutation was defined through the builder API: IllegalArgumentException
- A mutation spec couldn't be encoded and the whole operation was cancelled: TranscodingException
- The multi-mutation failed: MultiMutationException
- The durability constraint could not be fulfilled because of a temporary or persistent problem: DurabilityException
- CAS was provided but optimistic locking failed: CASMismatchException
When receiving a MultiMutationException
, one can inspect the exception to find the zero-based index and
error status code
of the first failing Mutation
. Subsequent mutations may have
also failed had they been attempted, but a single spec failing causes the whole operation to be cancelled.
Other top-level error conditions are similar to those encountered during a document-level AsyncBucket.replace(Document)
.
A DurabilityException
typically happens if the given amount of replicas needed to fulfill the durability
requirement cannot be met because either the bucket does not have enough replicas configured or they are not
available in a failover event. As an example, if one replica is configured and ReplicateTo.TWO
is used,
the observable is errored with a DurabilityException
. The same can happen if one replica is configured,
but one node has been failed over and not yet rebalanced (hence, on a subset of the partitions there is no
replica available). **It is important to understand that the original execute has already happened, so the actual
execute and the watching for durability requirements are two separate tasks internally.**persistTo
- the persistence requirement to watch.replicateTo
- the replication requirement to watch.Observable
of a single DocumentFragment
(if successful) containing updated cas metadata.
Note that some individual results could also bear a value, like counter operations.public rx.Observable<DocumentFragment<Mutation>> execute(PersistTo persistTo, ReplicateTo replicateTo, long timeout, TimeUnit timeUnit)
mutation
operations inside a single existing JSON document
and watch for durability requirements.
The list of mutations and paths to mutate in the JSON is added through builder methods like
arrayInsert(String, Object)
.
Multi-mutations are applied as a whole, atomically at the document level. That means that if one of the mutations
fails, none of the mutations are applied. Otherwise, all mutations can be considered successful and the whole
operation will receive a DocumentFragment
with the updated cas (and optionally MutationToken
).
The subdocument API has the benefit of only transmitting the fragment of the document you want to mutate
on the wire, instead of the whole document.
This Observable most notable error conditions are:
- The enclosing document does not exist: DocumentDoesNotExistException
- The enclosing document is not JSON: DocumentNotJsonException
- No mutation was defined through the builder API: IllegalArgumentException
- A mutation spec couldn't be encoded and the whole operation was cancelled: TranscodingException
- The multi-mutation failed: MultiMutationException
- The durability constraint could not be fulfilled because of a temporary or persistent problem: DurabilityException
- CAS was provided but optimistic locking failed: CASMismatchException
When receiving a MultiMutationException
, one can inspect the exception to find the zero-based index and
error status code
of the first failing Mutation
. Subsequent mutations may have
also failed had they been attempted, but a single spec failing causes the whole operation to be cancelled.
Other top-level error conditions are similar to those encountered during a document-level AsyncBucket.replace(Document)
.
A DurabilityException
typically happens if the given amount of replicas needed to fulfill the durability
requirement cannot be met because either the bucket does not have enough replicas configured or they are not
available in a failover event. As an example, if one replica is configured and ReplicateTo.TWO
is used,
the observable is errored with a DurabilityException
. The same can happen if one replica is configured,
but one node has been failed over and not yet rebalanced (hence, on a subset of the partitions there is no
replica available). **It is important to understand that the original execute has already happened, so the actual
execute and the watching for durability requirements are two separate tasks internally.**persistTo
- the persistence requirement to watch.replicateTo
- the replication requirement to watch.timeout
- the specific timeout to apply for the operation.timeUnit
- the time unit for the timeout.Observable
of a single DocumentFragment
(if successful) containing updated cas metadata.
Note that some individual results could also bear a value, like counter operations.public rx.Observable<DocumentFragment<Mutation>> execute(PersistTo persistTo)
mutation
operations inside a single existing JSON document
and watch for durability requirements.
The list of mutations and paths to mutate in the JSON is added through builder methods like
arrayInsert(String, Object)
.
Multi-mutations are applied as a whole, atomically at the document level. That means that if one of the mutations
fails, none of the mutations are applied. Otherwise, all mutations can be considered successful and the whole
operation will receive a DocumentFragment
with the updated cas (and optionally MutationToken
).
The subdocument API has the benefit of only transmitting the fragment of the document you want to mutate
on the wire, instead of the whole document.
This Observable most notable error conditions are:
- The enclosing document does not exist: DocumentDoesNotExistException
- The enclosing document is not JSON: DocumentNotJsonException
- No mutation was defined through the builder API: IllegalArgumentException
- A mutation spec couldn't be encoded and the whole operation was cancelled: TranscodingException
- The multi-mutation failed: MultiMutationException
- The durability constraint could not be fulfilled because of a temporary or persistent problem: DurabilityException
- CAS was provided but optimistic locking failed: CASMismatchException
When receiving a MultiMutationException
, one can inspect the exception to find the zero-based index and
error status code
of the first failing Mutation
. Subsequent mutations may have
also failed had they been attempted, but a single spec failing causes the whole operation to be cancelled.
Other top-level error conditions are similar to those encountered during a document-level AsyncBucket.replace(Document)
.
A DurabilityException
typically happens if the given amount of replicas needed to fulfill the durability
requirement cannot be met because either the bucket does not have enough replicas configured or they are not
available in a failover event. As an example, if one replica is configured and ReplicateTo.TWO
is used,
the observable is errored with a DurabilityException
. The same can happen if one replica is configured,
but one node has been failed over and not yet rebalanced (hence, on a subset of the partitions there is no
replica available). **It is important to understand that the original execute has already happened, so the actual
execute and the watching for durability requirements are two separate tasks internally.**persistTo
- the persistence requirement to watch.Observable
of a single DocumentFragment
(if successful) containing updated cas metadata.
Note that some individual results could also bear a value, like counter operations.public rx.Observable<DocumentFragment<Mutation>> execute(PersistTo persistTo, long timeout, TimeUnit timeUnit)
mutation
operations inside a single existing JSON document
and watch for durability requirements.
The list of mutations and paths to mutate in the JSON is added through builder methods like
arrayInsert(String, Object)
.
Multi-mutations are applied as a whole, atomically at the document level. That means that if one of the mutations
fails, none of the mutations are applied. Otherwise, all mutations can be considered successful and the whole
operation will receive a DocumentFragment
with the updated cas (and optionally MutationToken
).
The subdocument API has the benefit of only transmitting the fragment of the document you want to mutate
on the wire, instead of the whole document.
This Observable most notable error conditions are:
- The enclosing document does not exist: DocumentDoesNotExistException
- The enclosing document is not JSON: DocumentNotJsonException
- No mutation was defined through the builder API: IllegalArgumentException
- A mutation spec couldn't be encoded and the whole operation was cancelled: TranscodingException
- The multi-mutation failed: MultiMutationException
- The durability constraint could not be fulfilled because of a temporary or persistent problem: DurabilityException
- CAS was provided but optimistic locking failed: CASMismatchException
When receiving a MultiMutationException
, one can inspect the exception to find the zero-based index and
error status code
of the first failing Mutation
. Subsequent mutations may have
also failed had they been attempted, but a single spec failing causes the whole operation to be cancelled.
Other top-level error conditions are similar to those encountered during a document-level AsyncBucket.replace(Document)
.
A DurabilityException
typically happens if the given amount of replicas needed to fulfill the durability
requirement cannot be met because either the bucket does not have enough replicas configured or they are not
available in a failover event. As an example, if one replica is configured and ReplicateTo.TWO
is used,
the observable is errored with a DurabilityException
. The same can happen if one replica is configured,
but one node has been failed over and not yet rebalanced (hence, on a subset of the partitions there is no
replica available). **It is important to understand that the original execute has already happened, so the actual
execute and the watching for durability requirements are two separate tasks internally.**persistTo
- the persistence requirement to watch.timeout
- the specific timeout to apply for the operation.timeUnit
- the time unit for the timeout.Observable
of a single DocumentFragment
(if successful) containing updated cas metadata.
Note that some individual results could also bear a value, like counter operations.public rx.Observable<DocumentFragment<Mutation>> execute(ReplicateTo replicateTo)
mutation
operations inside a single existing JSON document
and watch for durability requirements.
The list of mutations and paths to mutate in the JSON is added through builder methods like
arrayInsert(String, Object)
.
Multi-mutations are applied as a whole, atomically at the document level. That means that if one of the mutations
fails, none of the mutations are applied. Otherwise, all mutations can be considered successful and the whole
operation will receive a DocumentFragment
with the updated cas (and optionally MutationToken
).
The subdocument API has the benefit of only transmitting the fragment of the document you want to mutate
on the wire, instead of the whole document.
This Observable most notable error conditions are:
- The enclosing document does not exist: DocumentDoesNotExistException
- The enclosing document is not JSON: DocumentNotJsonException
- No mutation was defined through the builder API: IllegalArgumentException
- A mutation spec couldn't be encoded and the whole operation was cancelled: TranscodingException
- The multi-mutation failed: MultiMutationException
- The durability constraint could not be fulfilled because of a temporary or persistent problem: DurabilityException
- CAS was provided but optimistic locking failed: CASMismatchException
When receiving a MultiMutationException
, one can inspect the exception to find the zero-based index and
error status code
of the first failing Mutation
. Subsequent mutations may have
also failed had they been attempted, but a single spec failing causes the whole operation to be cancelled.
Other top-level error conditions are similar to those encountered during a document-level AsyncBucket.replace(Document)
.
A DurabilityException
typically happens if the given amount of replicas needed to fulfill the durability
requirement cannot be met because either the bucket does not have enough replicas configured or they are not
available in a failover event. As an example, if one replica is configured and ReplicateTo.TWO
is used,
the observable is errored with a DurabilityException
. The same can happen if one replica is configured,
but one node has been failed over and not yet rebalanced (hence, on a subset of the partitions there is no
replica available). **It is important to understand that the original execute has already happened, so the actual
execute and the watching for durability requirements are two separate tasks internally.**replicateTo
- the replication requirement to watch.Observable
of a single DocumentFragment
(if successful) containing updated cas metadata.
Note that some individual results could also bear a value, like counter operations.public rx.Observable<DocumentFragment<Mutation>> execute(ReplicateTo replicateTo, long timeout, TimeUnit timeUnit)
mutation
operations inside a single existing JSON document
and watch for durability requirements.
The list of mutations and paths to mutate in the JSON is added through builder methods like
arrayInsert(String, Object)
.
Multi-mutations are applied as a whole, atomically at the document level. That means that if one of the mutations
fails, none of the mutations are applied. Otherwise, all mutations can be considered successful and the whole
operation will receive a DocumentFragment
with the updated cas (and optionally MutationToken
).
The subdocument API has the benefit of only transmitting the fragment of the document you want to mutate
on the wire, instead of the whole document.
This Observable most notable error conditions are:
- The enclosing document does not exist: DocumentDoesNotExistException
- The enclosing document is not JSON: DocumentNotJsonException
- No mutation was defined through the builder API: IllegalArgumentException
- A mutation spec couldn't be encoded and the whole operation was cancelled: TranscodingException
- The multi-mutation failed: MultiMutationException
- The durability constraint could not be fulfilled because of a temporary or persistent problem: DurabilityException
- CAS was provided but optimistic locking failed: CASMismatchException
When receiving a MultiMutationException
, one can inspect the exception to find the zero-based index and
error status code
of the first failing Mutation
. Subsequent mutations may have
also failed had they been attempted, but a single spec failing causes the whole operation to be cancelled.
Other top-level error conditions are similar to those encountered during a document-level AsyncBucket.replace(Document)
.
A DurabilityException
typically happens if the given amount of replicas needed to fulfill the durability
requirement cannot be met because either the bucket does not have enough replicas configured or they are not
available in a failover event. As an example, if one replica is configured and ReplicateTo.TWO
is used,
the observable is errored with a DurabilityException
. The same can happen if one replica is configured,
but one node has been failed over and not yet rebalanced (hence, on a subset of the partitions there is no
replica available). **It is important to understand that the original execute has already happened, so the actual
execute and the watching for durability requirements are two separate tasks internally.**replicateTo
- the replication requirement to watch.timeout
- the specific timeout to apply for the operation.timeUnit
- the time unit for the timeout.Observable
of a single DocumentFragment
(if successful) containing updated cas metadata.
Note that some individual results could also bear a value, like counter operations.public AsyncMutateInBuilder withExpiry(int expiry)
expiry
- the new expiry to apply (not setting it will disable expiration
for the full document)public AsyncMutateInBuilder withCas(long cas)
cas
- the CAS to compare the enclosing document to.public AsyncMutateInBuilder withDurability(PersistTo persistTo)
persistTo
- the persistence durability constraint to observe.public AsyncMutateInBuilder withDurability(ReplicateTo replicateTo)
replicateTo
- the replication durability constraint to observe.public AsyncMutateInBuilder withDurability(PersistTo persistTo, ReplicateTo replicateTo)
persistTo
- the persistence durability constraint to observe.replicateTo
- the replication durability constraint to observe.@Deprecated public AsyncMutateInBuilder createDocument(boolean createDocument)
upsertDocument(boolean)
instead.createDocument
- true to create document.public AsyncMutateInBuilder upsertDocument(boolean upsertDocument)
upsertDocument
- true to create document.@InterfaceStability.Committed public AsyncMutateInBuilder insertDocument(boolean insertDocument)
insertDocument
- true to insert document.public <T> AsyncMutateInBuilder replace(String path, T fragment)
path
- the path where the value to replace is.fragment
- the new value.public <T> AsyncMutateInBuilder replace(String path, T fragment, SubdocOptionsBuilder optionsBuilder)
path
- the path where the value to replace is.fragment
- the new value.optionsBuilder
- SubdocOptionsBuilder
@Deprecated public <T> AsyncMutateInBuilder insert(String path, T fragment, boolean createPath)
insert(String, Object, SubdocOptionsBuilder)
instead.path
- the path where to insert a new dictionary value.fragment
- the new dictionary value to insert.createPath
- true to create missing intermediary nodes.public <T> AsyncMutateInBuilder insert(String path, T fragment)
path
- the path where to insert a new dictionary value.fragment
- the new dictionary value to insert.public <T> AsyncMutateInBuilder insert(String path, T fragment, SubdocOptionsBuilder optionsBuilder)
path
- the path where to insert a new dictionary value.fragment
- the new dictionary value to insert.optionsBuilder
- SubdocOptionsBuilder
@Deprecated public <T> AsyncMutateInBuilder upsert(String path, T fragment, boolean createPath)
upsert(String, Object, SubdocOptionsBuilder)
instead.path
- the path where to insert (or replace) a dictionary value.fragment
- the new dictionary value to be applied.createPath
- true to create missing intermediary nodes.public <T> AsyncMutateInBuilder upsert(String path, T fragment)
path
- the path where to insert (or replace) a dictionary value.fragment
- the new dictionary value to be applied.@InterfaceStability.Committed public AsyncMutateInBuilder upsert(JsonObject content)
content
- full content of the JSON documentpublic <T> AsyncMutateInBuilder upsert(String path, T fragment, SubdocOptionsBuilder optionsBuilder)
path
- the path where to insert (or replace) a dictionary value.fragment
- the new dictionary value to be applied.optionsBuilder
- SubdocOptionsBuilder
public <T> AsyncMutateInBuilder remove(String path)
path
- the path to remove.public <T> AsyncMutateInBuilder remove(String path, SubdocOptionsBuilder optionsBuilder)
path
- the path to remove.optionsBuilder
- SubdocOptionsBuilder
@Deprecated public AsyncMutateInBuilder counter(String path, long delta, boolean createPath)
counter(String, long, SubdocOptionsBuilder)
instead.path
- the path to the counter (must be containing a number).delta
- the value to increment or decrement the counter by.createPath
- true to create missing intermediary nodes.public AsyncMutateInBuilder counter(String path, long delta)
path
- the path to the counter (must be containing a number).delta
- the value to increment or decrement the counter by.public AsyncMutateInBuilder counter(String path, long delta, SubdocOptionsBuilder optionsBuilder)
path
- the path to the counter (must be containing a number).delta
- the value to increment or decrement the counter by.optionsBuilder
- SubdocOptionsBuilder
@Deprecated public <T> AsyncMutateInBuilder arrayPrepend(String path, T value, boolean createPath)
arrayPrepend(String, Object, SubdocOptionsBuilder)
instead.path
- the path of the array.value
- the value to insert at the front of the array.createPath
- true to create missing intermediary nodes.public <T> AsyncMutateInBuilder arrayPrepend(String path, T value)
path
- the path of the array.value
- the value to insert at the front of the array.public <T> AsyncMutateInBuilder arrayPrepend(String path, T value, SubdocOptionsBuilder optionsBuilder)
path
- the path of the array.value
- the value to insert at the front of the array.optionsBuilder
- SubdocOptionsBuilder
@Deprecated public <T> AsyncMutateInBuilder arrayPrependAll(String path, Collection<T> values, boolean createPath)
arrayPrependAll(String, Collection, SubdocOptionsBuilder)
instead.arrayPrepend(String, Object, boolean)
(String, Object)} by grouping
mutations in a single packet.
For example given an array [ A, B, C ], prepending the values X and Y yields [ X, Y, A, B, C ]
and not [ [ X, Y ], A, B, C ].T
- the type of data in the collection (must be JSON serializable).path
- the path of the array.values
- the collection of values to insert at the front of the array as individual elements.createPath
- true to create missing intermediary nodes.public <T> AsyncMutateInBuilder arrayPrependAll(String path, Collection<T> values, SubdocOptionsBuilder optionsBuilder)
arrayPrepend(String, Object, boolean)
(String, Object)} by grouping
mutations in a single packet.
For example given an array [ A, B, C ], prepending the values X and Y yields [ X, Y, A, B, C ]
and not [ [ X, Y ], A, B, C ].T
- the type of data in the collection (must be JSON serializable).path
- the path of the array.values
- the collection of values to insert at the front of the array as individual elements.optionsBuilder
- SubdocOptionsBuilder
public <T> AsyncMutateInBuilder arrayPrependAll(String path, T... values)
arrayPrependAll(String, Collection, boolean)
. Note
that parent nodes are not created when using this method (ie. createPath = false).
First value becomes the first element of the array, second value the second, etc... All existing values
are shifted right in the array, by the number of inserted elements.
Each item in the collection is inserted as an individual element of the array, but a bit of overhead
is saved compared to individual arrayPrepend(String, Object, boolean)
(String, Object)} by grouping
mutations in a single packet.
For example given an array [ A, B, C ], prepending the values X and Y yields [ X, Y, A, B, C ]
and not [ [ X, Y ], A, B, C ].T
- the type of data in the collection (must be JSON serializable).path
- the path of the array.values
- the values to insert at the front of the array as individual elements.if you need to create missing intermediary nodes.
@Deprecated public <T> AsyncMutateInBuilder arrayAppend(String path, T value, boolean createPath)
arrayAppend(String, Object, SubdocOptionsBuilder)
instead.path
- the path of the array.value
- the value to insert at the back of the array.createPath
- true to create missing intermediary nodes.public <T> AsyncMutateInBuilder arrayAppend(String path, T value)
path
- the path of the array.value
- the value to insert at the back of the array.public <T> AsyncMutateInBuilder arrayAppend(String path, T value, SubdocOptionsBuilder optionsBuilder)
path
- the path of the array.value
- the value to insert at the back of the array.optionsBuilder
- SubdocOptionsBuilder
@Deprecated public <T> AsyncMutateInBuilder arrayAppendAll(String path, Collection<T> values, boolean createPath)
arrayAppendAll(String, Collection, SubdocOptionsBuilder)
instead.arrayAppend(String, Object, boolean)
by grouping mutations in
a single packet.
For example given an array [ A, B, C ], appending the values X and Y yields [ A, B, C, X, Y ]
and not [ A, B, C, [ X, Y ] ].T
- the type of data in the collection (must be JSON serializable).path
- the path of the array.values
- the collection of values to individually insert at the back of the array.createPath
- true to create missing intermediary nodes.public <T> AsyncMutateInBuilder arrayAppendAll(String path, Collection<T> values, SubdocOptionsBuilder optionsBuilder)
arrayAppend(String, Object, boolean)
by grouping mutations in
a single packet.
For example given an array [ A, B, C ], appending the values X and Y yields [ A, B, C, X, Y ]
and not [ A, B, C, [ X, Y ] ].T
- the type of data in the collection (must be JSON serializable).path
- the path of the array.values
- the collection of values to individually insert at the back of the array.optionsBuilder
- SubdocOptionsBuilder
public <T> AsyncMutateInBuilder arrayAppendAll(String path, T... values)
arrayAppendAll(String, Collection, boolean)
.
Note that parent nodes are not created when using this method (ie. createPath = false).
Each item in the collection is inserted as an individual element of the array, but a bit of overhead
is saved compared to individual arrayAppend(String, Object, boolean)
by grouping mutations in
a single packet.
For example given an array [ A, B, C ], appending the values X and Y yields [ A, B, C, X, Y ]
and not [ A, B, C, [ X, Y ] ].T
- the type of data in the collection (must be JSON serializable).path
- the path of the array.values
- the values to individually insert at the back of the array.if you need to create missing intermediary nodes.
public <T> AsyncMutateInBuilder arrayInsert(String path, T value)
path
- the path (including array position) where to insert the value.value
- the value to insert in the array.public <T> AsyncMutateInBuilder arrayInsert(String path, T value, SubdocOptionsBuilder optionsBuilder)
path
- the path (including array position) where to insert the value.value
- the value to insert in the array.optionsBuilder
- SubdocOptionsBuilder
public <T> AsyncMutateInBuilder arrayInsertAll(String path, Collection<T> values)
arrayInsert(String, Object)
by grouping mutations in a single packet.
For example given an array [ A, B, C ], inserting the values X and Y at position 1 yields [ A, B, X, Y, C ]
and not [ A, B, [ X, Y ], C ].T
- the type of data in the collection (must be JSON serializable).path
- the path of the array.values
- the values to insert at the specified position of the array, each value becoming an entry at or
after the insert position.public <T> AsyncMutateInBuilder arrayInsertAll(String path, Collection<T> values, SubdocOptionsBuilder optionsBuilder)
arrayInsert(String, Object)
by grouping mutations in a single packet.
For example given an array [ A, B, C ], inserting the values X and Y at position 1 yields [ A, B, X, Y, C ]
and not [ A, B, [ X, Y ], C ].T
- the type of data in the collection (must be JSON serializable).path
- the path of the array.values
- the values to insert at the specified position of the array, each value becoming an entry at or
after the insert position.optionsBuilder
- SubdocOptionsBuilder
public <T> AsyncMutateInBuilder arrayInsertAll(String path, T... values)
arrayInsertAll(String, Collection)
. Note that parent nodes are not created
when using this method (ie. createPath = false).
Each item in the collection is inserted as an individual element of the array, but a bit of overhead
is saved compared to individual arrayInsert(String, Object)
by grouping mutations in a single packet.
For example given an array [ A, B, C ], inserting the values X and Y at position 1 yields [ A, B, X, Y, C ]
and not [ A, B, [ X, Y ], C ].T
- the type of data in the collection (must be JSON serializable).path
- the path of the array.values
- the values to insert at the specified position of the array, each value becoming an entry at or
after the insert position.if you need to create missing intermediary nodes.
@Deprecated public <T> AsyncMutateInBuilder arrayAddUnique(String path, T value, boolean createPath)
arrayAddUnique(String, Object, SubdocOptionsBuilder)
instead.path
- the path to mutate in the JSON.value
- the value to insert.createPath
- true to create missing intermediary nodes.public <T> AsyncMutateInBuilder arrayAddUnique(String path, T value)
path
- the path to mutate in the JSON.value
- the value to insert.public <T> AsyncMutateInBuilder arrayAddUnique(String path, T value, SubdocOptionsBuilder optionsBuilder)
path
- the path to mutate in the JSON.value
- the value to insert.optionsBuilder
- SubdocOptionsBuilder
protected rx.Observable<DocumentFragment<Mutation>> doMultiMutate(long timeout, TimeUnit timeUnit)
protected rx.Observable<DocumentFragment<Mutation>> doSingleMutate(MutationSpec spec, long timeout, TimeUnit timeUnit)
Copyright © 2015 Couchbase, Inc.