Package 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 Details

    • 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

    • getReplicaFromPreferredServerGroup

      public TransactionGetResult getReplicaFromPreferredServerGroup(Collection collection, String id)
      A convenience wrapper around getReplicaFromPreferredServerGroup(Collection, String, TransactionGetReplicaFromPreferredServerGroupOptions) using default options.

    • getReplicaFromPreferredServerGroup

      public TransactionGetResult getReplicaFromPreferredServerGroup(Collection collection, String id, TransactionGetReplicaFromPreferredServerGroupOptions options)
      Gets a document from the specified Couchbase collection matching the specified id.

      It will be fetched only from document copies that on nodes in the preferred server group, which can be configured with CoreEnvironment.Builder.preferredServerGroup(String).

      If no replica can be retrieved, which can include for reasons such as this preferredServerGroup not being set, and misconfigured server groups, then DocumentUnretrievableException can be raised. It is strongly recommended that this method always be used with a fallback strategy, such as: try { var result = ctx.getReplicaFromPreferredServerGroup(collection, id); } catch (DocumentUnretrievableException err) { var result = ctx.get(collection, id); }

      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

    • getMulti

      @Uncommitted public TransactionGetMultiResult getMulti(List<TransactionGetMultiSpec> specs)
      A convenience wrapper around getMulti(List, TransactionGetMultiOptions) using default options.

    • getMulti

      @Uncommitted public TransactionGetMultiResult getMulti(List<TransactionGetMultiSpec> specs, TransactionGetMultiOptions options)
      Fetches multiple documents in a single operation.

      In addition, it will heuristically aim to detect read skew anomalies, and avoid them if possible. Read skew detection and avoidance is not guaranteed.

      Parameters:
      specs - the documents to fetch.
      Returns:
      a result containing the fetched documents.

    • getMultiReplicasFromPreferredServerGroup

      @Uncommitted public TransactionGetMultiReplicasFromPreferredServerGroupResult getMultiReplicasFromPreferredServerGroup(List<TransactionGetMultiReplicasFromPreferredServerGroupSpec> specs)
      A convenience wrapper around getMulti(List, TransactionGetMultiOptions) using default options.

    • getMultiReplicasFromPreferredServerGroup

      @Uncommitted public TransactionGetMultiReplicasFromPreferredServerGroupResult getMultiReplicasFromPreferredServerGroup(List<TransactionGetMultiReplicasFromPreferredServerGroupSpec> specs, TransactionGetMultiReplicasFromPreferredServerGroupOptions options)
      Similar to getMulti(List, TransactionGetMultiOptions), but fetches the documents from replicas in the preferred server group.

      Note that the nature of replicas is that they are eventually consistent with the active, and so the effectiveness of read skew detection may be impacted.

    • 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:
      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:
      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.