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
All Methods Instance Methods Concrete Methods Modifier and Type Method 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 Couchbasebucket
matching the specifiedid
.java.util.Optional<TransactionGetResult>
getOptional(com.couchbase.client.java.Collection collection, java.lang.String id)
Gets a document from the specified Couchbasebucket
matching the specifiedid
.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 Couchbasecollection
.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(com.couchbase.client.java.Scope scope, java.lang.String statement)
Calls query() with default options.com.couchbase.client.java.query.QueryResult
query(com.couchbase.client.java.Scope scope, java.lang.String statement, TransactionQueryOptions options)
Runs a N1QL query and returns the result.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 specifieddoc
, using the document's lastTransactionGetResult.cas()
.TransactionGetResult
replace(TransactionGetResult doc, java.lang.Object content)
TransactionGetResult
replace(TransactionGetResult doc, java.lang.Object content, TransactionReplaceOptions options)
Mutates the specifieddoc
with new content, using the document's lastTransactionGetResult.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.
-
-
-
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 Couchbasebucket
matching the specifiedid
. It's returned as Optional.empty() if not found.- Parameters:
collection
- the Couchbase collection the document exists onid
- the document's ID- Returns:
- an
Optional
containing the document, orOptional.empty()
if not found
-
get
public TransactionGetResult get(com.couchbase.client.java.Collection collection, java.lang.String id)
Gets a document from the specified Couchbasebucket
matching the specifiedid
. If the document is not found, aDocumentNotFoundException
is thrown. If not caught inside the transaction logic, this particular exception will cause the overall transaction to abort with a thrownTransactionFailed
.- Parameters:
collection
- the Couchbase collection the document exists onid
- the document's ID- Returns:
- a
TransactionGetResult
containing the document
-
replace
public TransactionGetResult replace(TransactionGetResult doc, java.lang.Object content, TransactionReplaceOptions options)
Mutates the specifieddoc
with new content, using the document's lastTransactionGetResult.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 updatedcontent
- the content to replace the doc with. This will normally be aJsonObject
.options
- options controlling how the document is replaced. SeeTransactionReplaceOptions
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 Couchbasecollection
.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 docoptions
- options controlling how the document is inserted. SeeTransactionInsertOptions
for detailsid
- the document's unique IDcontent
- the content to insert. Generally this will be aJsonObject
- 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 specifieddoc
, using the document's lastTransactionGetResult.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 providedTransactionGetResult
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 aTransactionFailed
exception.
-
defer
@Volatile public void defer()
Defers committing this transaction. The resultantTransactionResult.serialized()
will contain a serialized form of the context for this transaction, which can be resumed usingTransactions.commit(com.couchbase.transactions.deferred.TransactionSerializedContext, com.couchbase.transactions.config.PerTransactionConfig)
orTransactions.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 aTransactionFailed
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
@Uncommitted 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
@Uncommitted public com.couchbase.client.java.query.QueryResult query(java.lang.String statement)
Calls query() with default options.
-
query
@Uncommitted public com.couchbase.client.java.query.QueryResult query(com.couchbase.client.java.Scope scope, 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.
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
- 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
@Uncommitted public com.couchbase.client.java.query.QueryResult query(com.couchbase.client.java.Scope scope, java.lang.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.
-
-