com.couchbase.client.java.transactions

Class TransactionAttemptContext

java.lang.Object

com.couchbase.client.java.transactions.TransactionAttemptContext

public class TransactionAttemptContext
extends Object

Provides methods to allow an application's transaction logic to read, mutate, insert and delete documents, as well as commit or rollback the transaction.

These methods are blocking/synchronous. See CoreTransactionAttemptContext for the asynchronous version (which is the preferred option, and which this class largely simply wraps).

Method Summary

Modifier and Type	Method and Description
TransactionGetResult	get(Collection collection, String id) Gets a document from the specified Couchbase collection matching the specified id.
TransactionGetResult	get(Collection collection, String id, TransactionGetOptions options) Gets a document from the specified Couchbase collection matching the specified id.
TransactionGetResult	insert(Collection collection, String id, Object content) Inserts a new document into the specified Couchbase collection.
TransactionGetResult	insert(Collection collection, String id, Object content, TransactionInsertOptions options) Inserts a new document into the specified Couchbase collection.
TransactionQueryResult	query(Scope scope, String statement) Calls query() with default options.
TransactionQueryResult	query(Scope scope, String statement, TransactionQueryOptions options) Runs a N1QL query and returns the result.
TransactionQueryResult	query(String statement) Calls query() with default options.
TransactionQueryResult	query(String statement, TransactionQueryOptions options) Runs a N1QL query and returns the result.
void	remove(TransactionGetResult doc) Removes the specified doc.
TransactionGetResult	replace(TransactionGetResult doc, Object content) Mutates the specified doc with new content.
TransactionGetResult	replace(TransactionGetResult doc, Object content, TransactionReplaceOptions options) Mutates the specified doc with new content.

Methods inherited from class java.lang.Object

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

Method Detail

get

public TransactionGetResult get(Collection collection,
                                String id)

Gets a document from the specified Couchbase collection matching the specified id. If the document is not found, a DocumentNotFoundException is thrown.

Parameters:

collection - the Couchbase collection the document exists on

id - the document's ID

Returns:

a TransactionGetResult containing the document

get

public TransactionGetResult get(Collection collection,
                                String id,
                                TransactionGetOptions options)

Gets a document from the specified Couchbase collection matching the specified id. If the document is not found, a DocumentNotFoundException is thrown.

Parameters:

collection - the Couchbase collection the document exists on

id - the document's ID

options - options controlling the operation

Returns:

a TransactionGetResult containing the document

replace

public TransactionGetResult replace(TransactionGetResult doc,
                                    Object content)

Mutates the specified doc with new content.

The mutation is staged until the transaction is committed. That is, any read of the document by any Couchbase component will see the document's current value, rather than this staged or 'dirty' data. If the attempt is rolled back, the staged mutation will be removed.

This staged data effectively locks the document from other transactional writes until the attempt completes (commits or rolls back).

If the mutation fails with a CasMismatchException, or any other exception, the transaction will automatically rollback this attempt, then retry.

Parameters:

doc - the doc to be updated

content - the content to replace the doc with. This will normally be a JsonObject.

Returns:

the doc, updated with its new CAS value. For performance a copy is not created and the original doc object is modified.

replace

public TransactionGetResult replace(TransactionGetResult doc,
                                    Object content,
                                    TransactionReplaceOptions options)

Mutates the specified doc with new content.

The mutation is staged until the transaction is committed. That is, any read of the document by any Couchbase component will see the document's current value, rather than this staged or 'dirty' data. If the attempt is rolled back, the staged mutation will be removed.

This staged data effectively locks the document from other transactional writes until the attempt completes (commits or rolls back).

If the mutation fails with a CasMismatchException, or any other exception, the transaction will automatically rollback this attempt, then retry.

Parameters:

doc - the doc to be updated

content - the content to replace the doc with. This will normally be a JsonObject.

options - options controlling the operation

Returns:

the doc, updated with its new CAS value. For performance a copy is not created and the original doc object is modified.

insert

public TransactionGetResult insert(Collection collection,
                                   String id,
                                   Object content)

Inserts a new document into the specified Couchbase collection.

As with replace(com.couchbase.client.java.transactions.TransactionGetResult, java.lang.Object), the insert is staged until the transaction is committed.

This staged data effectively locks the document from other transactional writes until the attempt completes (commits or rolls back).

Parameters:

collection - the Couchbase collection in which to insert the doc

id - the document's unique ID

content - the content to insert. Generally this will be a JsonObject

Returns:

the doc, updated with its new CAS value and ID, and converted to a TransactionGetResult

insert

public TransactionGetResult insert(Collection collection,
                                   String id,
                                   Object content,
                                   TransactionInsertOptions options)

Inserts a new document into the specified Couchbase collection.

As with replace(com.couchbase.client.java.transactions.TransactionGetResult, java.lang.Object), the insert is staged until the transaction is committed.

This staged data effectively locks the document from other transactional writes until the attempt completes (commits or rolls back).

Parameters:

collection - the Couchbase collection in which to insert the doc

id - the document's unique ID

content - the content to insert. Generally this will be a JsonObject

options - options controlling the operation

Returns:

the doc, updated with its new CAS value and ID, and converted to a TransactionGetResult

remove

public void remove(TransactionGetResult doc)

Removes the specified doc.

As with replace(com.couchbase.client.java.transactions.TransactionGetResult, java.lang.Object), the remove is staged until the transaction is committed. That is, the document will continue to exist, and the rest of the Couchbase platform will continue to see it.

This staged data effectively locks the document from other transactional writes until the attempt completes (commits or rolls back).

Note that a remove(String id) method is not possible, as it's necessary to check a provided TransactionGetResult to determine if the document is involved in another transaction.

Parameters:

doc - the doc to be removed

query

public TransactionQueryResult query(String statement,
                                    TransactionQueryOptions options)

Runs a N1QL query and returns the result.

All rows are buffered in-memory.

Throws:

com.couchbase.client.core.error.CouchbaseException - or an error derived from it on failure. The application can choose to catch and ignore this error, and the transaction attempt is allowed to continue. This differs from Key-Value operations, whose failure will cause the attempt to fail.

query

public TransactionQueryResult query(String statement)

Calls query() with default options.

query

public TransactionQueryResult query(Scope scope,
                                    String statement,
                                    TransactionQueryOptions options)

Runs a N1QL query and returns the result.

All rows are buffered in-memory.

This overload performs a 'scope-level query': that is, one in which a collection may be referenced by name in the query statement, without needing to specify the full bucket.scope.collection syntax.

Throws:

com.couchbase.client.core.error.CouchbaseException - or an error derived from it on failure. The application can choose to catch and ignore this error, and the transaction attempt is allowed to continue. This differs from Key-Value operations, whose failure will cause the attempt to fail.

query

public TransactionQueryResult query(Scope scope,
                                    String statement)

Calls query() with default options.

This overload performs a 'scope-level query': that is, one in which a collection may be referenced by name in the query statement, without needing to specify the full bucket.scope.collection syntax.