Package com.couchbase.transactions

Class Transactions

java.lang.Object

com.couchbase.transactions.Transactions

All Implemented Interfaces:

java.lang.AutoCloseable

public class Transactions
extends java.lang.Object
implements java.lang.AutoCloseable

The starting point for creating Couchbase transactions.

The main methods to run transactions are run(java.util.function.Consumer<com.couchbase.transactions.AttemptContext>, com.couchbase.transactions.config.PerTransactionConfig) and reactive.

Certain configurations, including the default one, will create background resources including cleanup threads, so it is highly recommended that an application create and reuse just one Transactions object.

Method Summary

Modifier and Type	Method	Description
void	close()	Close all resources opened by this instance.
TransactionResult	commit(TransactionSerializedContext serialized)	Commits a deferred transaction, using a default PerTransactionConfig
TransactionResult	commit(TransactionSerializedContext serialized, PerTransactionConfig perConfig)	Commits a deferred transaction.
TransactionConfig	config()	Returns the TransactionConfig used to create this instance.
static Transactions	create(com.couchbase.client.java.Cluster cluster)	Create a Transactions object using the default TransactionConfig.
static Transactions	create(com.couchbase.client.java.Cluster cluster, TransactionConfig config)	Create a Transactions object using the provided TransactionConfig.
static Transactions	create(com.couchbase.client.java.Cluster cluster, TransactionConfigBuilder config)	Create a Transactions object using the provided TransactionConfigBuilder.
SingleQueryTransactionResult	query(com.couchbase.client.java.Scope scope, java.lang.String statement)	Performs a single query transaction, with a scope context and default configuration.
SingleQueryTransactionResult	query(com.couchbase.client.java.Scope scope, java.lang.String statement, SingleQueryTransactionConfig queryConfig)	Performs a single query transaction, with a scope context and custom configuration.
SingleQueryTransactionResult	query(java.lang.String statement)	Performs a single query transaction, with default configuration.
SingleQueryTransactionResult	query(java.lang.String statement, SingleQueryTransactionConfig queryConfig)	Performs a single query transaction, with a custom configuration.
TransactionsReactive	reactive()	Returns an TransactionsReactive, which allows transactions to be run in an asynchronous manner.
reactor.core.publisher.Mono<TransactionResult>	reactive(java.util.function.Function<AttemptContextReactive,reactor.core.publisher.Mono<java.lang.Void>> transactionLogic)	A convenience wrapper around TransactionsReactive.run(java.util.function.Function<com.couchbase.transactions.AttemptContextReactive, reactor.core.publisher.Mono<java.lang.Void>>, com.couchbase.transactions.config.PerTransactionConfig), that provides a default PerTransactionConfig.
reactor.core.publisher.Mono<TransactionResult>	reactive(java.util.function.Function<AttemptContextReactive,reactor.core.publisher.Mono<java.lang.Void>> transactionLogic, PerTransactionConfig perConfig)	A convenience wrapper around TransactionsReactive.run(java.util.function.Function<com.couchbase.transactions.AttemptContextReactive, reactor.core.publisher.Mono<java.lang.Void>>, com.couchbase.transactions.config.PerTransactionConfig).
TransactionResult	rollback(TransactionSerializedContext serialized)	Rolls back a deferred transaction, using a default PerTransactionConfig
TransactionResult	rollback(TransactionSerializedContext serialized, PerTransactionConfig perConfig)	Rolls back a deferred transaction.
TransactionResult	run(java.util.function.Consumer<AttemptContext> transactionLogic)	Runs supplied transactional logic until success or failure.
TransactionResult	run(java.util.function.Consumer<AttemptContext> transactionLogic, PerTransactionConfig perConfig)	Runs supplied transactional logic until success or failure.

Methods inherited from class java.lang.Object

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

Method Detail

create

public static Transactions create(com.couchbase.client.java.Cluster cluster)

Create a Transactions object using the default TransactionConfig.

Parameters:

cluster - a Couchbase Cluster object

create

public static Transactions create(com.couchbase.client.java.Cluster cluster,
                                  TransactionConfig config)

Create a Transactions object using the provided TransactionConfig.

Parameters:

cluster - a Couchbase Cluster object

config - a TransactionConfig

create

public static Transactions create(com.couchbase.client.java.Cluster cluster,
                                  TransactionConfigBuilder config)

Create a Transactions object using the provided TransactionConfigBuilder.

Provided as a convenience method to the TransactionConfigBuilder does not have to be explicitly built.

Parameters:

cluster - a Couchbase Cluster object

config - a TransactionConfigBuilder

config

public TransactionConfig config()

Returns the TransactionConfig used to create this instance.

run

public TransactionResult run(java.util.function.Consumer<AttemptContext> transactionLogic,
                             PerTransactionConfig perConfig)
                      throws TransactionFailed

Runs supplied transactional logic until success or failure.

The supplied transactional logic will be run if necessary multiple times, until either:

• The transaction successfully commits
• The transactional logic requests an explicit rollback
• The transaction timesout. This is controlled by the TransactionConfigBuilder.expirationTime(Duration)} configuration parameter.
• An exception is thrown, either inside the transaction library or by the supplied transaction logic, that cannot be handled.

The transaction logic Consumer is provided an AttemptContext, which contains methods allowing it to read, mutate, insert and delete documents, as well as commit or rollback the transaction.

If the transaction logic performs a commit or rollback it must be the last operation performed. Else a TransactionFailed will be thrown. Similarly, there cannot be a commit followed by a rollback, or vice versa - this will also raise a TransactionFailed.

If the transaction logic does not perform an explicit commit or rollback, then a commit will be performed anyway.

Parameters:

transactionLogic - the application's transaction logic

perConfig - the configuration to use for this transaction

Returns:

there is no need to check the returned TransactionResult, as success is implied by the lack of a thrown exception. It contains information useful only for debugging and logging.

Throws:

TransactionFailed - or a derived exception if the transaction fails to commit for any reason, possibly after multiple retries. The exception contains further details of the error

run

public TransactionResult run(java.util.function.Consumer<AttemptContext> transactionLogic)
                      throws TransactionFailed

Runs supplied transactional logic until success or failure. A convenience overload for run(java.util.function.Consumer<com.couchbase.transactions.AttemptContext>, com.couchbase.transactions.config.PerTransactionConfig) that provides a default PerTransactionConfig

Throws:

TransactionFailed

reactive

public TransactionsReactive reactive()

Returns an TransactionsReactive, which allows transactions to be run in an asynchronous manner.

reactive

public reactor.core.publisher.Mono<TransactionResult> reactive(java.util.function.Function<AttemptContextReactive,reactor.core.publisher.Mono<java.lang.Void>> transactionLogic,
                                                               PerTransactionConfig perConfig)

A convenience wrapper around TransactionsReactive.run(java.util.function.Function<com.couchbase.transactions.AttemptContextReactive, reactor.core.publisher.Mono<java.lang.Void>>, com.couchbase.transactions.config.PerTransactionConfig).

reactive

public reactor.core.publisher.Mono<TransactionResult> reactive(java.util.function.Function<AttemptContextReactive,reactor.core.publisher.Mono<java.lang.Void>> transactionLogic)

A convenience wrapper around TransactionsReactive.run(java.util.function.Function<com.couchbase.transactions.AttemptContextReactive, reactor.core.publisher.Mono<java.lang.Void>>, com.couchbase.transactions.config.PerTransactionConfig), that provides a default PerTransactionConfig.

commit

@Volatile
public TransactionResult commit(TransactionSerializedContext serialized,
                                PerTransactionConfig perConfig)

Commits a deferred transaction.

Parameters:

serialized - the serialized context for the deferred transaction

Returns:

the result of the commit portion of the transaction

commit

@Volatile
public TransactionResult commit(TransactionSerializedContext serialized)

Commits a deferred transaction, using a default PerTransactionConfig

Parameters:

serialized - the serialized context for the deferred transaction

Returns:

the result of the commit portion of the transaction

rollback

@Volatile
public TransactionResult rollback(TransactionSerializedContext serialized,
                                  PerTransactionConfig perConfig)

Rolls back a deferred transaction.

Parameters:

serialized - the serialized context for the deferred transaction

Returns:

the result of the rollback portion of the transaction

rollback

@Volatile
public TransactionResult rollback(TransactionSerializedContext serialized)

Rolls back a deferred transaction, using a default PerTransactionConfig

Parameters:

serialized - the serialized context for the deferred transaction

Returns:

the result of the rollback portion of the transaction

query

@Uncommitted
public SingleQueryTransactionResult query(java.lang.String statement)

Performs a single query transaction, with default configuration.

Parameters:

statement - the statement to execute.

Returns:

a SingleQueryTransactionResult

query

@Uncommitted
public SingleQueryTransactionResult query(java.lang.String statement,
                                          SingleQueryTransactionConfig queryConfig)

Performs a single query transaction, with a custom configuration.

Parameters:

statement - the statement to execute.

queryConfig - configuration options.

Returns:

a SingleQueryTransactionResult

query

@Uncommitted
public SingleQueryTransactionResult query(com.couchbase.client.java.Scope scope,
                                          java.lang.String statement)

Performs a single query transaction, with a scope context and default configuration.

Parameters:

statement - the statement to execute.

scope - the query will be executed in the context of this scope, so it can refer to a collection on this scope rather than needed to provide the full keyspace.

Returns:

a SingleQueryTransactionResult

query

@Uncommitted
public SingleQueryTransactionResult query(com.couchbase.client.java.Scope scope,
                                          java.lang.String statement,
                                          SingleQueryTransactionConfig queryConfig)

Performs a single query transaction, with a scope context and custom configuration.

Parameters:

statement - the statement to execute.

scope - the query will be executed in the context of this scope, so it can refer to a collection on this scope rather than needed to provide the full keyspace.

queryConfig - configuration options.

Returns:

a SingleQueryTransactionResult

close

public void close()

Close all resources opened by this instance. Will block until complete. It is recommended to call this method upon application exit.

Specified by:

close in interface java.lang.AutoCloseable