Class 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 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​(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 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.
      • 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)
      • 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.

      • 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

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