org.multiverse.api

## Interface TxnFactoryBuilder

All Known Subinterfaces:
  GammaTxnFactoryBuilder

    public interface TxnFactoryBuilder

A Builder for creating a `TxnFactory` and `TxnExecutor`. This builder provides full control on transaction settings.

Since the `Txn` and `TxnExecutor` are very closely integrated, both of them are created by this TxnFactoryBuilder.

Instances of this class are considered immutable, so when you call one of the modifying methods, make sure that you use the resulting TxnFactoryBuilder. Normally with the builder implementation the same instance is returned. In this case this isn't true because a new instance is returned every time.

See Also:
  `TxnFactory`, `TxnConfig`

### Method Summary

Methods
`TxnFactoryBuilder` `addPermanentListener(TxnListener listener)` Adds a permanent `Txn` `TxnListener`.
`TxnConfig` `getConfig()` Returns the `TxnConfig` used by this TxnFactoryBuilder.
`TxnFactory` `newTransactionFactory()` Builds a new `TxnFactory`.
`TxnExecutor` `newTxnExecutor()` Builds a new `TxnExecutor` optimized for executing transactions created by this TxnFactoryBuilder.
`TxnFactoryBuilder` `setBackoffPolicy(BackoffPolicy backoffPolicy)` Sets the `Txn` `BackoffPolicy`.
`TxnFactoryBuilder` `setBlockingAllowed(boolean blockingAllowed)` Sets if the `Txn` is allowed to do an explicit retry (needed for a blocking operation).
`TxnFactoryBuilder` `setControlFlowErrorsReused(boolean reused)` Sets if the `ControlFlowError` is reused.
`TxnFactoryBuilder` `setDirtyCheckEnabled(boolean dirtyCheckEnabled)` Sets if the `Txn` dirty check is enabled.
`TxnFactoryBuilder` `setFamilyName(java.lang.String familyName)` Sets the `Txn` familyname.
`TxnFactoryBuilder` `setInterruptible(boolean interruptible)` Sets if the `Txn` can be interrupted while doing blocking operations.
`TxnFactoryBuilder` `setIsolationLevel(IsolationLevel isolationLevel)` Sets the `IsolationLevel` on the `Txn`.
`TxnFactoryBuilder` `setMaxRetries(int maxRetries)` Sets the the maximum count a `Txn` can be retried.
`TxnFactoryBuilder` `setPropagationLevel(PropagationLevel propagationLevel)` Sets the `PropagationLevel` used.
`TxnFactoryBuilder` `setReadLockMode(LockMode lockMode)` Sets the `Txn` `LockMode` for all reads.
`TxnFactoryBuilder` `setReadonly(boolean readonly)` Sets the readonly property on a `Txn`.
`TxnFactoryBuilder` `setReadTrackingEnabled(boolean enabled)` Sets if the `Txn` should automatically track all reads that have been done.
`TxnFactoryBuilder` `setSpeculative(boolean speculative)` With the speculative configuration enabled, the `Stm` is allowed to determine optimal settings for a `Txn`.
`TxnFactoryBuilder` `setSpinCount(int spinCount)` Sets the maximum number of spins that are allowed when a `Txn` can't be read/written/locked because it is locked by another transaction.
`TxnFactoryBuilder` `setTimeoutNs(long timeoutNs)` Sets the timeout (the maximum time a `Txn` is allowed to block.
`TxnFactoryBuilder` `setTraceLevel(TraceLevel traceLevel)` Sets the `Txn` `TraceLevel`.
`TxnFactoryBuilder` `setWriteLockMode(LockMode lockMode)` Sets the `Txn` `LockMode` for all writes.

### Method Detail

#### getConfig

    TxnConfig getConfig()

Returns the `TxnConfig` used by this TxnFactoryBuilder.

Returns:
  the used TxnConfig.

#### setControlFlowErrorsReused

    TxnFactoryBuilder setControlFlowErrorsReused(boolean reused)

Sets if the `ControlFlowError` is reused. Normally you don't want to reuse them because they can be expensive to create (especially the stacktrace) and they could be created very often. But for debugging purposes it can be quite annoying because you want to see the stacktrace.

Parameters:
  `reused` - true if ControlFlowErrors should be reused.
Returns:
  the updated TxnFactoryBuilder.
See Also:
  `TxnConfig.isControlFlowErrorsReused()`

#### setFamilyName

    TxnFactoryBuilder setFamilyName(java.lang.String familyName)

Sets the `Txn` familyname. If an `TxnExecutor` is used inside a method, a useful familyname could be the full name of the class and the method.

The transaction familyName is useful debugging purposes, but has not other meaning.

Parameters:
  `familyName` - the familyName of the transaction.
Returns:
  the updated TxnFactoryBuilder
Throws:
  `java.lang.NullPointerException` - if familyName is null.
See Also:
  `TxnConfig.getFamilyName()`

#### setPropagationLevel

    TxnFactoryBuilder setPropagationLevel(PropagationLevel propagationLevel)

Sets the `PropagationLevel` used. With the PropagationLevel you have control on how the transaction deals with transaction nesting. The default is `PropagationLevel.Requires` which automatically starts a transaction is one is missing, or lifts on a transaction if available.

Parameters:
  `propagationLevel` - the new PropagationLevel
Returns:
  the updated TxnFactoryBuilder
Throws:
  `java.lang.NullPointerException` - if propagationLevel is null.
See Also:
  `TxnConfig.getPropagationLevel()`, `PropagationLevel`

#### setReadLockMode

    TxnFactoryBuilder setReadLockMode(LockMode lockMode)

Sets the `Txn` `LockMode` for all reads. If a LockMode is set higher than `LockMode.None`, this transaction will locks all reads (and writes since a read is needed for a write) and the transaction automatically becomes serialized.

Parameters:
  `lockMode` - the LockMode to set.
Returns:
  the updated TxnFactoryBuilder.
Throws:
  `java.lang.NullPointerException` - if lockMode is null.
See Also:
  `TxnConfig.getReadLockMode()`, `LockMode`

#### setWriteLockMode

    TxnFactoryBuilder setWriteLockMode(LockMode lockMode)

Sets the `Txn` `LockMode` for all writes. For a write, always a read needs to be done, so if the read LockMode is

Freshly constructed objects that are not committed, automatically are locked with `LockMode.Exclusive`.

If the write LockMode is set after the read LockMode and the write LockMode is lower than the read LockMode, an `IllegalTxnFactoryException` will be thrown when a `TxnFactory` is created.

If the write LockMode is set before the read LockMode and the write LockMode is lower than the read LockMode, the write LockMode automatically is upgraded to that of the read LockMode. This makes setting the readLock mode less of a nuisance.

Parameters:
  `lockMode` - the LockMode to set.
Returns:
  the updated TxnFactoryBuilder.
Throws:
  `java.lang.NullPointerException` - if lockMode is null.
See Also:
  `TxnConfig.getWriteLockMode()`, `LockMode`

#### addPermanentListener

    TxnFactoryBuilder addPermanentListener(TxnListener listener)

Adds a permanent `Txn` `TxnListener`. All permanent listeners are always executed after all normal listeners are executed. If the same listener is added multiple times, it will be executed multiple times.

This method is very useful for integrating Multiverse in other JVM based environments because with this approach you have a callback when transaction aborts/commit and can add your own logic. See the `TxnListener` for more information about normal vs permanent listeners.

Parameters:
  `listener` - the permanent listener to add.
Returns:
  the updated TxnFactoryBuilder.
Throws:
  `java.lang.NullPointerException` - if listener is null.
See Also:
  `TxnConfig.getPermanentListeners()`

#### setTraceLevel

    TxnFactoryBuilder setTraceLevel(TraceLevel traceLevel)

Sets the `Txn` `TraceLevel`. With tracing it is possible to see what is happening inside a transaction.

Parameters:
  `traceLevel` - the new traceLevel.
Returns:
  the updated TxnFactoryBuilder.
Throws:
  `java.lang.NullPointerException` - if traceLevel is null.
See Also:
  `TxnConfig.getTraceLevel()`, `TraceLevel`

#### setTimeoutNs

    TxnFactoryBuilder setTimeoutNs(long timeoutNs)

Sets the timeout (the maximum time a `Txn` is allowed to block. Long.MAX_VALUE indicates that an unbound timeout should be used.

Parameters:
  `timeoutNs` - the timeout specified in nano seconds
Returns:
  the updated TxnFactoryBuilder
See Also:
  `TxnConfig.getTimeoutNs()`, `Txn.getRemainingTimeoutNs()`

#### setInterruptible

    TxnFactoryBuilder setInterruptible(boolean interruptible)

Sets if the `Txn` can be interrupted while doing blocking operations.

Parameters:
  `interruptible` - if the transaction can be interrupted while doing blocking operations.
Returns:
  the updated TxnFactoryBuilder
See Also:
  `TxnConfig.isInterruptible()`

#### setBackoffPolicy

    TxnFactoryBuilder setBackoffPolicy(BackoffPolicy backoffPolicy)

Sets the `Txn` `BackoffPolicy`. Policy is used to backoff when a transaction conflicts with another `Txn`. See the `BackoffPolicy` for more information.

Parameters:
  `backoffPolicy` - the backoff policy to use.
Returns:
  the updated TxnFactoryBuilder
Throws:
  `java.lang.NullPointerException` - if backoffPolicy is null.
See Also:
  `TxnConfig.getBackoffPolicy()`

#### setDirtyCheckEnabled

    TxnFactoryBuilder setDirtyCheckEnabled(boolean dirtyCheckEnabled)

Sets if the `Txn` dirty check is enabled. Dirty check is that something only needs to be written, if there really is a change (else it will be interpreted as a read). If it is disabled, it will always write, and this could prevent the aba isolation anomaly, but causes more conflicts so more contention. In most cases enabling it is the best option.

Parameters:
  `dirtyCheckEnabled` - true if dirty check should be executed, false otherwise.
Returns:
  the updated TxnFactoryBuilder.
See Also:
  `TxnConfig.isDirtyCheckEnabled()`

#### setSpinCount

    TxnFactoryBuilder setSpinCount(int spinCount)

Sets the maximum number of spins that are allowed when a `Txn` can't be read/written/locked because it is locked by another transaction.

Setting the value to a very high value, could lead to more an increased chance of a live locking.

Parameters:
  `spinCount` - the maximum number of spins
Returns:
  the updated TxnFactoryBuilder.
Throws:
  `java.lang.IllegalArgumentException` - if spinCount smaller than 0.
See Also:
  `TxnConfig.getSpinCount()`

#### setReadonly

    TxnFactoryBuilder setReadonly(boolean readonly)

Sets the readonly property on a `Txn`. If a transaction is configured as readonly, no write operations (also no construction of new transactional objects making use of that transaction) is allowed

Parameters:
  `readonly` - true if the transaction should be readonly, false otherwise.
Returns:
  the updated TxnFactoryBuilder
See Also:
  `TxnConfig.isReadonly()`

#### setReadTrackingEnabled

    TxnFactoryBuilder setReadTrackingEnabled(boolean enabled)

Sets if the `Txn` should automatically track all reads that have been done. This is needed for blocking operations, but also for other features like writeskew detection.

Tracking reads puts more pressure on the transaction since it needs to store all reads, but it reduces the chance of read conflicts, since once read from main memory, it can be retrieved from the transaction. The transaction is free to track reads even though this property is disabled.

Parameters:
  `enabled` - true if read tracking enabled, false otherwise.
Returns:
  the updated TxnFactoryBuilder
See Also:
  `TxnConfig.isReadTrackingEnabled()`

#### setSpeculative

    TxnFactoryBuilder setSpeculative(boolean speculative)

With the speculative configuration enabled, the `Stm` is allowed to determine optimal settings for a `Txn`.

Some behavior like readonly or the need for tracking reads can be determined runtime. The system can start with a readonly non readtracking transaction and upgrade to an update or a read tracking once a write or retry happens.

It depends on the `Stm` implementation on which properties it is going to speculate.

Enabling it can cause a few unexpected 'retries' of transactions, but it can seriously improve performance.

Parameters:
  `speculative` - indicates if speculative configuration should be enabled.
Returns:
  the updated TxnFactoryBuilder
See Also:
  `TxnConfig.isSpeculative()`

#### setMaxRetries

    TxnFactoryBuilder setMaxRetries(int maxRetries)

Sets the the maximum count a `Txn` can be retried. The default is 1000. Setting it to a very low value could mean that a transaction can't complete. Setting it to a very high value could lead to live-locking.

If the speculative configuration mechanism is enabled (`setSpeculative(boolean)`), a few retries are done in the beginning to figure out the best settings.

Parameters:
  `maxRetries` - the maximum number of times a transaction can be tried.
Returns:
  the updated TxnFactoryBuilder
Throws:
  `java.lang.IllegalArgumentException` - if maxRetries smaller than 0.
See Also:
  `TxnConfig.getMaxRetries()`

#### setIsolationLevel

    TxnFactoryBuilder setIsolationLevel(IsolationLevel isolationLevel)

Sets the `IsolationLevel` on the `Txn`.

The `Txn` is free to upgraded to a higher `IsolationLevel`. This is essentially the same behavior you get when Oracle is used, where a read uncommitted is upgraded to a read committed and a repeatable read is upgraded to the Oracle version of serialized (so with the writeskew problem still there).

Parameters:
  `isolationLevel` - the new IsolationLevel
Returns:
  the updated TxnFactoryBuilder
Throws:
  `java.lang.NullPointerException` - if isolationLevel is null.
See Also:
  `TxnConfig.getIsolationLevel()`, `IsolationLevel`

#### setBlockingAllowed

    TxnFactoryBuilder setBlockingAllowed(boolean blockingAllowed)

Sets if the `Txn` is allowed to do an explicit retry (needed for a blocking operation). One use case for disallowing it, it when the transaction is used inside an actor, and you don't want that inside the logic executed by the agent a blocking operations is done (e.g. taking an item of a blocking queue).

Parameters:
  `blockingAllowed` - true if explicit retry is allowed, false otherwise.
Returns:
  the updated TxnFactoryBuilder

#### newTransactionFactory

    TxnFactory newTransactionFactory()

Builds a new `TxnFactory`.

Returns:
  the build TxnFactory.
Throws:
  `IllegalTxnFactoryException` - if the TxnFactory could not be build because the configuration was not correct.

#### newTxnExecutor

    TxnExecutor newTxnExecutor()

Builds a new `TxnExecutor` optimized for executing transactions created by this TxnFactoryBuilder.

Returns:
  the created TxnExecutor.
Throws:
  `IllegalTxnFactoryException` - if the TxnFactory could not be build because the configuration was not correct.