com.couchbase.client.java.subdoc

Class AsyncMutateInBuilder

java.lang.Object

com.couchbase.client.java.subdoc.AsyncMutateInBuilder

@InterfaceStability.Experimental
 @InterfaceAudience.Public
public class AsyncMutateInBuilder
extends Object

A builder for subdocument mutations. In order to perform the final set of operations, use the doMutate() 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.

Since:

2.2

Author:

Simon Baslé

Field Summary

Fields

Modifier and Type	Field and Description
protected long	cas
protected String	docId
protected int	expiry
protected List<MutationSpec>	mutationSpecs
protected PersistTo	persistTo
protected ReplicateTo	replicateTo

Constructor Summary

Constructors

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.

Method Summary

Modifier and Type	Method and Description
<T> AsyncMutateInBuilder	addUnique(String path, T value, boolean createParents) 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	arrayInsert(String path, T value) Insert into an existing array at a specific position (denoted in the path, eg.
AsyncMutateInBuilder	counter(String path, long delta, boolean createParents) Increment/decrement a numerical fragment in a JSON document.
protected Observable<DocumentFragment<Mutation>>	doMultiMutate()
Observable<DocumentFragment<Mutation>>	doMutate() Perform several mutation operations inside a single existing JSON document.
protected Observable<DocumentFragment<Mutation>>	doSingleMutate(MutationSpec spec)
<T> AsyncMutateInBuilder	insert(String path, T fragment, boolean createParents) Insert a fragment provided the last element of the path doesn’t exists,
<T> AsyncMutateInBuilder	pushBack(String path, T value, boolean createParents) Push to the back of an existing array, appending the value.
<T> AsyncMutateInBuilder	pushFront(String path, T value, boolean createParents) Push to the front of an existing array, prepending the value.
<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	replace(String path, T fragment) Replace an existing value by the given fragment.
String	toString()
<T> AsyncMutateInBuilder	upsert(String path, T fragment, boolean createParents) Insert a fragment, replacing the old value if the path exists.
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.

Methods inherited from class java.lang.Object

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

Field Detail

docId

protected final String docId

mutationSpecs

protected final List<MutationSpec> mutationSpecs

expiry

protected int expiry

cas

protected long cas

persistTo

protected PersistTo persistTo

replicateTo

protected ReplicateTo replicateTo

Constructor Detail

AsyncMutateInBuilder

@InterfaceAudience.Private
public 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.

Method Detail

doMutate

public Observable<DocumentFragment<Mutation>> doMutate()

Perform several 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
• 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).

Returns:

an Observable of a single DocumentFragment (if successful) containing updated cas metadata. Note that some individual results could also bear a value, like counter operations.

withExpiry

public AsyncMutateInBuilder withExpiry(int expiry)

Change the expiry of the enclosing document as part of the mutation.

Parameters:

expiry - the new expiry to apply (or 0 to avoid changing the expiry)

Returns:

this builder for chaining.

withCas

public AsyncMutateInBuilder withCas(long cas)

Apply the whole mutation using optimistic locking, checking against the provided CAS value.

Parameters:

cas - the CAS to compare the enclosing document to.

Returns:

this builder for chaining.

withDurability

public AsyncMutateInBuilder withDurability(PersistTo persistTo)

Set a persistence durability constraint for the whole mutation.

Parameters:

persistTo - the persistence durability constraint to observe.

Returns:

this builder for chaining.

withDurability

public AsyncMutateInBuilder withDurability(ReplicateTo replicateTo)

Set a replication durability constraint for the whole mutation.

Parameters:

replicateTo - the replication durability constraint to observe.

Returns:

this builder for chaining.

withDurability

public AsyncMutateInBuilder withDurability(PersistTo persistTo,
                                           ReplicateTo replicateTo)

Set both a persistence and a replication durability constraints for the whole mutation.

Parameters:

persistTo - the persistence durability constraint to observe.

replicateTo - the replication durability constraint to observe.

Returns:

this builder for chaining.

replace

public <T> AsyncMutateInBuilder replace(String path,
                                        T fragment)

Replace an existing value by the given fragment.

Parameters:

path - the path where the value to replace is.

fragment - the new value.

insert

public <T> AsyncMutateInBuilder insert(String path,
                                       T fragment,
                                       boolean createParents)

Insert a fragment provided the last element of the path doesn’t exists,

Parameters:

path - the path where to insert a new dictionary value.

fragment - the new dictionary value to insert.

createParents - true to create missing intermediary nodes.

upsert

public <T> AsyncMutateInBuilder upsert(String path,
                                       T fragment,
                                       boolean createParents)

Insert a fragment, replacing the old value if the path exists.

Parameters:

path - the path where to insert (or replace) a dictionary value.

fragment - the new dictionary value to be applied.

createParents - true to create missing intermediary nodes.

remove

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

Parameters:

path - the path to remove.

counter

public AsyncMutateInBuilder counter(String path,
                                    long delta,
                                    boolean createParents)

Increment/decrement a numerical fragment in a JSON document. If the value (last element of the path) doesn’t exist the counter is created and takes the value of the delta.

Parameters:

path - the path to the counter (must be containing a number).

delta - the value to increment or decrement the counter by.

createParents - true to create missing intermediary nodes.

pushFront

public <T> AsyncMutateInBuilder pushFront(String path,
                                          T value,
                                          boolean createParents)

Push to the front of an existing array, prepending the value.

Parameters:

path - the path of the array.

value - the value to insert at the front of the array.

createParents - true to create missing intermediary nodes.

pushBack

public <T> AsyncMutateInBuilder pushBack(String path,
                                         T value,
                                         boolean createParents)

Push to the back of an existing array, appending the value.

Parameters:

path - the path of the array.

value - the value to insert at the back of the array.

createParents - true to create missing intermediary nodes.

arrayInsert

public <T> AsyncMutateInBuilder arrayInsert(String path,
                                            T value)

Insert into an existing array at a specific position (denoted in the path, eg. “sub.array[2]”).

Parameters:

path - the path (including array position) where to insert the value.

value - the value to insert in the array.

addUnique

public <T> AsyncMutateInBuilder addUnique(String path,
                                          T value,
                                          boolean createParents)

Insert a value in an existing array only if the value isn’t already contained in the array (by way of string comparison).

Parameters:

path - the path to mutate in the JSON.

value - the value to insert.

createParents - true to create missing intermediary nodes.

doMultiMutate

protected Observable<DocumentFragment<Mutation>> doMultiMutate()

doSingleMutate

protected Observable<DocumentFragment<Mutation>> doSingleMutate(MutationSpec spec)

toString

public String toString()

Overrides:

toString in class Object