com.couchbase.transactions

Class AttemptContext

java.lang.Object

com.couchbase.transactions.AttemptContext

public class AttemptContext
extends java.lang.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 AttemptContextReactive for the asynchronous version (which is the preferred option, and which this class largely simply wraps).

Method Summary

Modifier and Type	Method and Description
java.lang.String	attemptId() Returns the globally unique ID of this attempt, which may be useful for debugging and logging purposes.
void	commit() Commits the transaction.
void	defer() Defers committing this transaction.
TransactionGetResult	get(com.couchbase.client.java.Collection collection, java.lang.String id) Gets a document from the specified Couchbase bucket matching the specified id.
java.util.Optional<TransactionGetResult>	getOptional(com.couchbase.client.java.Collection collection, java.lang.String id) Gets a document from the specified Couchbase bucket matching the specified id.
TransactionGetResult	insert(com.couchbase.client.java.Collection collection, java.lang.String id, java.lang.Object content)
TransactionGetResult	insert(com.couchbase.client.java.Collection collection, java.lang.String id, java.lang.Object content, TransactionInsertOptions options) Inserts a new document into the specified Couchbase collection.
TransactionLogger	logger() Gives access to the attempt's logger, allowing application trace to be interleaved with transaction trace.
com.couchbase.client.java.query.QueryResult	query(java.lang.String statement) Calls query() with default options.
com.couchbase.client.java.query.QueryResult	query(java.lang.String statement, TransactionQueryOptions options) Runs a N1QL query and returns the result.
void	remove(TransactionGetResult doc) Removes the specified doc, using the document's last TransactionGetResult.cas().
TransactionGetResult	replace(TransactionGetResult doc, java.lang.Object content)
TransactionGetResult	replace(TransactionGetResult doc, java.lang.Object content, TransactionReplaceOptions options) Mutates the specified doc with new content, using the document's last TransactionGetResult.cas().
void	rollback() Rolls back the transaction.
java.lang.String	transactionId() Returns the globally unique ID of the overall transaction owning this attempt, which may be useful for debugging and logging purposes.

Methods inherited from class java.lang.Object

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

Method Detail

logger

public TransactionLogger logger()

Gives access to the attempt's logger, allowing application trace to be interleaved with transaction trace.

getOptional

public java.util.Optional<TransactionGetResult> getOptional(com.couchbase.client.java.Collection collection,
                                                            java.lang.String id)

Gets a document from the specified Couchbase bucket matching the specified id. It's returned as Optional.empty() if not found.

Parameters:

collection - the Couchbase collection the document exists on

id - the document's ID

Returns:

an Optional containing the document, or Optional.empty() if not found

get

public TransactionGetResult get(com.couchbase.client.java.Collection collection,
                                java.lang.String id)

Gets a document from the specified Couchbase bucket matching the specified id. If the document is not found, a DocumentNotFoundException is thrown. If not caught inside the transaction logic, this particular exception will cause the overall transaction to abort with a thrown TransactionFailed.

Parameters:

collection - the Couchbase collection the document exists on

id - the document's ID

Returns:

a TransactionGetResult containing the document

replace

public TransactionGetResult replace(TransactionGetResult doc,
                                    java.lang.Object content,
                                    TransactionReplaceOptions options)

Mutates the specified doc with new content, using the document's last TransactionGetResult.cas().

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 how the document is replaced. See TransactionReplaceOptions for details

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,
                                    java.lang.Object content)

insert

public TransactionGetResult insert(com.couchbase.client.java.Collection collection,
                                   java.lang.String id,
                                   java.lang.Object content,
                                   TransactionInsertOptions options)

Inserts a new document into the specified Couchbase collection.

As with replace(com.couchbase.transactions.TransactionGetResult, java.lang.Object, com.couchbase.transactions.TransactionReplaceOptions), the insert is staged until the transaction is committed. Due to technical limitations it is not as possible to completely hide the staged data from the rest of the Couchbase platform, as an empty document must be created.

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

options - options controlling how the document is inserted. See TransactionInsertOptions for details

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(com.couchbase.client.java.Collection collection,
                                   java.lang.String id,
                                   java.lang.Object content)

remove

public void remove(TransactionGetResult doc)

Removes the specified doc, using the document's last TransactionGetResult.cas().

As with replace(com.couchbase.transactions.TransactionGetResult, java.lang.Object, com.couchbase.transactions.TransactionReplaceOptions), 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

commit

public void commit()

Commits the transaction. All staged replaces, inserts and removals will be written.

After this, no further operations are permitted on this instance, and they will result in an IllegalStateException that will, if not caught in the transaction logic, cause the transaction to fail with a TransactionFailed exception.

defer

@Stability.Volatile
public void defer()

Defers committing this transaction.

The resultant TransactionResult.serialized() will contain a serialized form of the context for this transaction, which can be resumed using Transactions.commit(com.couchbase.transactions.deferred.TransactionSerializedContext, com.couchbase.transactions.config.PerTransactionConfig) or Transactions.rollback(com.couchbase.transactions.deferred.TransactionSerializedContext, com.couchbase.transactions.config.PerTransactionConfig).

rollback

public void rollback()

Rolls back the transaction. All staged replaces, inserts and removals will be removed. The transaction will not be retried, so this will be the final attempt.

After this, no further operations are permitted on this instance, and they will result in an IllegalStateException that will, if not caught in the transaction logic, cause the transaction to fail with a TransactionFailed exception.

attemptId

public java.lang.String attemptId()

Returns the globally unique ID of this attempt, which may be useful for debugging and logging purposes.

transactionId

public java.lang.String transactionId()

Returns the globally unique ID of the overall transaction owning this attempt, which may be useful for debugging and logging purposes.

query

public com.couchbase.client.java.query.QueryResult query(java.lang.String statement,
                                                         TransactionQueryOptions options)

Runs a N1QL query and returns the result.

All rows are buffered in-memory. The reactive version of this API provides a streaming interface which will not

Throws:

com.couchbase.client.core.error.CouchbaseException - 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 com.couchbase.client.java.query.QueryResult query(java.lang.String statement)

Calls query() with default options.