com.couchbase.client.java.subdoc

Class MutateInBuilder

java.lang.Object

com.couchbase.client.java.subdoc.MutateInBuilder

@InterfaceStability.Committed
 @InterfaceAudience.Public
public class MutateInBuilder
extends Object

A builder for subdocument mutations. In order to perform the final set of operations, use the execute() method. Operations are performed synchronously (see AsyncMutateInBuilder for an asynchronous version).

Instances of this builder should be obtained through Bucket.mutateIn(String) rather than directly constructed.

Since:

2.2

Author:

Simon Baslé

Constructor Summary

Constructors

Constructor and Description
MutateInBuilder(AsyncMutateInBuilder asyncBuilder, long defaultTimeout, TimeUnit defaultTimeUnit) Instances of this builder should be obtained through Bucket.mutateIn(String) rather than directly constructed.

Method Summary

Modifier and Type	Method and Description
<T> MutateInBuilder	arrayAddUnique(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> MutateInBuilder	arrayAppend(String path, T value, boolean createParents) Append to an existing array, pushing the value to the back/last position in the array.
<T> MutateInBuilder	arrayAppendAll(String path, Collection<T> values, boolean createParents) 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> MutateInBuilder	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> MutateInBuilder	arrayInsert(String path, T value) Insert into an existing array at a specific position (denoted in the path, eg.
<T> MutateInBuilder	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> MutateInBuilder	arrayInsertAll(String path, T... values) Insert multiple values at once in an existing array at a specified position (denoted in the path, eg.
<T> MutateInBuilder	arrayPrepend(String path, T value, boolean createParents) Prepend to an existing array, pushing the value to the front/first position in the array.
<T> MutateInBuilder	arrayPrependAll(String path, Collection<T> values, boolean createParents) 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> MutateInBuilder	arrayPrependAll(String path, T... values) Prepend multiple values at once in an existing array, pushing all values to the front/start of the array.
MutateInBuilder	counter(String path, long delta, boolean createParents) Increment/decrement a numerical fragment in a JSON document.
DocumentFragment<Mutation>	execute() Perform several mutation operations inside a single existing JSON document, with the default key/value timeout.
DocumentFragment<Mutation>	execute(long timeout, TimeUnit timeUnit) Perform several mutation operations inside a single existing JSON document, with a specific timeout.
<T> MutateInBuilder	insert(String path, T fragment, boolean createParents) Insert a fragment provided the last element of the path doesn’t exists.
<T> MutateInBuilder	remove(String path) Remove an entry in a JSON document (scalar, array element, dictionary entry, whole array or dictionary, depending on the path).
<T> MutateInBuilder	replace(String path, T fragment) Replace an existing value by the given fragment.
String	toString()
<T> MutateInBuilder	upsert(String path, T fragment, boolean createParents) Insert a fragment, replacing the old value if the path exists.
MutateInBuilder	withCas(long cas) Apply the whole mutation using optimistic locking, checking against the provided CAS value.
MutateInBuilder	withDurability(PersistTo persistTo) Set a persistence durability constraint for the whole mutation.
MutateInBuilder	withDurability(PersistTo persistTo, ReplicateTo replicateTo) Set both a persistence and replication durability constraints for the whole mutation.
MutateInBuilder	withDurability(ReplicateTo replicateTo) Set a replication durability constraint for the whole mutation.
MutateInBuilder	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

Constructor Detail

MutateInBuilder

@InterfaceAudience.Private
public MutateInBuilder(AsyncMutateInBuilder asyncBuilder,
                                                  long defaultTimeout,
                                                  TimeUnit defaultTimeUnit)

Instances of this builder should be obtained through Bucket.mutateIn(String) rather than directly constructed.

Method Detail

execute

public DocumentFragment<Mutation> execute()

Perform several mutation operations inside a single existing JSON document, with the default key/value timeout. 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 operation throws under the following notable error conditions:

• 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 Bucket.replace(Document).

Returns:

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

execute

public DocumentFragment<Mutation> execute(long timeout,
                                          TimeUnit timeUnit)

Perform several mutation operations inside a single existing JSON document, with a specific timeout. 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 operation throws under the following most notable error conditions:

• 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 //TODO list all subdoc level errors here

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 Bucket.replace(Document).

Parameters:

timeout - the specific timeout to apply for the operation.

timeUnit - the time unit for the timeout.

Returns:

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

withExpiry

public MutateInBuilder 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 MutateInBuilder 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 MutateInBuilder 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 MutateInBuilder 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 MutateInBuilder withDurability(PersistTo persistTo,
                                      ReplicateTo replicateTo)

Set both a persistence and 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> MutateInBuilder 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> MutateInBuilder 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> MutateInBuilder 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> MutateInBuilder 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 MutateInBuilder 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.

arrayPrepend

public <T> MutateInBuilder arrayPrepend(String path,
                                        T value,
                                        boolean createParents)

Prepend to an existing array, pushing the value to the front/first position in the array.

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.

arrayPrependAll

public <T> MutateInBuilder arrayPrependAll(String path,
                                           Collection<T> values,
                                           boolean createParents)

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.

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

Parameters:

path - the path of the array.

values - the collection of values to insert at the front of the array as individual elements.

createParents - true to create missing intermediary nodes.

T - the type of data in the collection (must be JSON serializable).

arrayPrependAll

public <T> MutateInBuilder arrayPrependAll(String path,
                                           T... values)

Prepend multiple values at once in an existing array, pushing all values to the front/start of the array. This is provided as a convenience alternative to arrayPrependAll(String, Collection, boolean). Note that parent nodes are not created when using this method (ie. createParents = 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 ].

Parameters:

path - the path of the array.

values - the values to insert at the front of the array as individual elements.

T - the type of data in the collection (must be JSON serializable).

See Also:

if you need to create missing intermediary nodes.

arrayAppend

public <T> MutateInBuilder arrayAppend(String path,
                                       T value,
                                       boolean createParents)

Append to an existing array, pushing the value to the back/last position in the array.

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.

arrayAppendAll

public <T> MutateInBuilder arrayAppendAll(String path,
                                          Collection<T> values,
                                          boolean createParents)

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.

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

Parameters:

path - the path of the array.

values - the collection of values to individually insert at the back of the array.

createParents - true to create missing intermediary nodes.

T - the type of data in the collection (must be JSON serializable).

arrayAppendAll

public <T> MutateInBuilder arrayAppendAll(String path,
                                          T... values)

Append multiple values at once in an existing array, pushing all values to the back/end of the array. This is provided as a convenience alternative to arrayAppendAll(String, Collection, boolean). Note that parent nodes are not created when using this method (ie. createParents = 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 ] ].

Parameters:

path - the path of the array.

values - the values to individually insert at the back of the array.

T - the type of data in the collection (must be JSON serializable).

See Also:

if you need to create missing intermediary nodes.

arrayInsert

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

arrayInsertAll

public <T> MutateInBuilder arrayInsertAll(String path,
                                          Collection<T> values)

Insert multiple values at once in an existing array at a specified position (denoted in the path, eg. “sub.array[2]”), inserting all values in the collection’s iteration order at the given position and shifting existing values beyond the position by the number of elements in the collection.

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

Parameters:

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.

T - the type of data in the collection (must be JSON serializable).

arrayInsertAll

public <T> MutateInBuilder arrayInsertAll(String path,
                                          T... values)

Insert multiple values at once in an existing array at a specified position (denoted in the path, eg. “sub.array[2]”), inserting all values at the given position and shifting existing values beyond the position by the number of elements in the collection. This is provided as a convenience alternative to arrayInsertAll(String, Collection). Note that parent nodes are not created when using this method (ie. createParents = 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 ].

Parameters:

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.

T - the type of data in the collection (must be JSON serializable).

See Also:

if you need to create missing intermediary nodes.

arrayAddUnique

public <T> MutateInBuilder arrayAddUnique(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.

toString

public String toString()

Overrides:

toString in class Object