org.multiverse.api
Interface TransactionFactoryBuilder<T extends Transaction,B extends TransactionFactoryBuilder>

public interface TransactionFactoryBuilder<T extends Transaction,B extends TransactionFactoryBuilder>

An implementation of the builder design pattern to createReference a TransactionFactory. This is the place to be for transaction configuration. This approach also gives the freedom to access implementation specific setters by implementing and extending the TransactionFactoryBuilder interface.

Usage

In most cases the TransactionFactoryBuilder will be dropped once the TransactionFactory is created (the TransactionFactory is the one you want to store for later use).

Chained methods

It is important that the returned TransactionFactoryBuilder is used on the 'set' method because TransactionBuilders are immutable. If you don't do this, your transactions don't get the properties you want them to have.

Transaction familyName

This is purely used for debugging/profiling purposes. In the instrumentation the familyname is determined by the full method signature including the owning class.

The big advantage to a builder compared to just adding a big load of parameters or storing these parameters in a datastructure (so object without logic) is that the Stm implementation has a lot more room for adding custom parameters and stm-internal transaction-family related dependencies.

TransactionBuilders are immutable and therefor thread safe to use.

Author:

Peter Veentjer.

Method Summary

TransactionFactory<T>	build() Builds a TransactionFactory with the provided configuration.
BackoffPolicy	getBackoffPolicy() Return the BackoffPolicy used.
CommitLockPolicy	getCommitLockPolicy() Returns the CommitLockPolicy
String	getFamilyName() Returns the family name of the transaction.
int	getMaxReadSpinCount() Returns the maximum number of spins that should be executed when a transactional object can't be read because it is locked.
int	getMaxRetries() Returns the maximum number of times a transaction can be retried.
PropagationLevel	getPropagationLevel() Gets the PropagationLevel.
Stm	getStm() Returns the Stm that created this TransactionFactoryBuilder.
long	getTimeoutNs() Returns the timeout.
TraceLevel	getTraceLevel() Gets the TraceLevel.
boolean	isDirtyCheckEnabled() Checks if dirty check is enabled.
boolean	isExplicitRetryAllowed() Checks if explicit retry (for blocking operations) is allowed.
boolean	isInterruptible() Checks if the transaction is interruptible.
boolean	isQuickReleaseEnabled() Checks if quick release of locks while committing is enabled.
boolean	isReadonly() Checks if the transaction is readonly or an update.
boolean	isReadTrackingEnabled() Checks if the transaction automatically tracks reads.
boolean	isSpeculativeConfigurationEnabled() Checks if speculative configuration is enabled.
boolean	isWriteSkewAllowed() Checks if the writeskew problem is allowed to happen.
B	setBackoffPolicy(BackoffPolicy backoffPolicy) Sets the new backoff policy.
B	setCommitLockPolicy(CommitLockPolicy commitLockPolicy) Sets the CommitLockPolicy.
B	setDirtyCheckEnabled(boolean dirtyCheckEnabled) Sets id the dirty check is enabled.
B	setExplicitRetryAllowed(boolean explicitRetryEnabled) Sets if the Transaction is allowed to do an explicit retry (needed for a blocking operation).
B	setFamilyName(String familyName) Sets the transaction familyname.
B	setInterruptible(boolean interruptible) Sets if the transaction can be interrupted while doing blocking operations.
B	setMaxReadSpinCount(int maxReadSpinCount) Sets the maximum number of spins that should be executed when a transactional object can't be read because it is locked.
B	setMaxRetries(int maxRetries) Sets the the maximum count a transaction can be retried.
B	setPropagationLevel(PropagationLevel level) Sets the TransactionPropagationLevel.
B	setQuickReleaseEnabled(boolean enabled) Sets enabling quick release on locks is enabled.
B	setReadonly(boolean readonly) Sets the readonly property on a transaction.
B	setReadTrackingEnabled(boolean enabled) Sets if the transaction should automatically track all reads that have been done.
B	setSpeculativeConfigurationEnabled(boolean newValue) With the speculative configuration enabled, the stm is allowed to determine optimal settings for transactions.
B	setTimeoutNs(long timeoutNs) Sets the timeout (the maximum time a transaction is allowed to block.
B	setTraceLevel(TraceLevel traceLevel) Sets the TraceLevel.
B	setWriteSkewAllowed(boolean allowWriteSkew) If writeskew problem is allowed to happen.

Method Detail

getStm

Stm getStm()

Returns the Stm that created this TransactionFactoryBuilder.

Returns:

returns the Stm that created this TransactionFactoryBuilder.

getPropagationLevel

PropagationLevel getPropagationLevel()

Gets the PropagationLevel.

Returns:

the PropagationLevel.

setPropagationLevel

B setPropagationLevel(PropagationLevel level)

Sets the TransactionPropagationLevel.

Parameters:

level - the new PropagationLevel.

Returns:

the updated TransactionFactoryBuilder.

Throws:

NullPointerException - if level is null.

setTraceLevel

B setTraceLevel(TraceLevel traceLevel)

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

Parameters:

traceLevel - the new traceLevel.

Returns:

the updated TransactionFactoryBuilder.

Throws:

NullPointerException - if traceLevel is null.

See Also:

getTraceLevel()

getTraceLevel

TraceLevel getTraceLevel()

Gets the TraceLevel. With tracing it is possible to see what is happening inside a transaction.

Returns:

the TraceLevel.

See Also:

setTraceLevel(TraceLevel)

isDirtyCheckEnabled

boolean isDirtyCheckEnabled()

Checks if dirty check is enabled.

Returns:

true if enabled, false otherwise.

See Also:

setDirtyCheckEnabled(boolean)

setDirtyCheckEnabled

B setDirtyCheckEnabled(boolean dirtyCheckEnabled)

Sets id the dirty check is enabled. Dirty check is that something only needs to be written, if there really is a change. 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 TransactionFactoryBuilder.

See Also:

isDirtyCheckEnabled()

setExplicitRetryAllowed

B setExplicitRetryAllowed(boolean explicitRetryEnabled)

Sets if the Transaction 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:

explicitRetryEnabled - true if explicit retry is enabled, false otherwise.

Returns:

the updated TransactionFactoryBuilder

See Also:

isExplicitRetryAllowed()

isExplicitRetryAllowed

boolean isExplicitRetryAllowed()

Checks if explicit retry (for blocking operations) is allowed.

Returns:

true if allowed, false otherwise.

See Also:

setExplicitRetryAllowed(boolean)

setFamilyName

B setFamilyName(String familyName)

Sets the transaction familyname.

The transaction familyName is useful debugging purposes. With Multiverse 0.4 it was also needed for speculative configuration, but that requirement is dropped.

Parameters:

familyName - the familyName of the transaction.

Returns:

the updated TransactionFactoryBuilder

See Also:

getFamilyName()

getFamilyName

String getFamilyName()

Returns the family name of the transaction.

Returns:

the familyname of the transaction.

See Also:

setFamilyName(String)

setReadonly

B setReadonly(boolean readonly)

Sets the readonly property on a transaction. Readonly transactions are always cheaper than update transactions.

If this property is set, the stm will not speculate on this property anymore.

Parameters:

readonly - true if the transaction should be readonly, false otherwise.

Returns:

the updated TransactionFactoryBuilder

See Also:

isReadonly()

isReadonly

boolean isReadonly()

Checks if the transaction is readonly or an update.

Returns:

true if enabled, false otherwise.

See Also:

setReadonly(boolean)

setReadTrackingEnabled

B setReadTrackingEnabled(boolean enabled)

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

If this property is set, the stm will not speculate on this property anymore.

Parameters:

enabled - true if read tracking enabled, false otherwise.

Returns:

the updated TransactionFactoryBuilder

See Also:

isQuickReleaseEnabled()

isReadTrackingEnabled

boolean isReadTrackingEnabled()

Checks if the transaction automatically tracks reads.

Returns:

true if automatic read tracking is enabled, false otherwise.

See Also:

setReadTrackingEnabled(boolean)

setInterruptible

B setInterruptible(boolean interruptible)

Sets if the transaction can be interrupted while doing blocking operations.

Parameters:

interruptible - if the transaction can be interrupted while doing blocking operations.

Returns:

the updated TransactionFactoryBuilder

See Also:

isInterruptible()

isInterruptible

boolean isInterruptible()

Checks if the transaction is interruptible.

Returns:

true if interruptible, false otherwise.

See Also:

setInterruptible(boolean)

setCommitLockPolicy

B setCommitLockPolicy(CommitLockPolicy commitLockPolicy)

Sets the CommitLockPolicy. The CommitLockPolicy is only used by update transactions that commit: when the stm commits, locks need to be acquired on dirty objects.

Parameters:

commitLockPolicy - the new CommitLockPolicy

Returns:

the updated TransactionFactoryBuilder.

Throws:

NullPointerException - if commitLockPolicy is null.

See Also:

getCommitLockPolicy()

getCommitLockPolicy

CommitLockPolicy getCommitLockPolicy()

Returns the CommitLockPolicy

Returns:

the CommitLockPolicy.

setSpeculativeConfigurationEnabled

B setSpeculativeConfigurationEnabled(boolean newValue)

With the speculative configuration enabled, the stm is allowed to determine optimal settings for transactions. 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.

Parameters:

newValue - indicates if speculative configuration should be enabled.

Returns:

the updated TransactionFactoryBuilder

See Also:

isSpeculativeConfigurationEnabled()

isSpeculativeConfigurationEnabled

boolean isSpeculativeConfigurationEnabled()

Checks if speculative configuration is enabled.

Returns:

true if enabled, false otherwise.

See Also:

setSpeculativeConfigurationEnabled(boolean)

setWriteSkewAllowed

B setWriteSkewAllowed(boolean allowWriteSkew)

If writeskew problem is allowed to happen. Defaults to true and can have a big impact on performance (the complete read set needs to be validated and not just the writes). So disallow it wisely.

Parameters:

allowWriteSkew - indicates if writeSkew problem is allowed.

Returns:

the updated TransactionFactoryBuilder

See Also:

isWriteSkewAllowed()

isWriteSkewAllowed

boolean isWriteSkewAllowed()

Checks if the writeskew problem is allowed to happen.

Returns:

true if allowed, false otherwise.

See Also:

setWriteSkewAllowed(boolean)

setQuickReleaseEnabled

B setQuickReleaseEnabled(boolean enabled)

Sets enabling quick release on locks is enabled. When a transaction commits, it needs to acquire the writelocks. If quick release is disabled, first all writes are executed before any lock is released. With quick release enabled, the lock on the transactional object is released as soon as the write is done.

The 'disadvantage' of having this enabled is that it could happen that some objects modified in a transaction are releases and some are not. If another transaction picks up these objects, it could be that it is able to read some and fails on other. Normally this isn't an issue because the transaction is retried in combination with a back off policy.

Parameters:

enabled - true if the lock of a transaction object should be releases as soon as possible instead of waiting for the whole transaction to commit.

Returns:

the updated TransactionFactoryBuilder

See Also:

isQuickReleaseEnabled()

isQuickReleaseEnabled

boolean isQuickReleaseEnabled()

Checks if quick release of locks while committing is enabled.

Returns:

true if enabled, false otherwise.

See Also:

setQuickReleaseEnabled(boolean)

setBackoffPolicy

B setBackoffPolicy(BackoffPolicy backoffPolicy)

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

Parameters:

backoffPolicy - the backoff policy to use.

Returns:

the updated TransactionFactoryBuilder

Throws:

NullPointerException - if backoffPolicy is null.

See Also:

getBackoffPolicy()

getBackoffPolicy

BackoffPolicy getBackoffPolicy()

Return the BackoffPolicy used.

Returns:

the BackoffPolicy.

See Also:

setBackoffPolicy(org.multiverse.api.backoff.BackoffPolicy)

setTimeoutNs

B setTimeoutNs(long timeoutNs)

Sets the timeout (the maximum time a transaction is allowed to block. Long.MAX_VALUE indicates that no timeout should be used.

Parameters:

timeoutNs - the timeout specified in nano seconds

Returns:

the updated TransactionFactoryBuilder

getTimeoutNs

long getTimeoutNs()

Returns the timeout. Value will always be equal or larger than zero.

Returns:

the timeout.

See Also:

setTimeoutNs(long)

setMaxRetries

B setMaxRetries(int maxRetries)

Sets the the maximum count a transaction can be retried. The default is 1000. Setting it to a very low value could mean that a transaction can't complete.

Parameters:

maxRetries - the maximum number of times a transaction can be tried.

Returns:

the updated TransactionFactoryBuilder

Throws:

IllegalArgumentException - if retryCount smaller than 0.

getMaxRetries

int getMaxRetries()

Returns the maximum number of times a transaction can be retried. It doesn't matter if a retry is caused by explicit retries, or by more accidental retries(read/write conflicts).

Returns:

the maximum number of times a transaction can be retried. The returned value will always be equal or larger than 0.

setMaxReadSpinCount

B setMaxReadSpinCount(int maxReadSpinCount)

Sets the maximum number of spins that should be executed when a transactional object can't be read because it is locked. Watch out with setting this value too high, because a system could start livelocking.

Parameters:

maxReadSpinCount - the maximum number of spins.

Returns:

the updated TransactionFactoryBuilder.

Throws:

IllegalArgumentException - if smaller than 0.

See Also:

getMaxReadSpinCount()

getMaxReadSpinCount

int getMaxReadSpinCount()

Returns the maximum number of spins that should be executed when a transactional object can't be read because it is locked. Value will always be equal or larger than 0.

Returns:

the maximum number of spins

See Also:

setMaxReadSpinCount(int)

build

TransactionFactory<T> build()

Builds a TransactionFactory with the provided configuration.

Returns:

the started Transaction.

Throws:

IllegalStateException - if this TransactionFactoryBuilder is not configured correctly and therefor the TransactionFactory can't be created.