com.couchbase.transactions.config

Class TransactionConfigBuilder

java.lang.Object

com.couchbase.transactions.config.TransactionConfigBuilder

public class TransactionConfigBuilder
extends java.lang.Object

Provides all configurable parameters for Couchbase transactions, in a builder format.

Method Summary

Modifier and Type	Method and Description
TransactionConfig	build() Converts this mutable instance into an immutable TransactionConfig that's ready to be used with Transactions.
TransactionConfigBuilder	cleanupClientAttempts(boolean cleanupClientAttempts) Controls where a background thread is created to cleanup any transaction attempts made by this client.
TransactionConfigBuilder	cleanupLostAttempts(boolean cleanupLostAttempts) Controls where a background process is created to cleanup any 'lost' transaction attempts: that is, those for which the regular cleanup process has failed.
TransactionConfigBuilder	cleanupWindow(java.time.Duration cleanupWindow) Part of the lost attempts background cleanup process.
static TransactionConfigBuilder	create() Returns a new TransactionConfigBuilder, which can be used to build up and create a TransactionConfig.
TransactionConfigBuilder	durabilityLevel(TransactionDurabilityLevel level) All transaction writes will be performed with this durability setting.
TransactionConfigBuilder	expirationTime(java.time.Duration expirationTime) Sets the maximum time that transactions can run for.
TransactionConfigBuilder	keyValueTimeout(java.time.Duration timeout) Sets the default timeout used with all key-value writes.
TransactionConfigBuilder	logDirectly(com.couchbase.client.core.cnc.Event.Severity logLevel) Logs all lines that are related to transactions and are at a level greater to or equal to logLevel, directly to the standard Couchbase logging event bus.
TransactionConfigBuilder	logOnFailure(boolean logOnFailure, com.couchbase.client.core.cnc.Event.Severity logOnFailureLevel) If a transaction fails, e.g.
TransactionConfigBuilder	metadataCollection(com.couchbase.client.java.Collection collection) Allows setting a custom collection to use for any transactional metadata documents.
TransactionConfigBuilder	numATRs(int atrs) Currently, this is to be used only with Couchbase guidance and instructions.
TransactionConfigBuilder	persistentLogging(com.couchbase.client.java.Collection collection) Currently, this is to be used only with Couchbase guidance and instructions.
TransactionConfigBuilder	testFactories(AttemptContextFactory attemptContextFactory, CleanerFactory cleanerFactory, ClientRecordFactory clientRecordFactory) For internal testing.

Methods inherited from class java.lang.Object

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

Method Detail

create

public static TransactionConfigBuilder create()

Returns a new TransactionConfigBuilder, which can be used to build up and create a TransactionConfig.

build

public TransactionConfig build()

Converts this mutable instance into an immutable TransactionConfig that's ready to be used with Transactions.

cleanupClientAttempts

public TransactionConfigBuilder cleanupClientAttempts(boolean cleanupClientAttempts)

Controls where a background thread is created to cleanup any transaction attempts made by this client.

This should be left at its default of true. Without this, this client's transactions will only be cleaned up by the lost attempts cleanup process, which is by necessity slower.

cleanupLostAttempts

public TransactionConfigBuilder cleanupLostAttempts(boolean cleanupLostAttempts)

Controls where a background process is created to cleanup any 'lost' transaction attempts: that is, those for which the regular cleanup process has failed.

This should be left at its default of true. Without at least one client performing this cleanup, 'lost' transactions will not be removed.

cleanupWindow

public TransactionConfigBuilder cleanupWindow(java.time.Duration cleanupWindow)

Part of the lost attempts background cleanup process. Specifies the window during which the cleanup process is sure to discover all lost transactions.

This process is an implementation detail, but currently consists of polling multiple documents. The default setting of 60 seconds is tuned to reduce impact on the cluster. If the application would prefer to discover lost transactions more swiftly, but at the cost of more frequent polling, it can feel free to reduce this parameter, while monitoring resource usage.

The trade-off to appreciate is that if a document is in a transaction A, it is effectively locked from being updated by another transaction until transaction A has been completed - that is, committed or rolled back. In rare cases such as application crashes, the transaction will remain incomplete - that is, it will be lost - until the lost transactions process discovers it.

expirationTime

public TransactionConfigBuilder expirationTime(java.time.Duration expirationTime)

Sets the maximum time that transactions can run for. The default is 15 seconds. After this time, transactions will throw a TransactionExpired error.

Applications can increase or decrease this as desired. The trade-off to understand is that documents that are being mutated in a transaction A, are effectively locked from being updated by other transactions until transaction A has completed - committed or rolled back. If transaction A is unable to complete for whatever reason, the document can be locked for this expirationTime time.

It is worth noting that this setting does not completely guarantee that the transaction will immediately be completed after that time. In some rare cases, such as application crashes, it may take longer as the lost transactions cleanup process will be involved. More details are in cleanupWindow.

durabilityLevel

public TransactionConfigBuilder durabilityLevel(TransactionDurabilityLevel level)

All transaction writes will be performed with this durability setting. All writes in Couchbase go initially to one primary node, and from their fan-out to any configured replicas. If durability is disabled then the transaction will continue as soon as the write is available on the primary node. The durability setting will ensure the transaction does not continue until the write is available in more places. This can provide a small degree of extra security in the advent of node loss. The default setting is TransactionDurabilityLevel.MAJORITY, meaning a transaction will pause on each write until it is available in-memory on a majority of configured replicas.

logDirectly

public TransactionConfigBuilder logDirectly(com.couchbase.client.core.cnc.Event.Severity logLevel)

Logs all lines that are related to transactions and are at a level greater to or equal to logLevel, directly to the standard Couchbase logging event bus. Default is disabled.

Note that the application may instead prefer to use the TransactionLogger object contained in both TransactionResult and TransactionFailed, which contains the same information that will be logged by this method.

logOnFailure

public TransactionConfigBuilder logOnFailure(boolean logOnFailure,
                                             com.couchbase.client.core.cnc.Event.Severity logOnFailureLevel)

If a transaction fails, e.g. throws a TransactionFailed exception, then automatically log all lines that are related to that transactions and are at a level greater to or equal to logLevel, directly to the standard Couchbase logger. Default is disabled.

keyValueTimeout

public TransactionConfigBuilder keyValueTimeout(java.time.Duration timeout)

Sets the default timeout used with all key-value writes. By default this is whatever has been configured at the ClusterEnvironment level (for important mutating operations it will use the environment's kvDurableTimeout, else the environment's regular kvTimeout).

testFactories

@Stability.Internal
public TransactionConfigBuilder testFactories(AttemptContextFactory attemptContextFactory,
                                                                  CleanerFactory cleanerFactory,
                                                                  ClientRecordFactory clientRecordFactory)

For internal testing. Applications should not require this.

Parameters:

attemptContextFactory - provide a factory that will create AttemptContextReactive whenever one is required, allowing methods on this to be mocked out. Can be null, in which case the default factory will be used.

cleanerFactory - provide a factory that will create CleanerFactory whenever one is required, allowing methods on this to be mocked out. Can be null, in which case the default factory will be used.

clientRecordFactory - provide a factory that will create ClientRecordFactory whenever one is required, allowing methods on this to be mocked out. Can be null, in which case the default factory will be used.

persistentLogging

@Stability.Volatile
public TransactionConfigBuilder persistentLogging(com.couchbase.client.java.Collection collection)

Currently, this is to be used only with Couchbase guidance and instructions.

numATRs

@Stability.Internal
public TransactionConfigBuilder numATRs(int atrs)

Currently, this is to be used only with Couchbase guidance and instructions. Ensure that the same value is used for each client participating in transactions. The maximum possible value is ATRIds.MAX_ATRS

metadataCollection

@Stability.Volatile
public TransactionConfigBuilder metadataCollection(com.couchbase.client.java.Collection collection)

Allows setting a custom collection to use for any transactional metadata documents.

If not set, it will default to creating these documents in the default collection of the bucket that the first mutation document in the transaction is on.

This setting also configures where cleanup runs. By default, cleanup will check the default collection of all open buckets for transactional metadata. If this is set, cleanup will only check this metadata collection.