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
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description TransactionConfig
build()
Converts this mutable instance into an immutableTransactionConfig
that's ready to be used withTransactions
.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 newTransactionConfigBuilder
, which can be used to build up and create aTransactionConfig
.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 tologLevel
, 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
queryConfig(TransactionQueryConfigBuilder queryConfig)
Sets the default query configuration for all transactions.TransactionConfigBuilder
testFactories(AttemptContextFactory attemptContextFactory, CleanerFactory cleanerFactory, ClientRecordFactory clientRecordFactory)
For internal testing.
-
-
-
Method Detail
-
create
public static TransactionConfigBuilder create()
Returns a newTransactionConfigBuilder
, which can be used to build up and create aTransactionConfig
.
-
build
public TransactionConfig build()
Converts this mutable instance into an immutableTransactionConfig
that's ready to be used withTransactions
.
-
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 aTransactionExpired
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 tologLevel
, 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 bothTransactionResult
andTransactionFailed
, 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 aTransactionFailed
exception, then automatically log all lines that are related to that transactions and are at a level greater to or equal tologLevel
, 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
@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 createAttemptContextReactive
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 createCleanerFactory
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 createClientRecordFactory
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
@Volatile public TransactionConfigBuilder persistentLogging(com.couchbase.client.java.Collection collection)
Currently, this is to be used only with Couchbase guidance and instructions.
-
numATRs
@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
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.
-
queryConfig
public TransactionConfigBuilder queryConfig(TransactionQueryConfigBuilder queryConfig)
Sets the default query configuration for all transactions.- Parameters:
queryConfig
- the query configuration to use- Returns:
- this, for chaining
-
-