agi.foundation.infrastructure.threading

(agi.foundation.tracking-2021r1.jar)

Class TransactedProperty<T>

java.lang.Object

agi.foundation.infrastructure.threading.TransactedObject

agi.foundation.infrastructure.threading.TransactedProperty<T>

Type Parameters:

T - The type of the property. This type must be immutable (meaning it cannot be changed after it is constructed) or it must be treated as such.

public class TransactedProperty<T>
extends TransactedObject

A property that participates in the software transactional memory (STM) system. The property's value must be read and modified in the context of a Transaction, which guarantees snapshot isolation for all properties in a TransactionContext.

Constructor Summary

Constructors

Constructor and Description
TransactedProperty(TransactionContext context, Object owner) Initializes a new property with a specified context and owner.
TransactedProperty(TransactionContext context, Object owner, T value) Initializes a new property with a specified context, owner, and value.

Method Summary

Modifier and Type	Method and Description
void	addChanged(EventHandler<TransactedPropertyChangedEventArgs<T>> value) Adds a handler for an event that is raised when a transaction that changes this property is Committed (add / remove).
void	ensureValue(Transaction transaction) At Transaction.commit() time, ensures that the value of this property, as seen by a given Transaction, has not changed.
T	getValue(Transaction transaction) Gets the value of this transacted property in the context of the given transaction, guaranteeing snapshot isolation.
void	removeChanged(EventHandler<TransactedPropertyChangedEventArgs<T>> value) Removes a handler for an event that is raised when a transaction that changes this property is Committed (add / remove).
void	setValue(Transaction transaction, T value) Sets the value of this property in the context of the specified transaction.
String	toString() Get a String that represents the value of this transacted property.

Methods inherited from class agi.foundation.infrastructure.threading.TransactedObject

checkTransaction, getContext, getOwner

Methods inherited from class java.lang.Object

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

Constructor Detail

TransactedProperty

public TransactedProperty(@Nonnull
                          TransactionContext context,
                          Object owner)

Initializes a new property with a specified context and owner. The value of the property will be the default value for the type T.

Parameters:

context - The context in which this property can be read and modified.

owner - The object that owns this property.

TransactedProperty

public TransactedProperty(@Nonnull
                          TransactionContext context,
                          Object owner,
                          T value)

Initializes a new property with a specified context, owner, and value.

Parameters:

context - The context in which this property can be read and modified.

owner - The object that owns this property.

value - The initial value of the property.

Method Detail

addChanged

public final void addChanged(EventHandler<TransactedPropertyChangedEventArgs<T>> value)

Adds a handler for an event that is raised when a transaction that changes this property is Committed (add / remove). See the Remarks section for more information.

This event is raised in the thread that committed the transaction and is raised inside the commit lock. This means that it is only raised by one thread at a time and it is raised once per transaction in the order in which the transactions are committed.

When this event is raised, all values modified by the transaction have already been committed and will be visible to a transaction started within an event handler. Attempting to commit another transaction within a handler hooked up to this event will result in an IllegalStateException, however. If additional changes are necessary, use the ChainedTransaction (get) and do not manually commit it. It will be automatically committed after all handlers for this event have finished executing. It is guaranteed that the chained transaction will commit immediately after all event handlers return, before any other transaction can commit, and that it will not raise a TransactionConflictException.

It is very important that subscribers to this event execute very quickly in order to avoid blocking the entire transaction system.

Parameters:

value - The handler.

removeChanged

public final void removeChanged(EventHandler<TransactedPropertyChangedEventArgs<T>> value)

Removes a handler for an event that is raised when a transaction that changes this property is Committed (add / remove). See the Remarks section for more information.

This event is raised in the thread that committed the transaction and is raised inside the commit lock. This means that it is only raised by one thread at a time and it is raised once per transaction in the order in which the transactions are committed.

When this event is raised, all values modified by the transaction have already been committed and will be visible to a transaction started within an event handler. Attempting to commit another transaction within a handler hooked up to this event will result in an IllegalStateException, however. If additional changes are necessary, use the ChainedTransaction (get) and do not manually commit it. It will be automatically committed after all handlers for this event have finished executing. It is guaranteed that the chained transaction will commit immediately after all event handlers return, before any other transaction can commit, and that it will not raise a TransactionConflictException.

It is very important that subscribers to this event execute very quickly in order to avoid blocking the entire transaction system.

Parameters:

value - The handler.

toString

public String toString()

Get a String that represents the value of this transacted property.

This method creates a new Transaction in which to obtain the current value of this transacted property.

Overrides:

toString in class Object

Returns:

The value of this transacted property.

getValue

public final T getValue(@Nonnull
                        Transaction transaction)

Gets the value of this transacted property in the context of the given transaction, guaranteeing snapshot isolation. See the Remarks section for more information.

This method guarantees snapshot isolation. This means that it will return either the last value that was passed to TransactedProperty.setValue(agi.foundation.Transaction, T) within the same transaction, or the value of this transacted property that was in place when the transaction started. This is true even if other transactions have committed a change to this transacted property since this transaction started.

If you need to ensure that the value returned by this method is the latest one, call TransactedProperty.ensureValue(agi.foundation.Transaction). When a transaction is committed, a TransactionConflictException will be raised if an ensured value was changed by a previously committed transaction.

Parameters:

transaction - The transaction in which to obtain the value of the property.

Returns:

The value.

ensureValue

public final void ensureValue(@Nonnull
                              Transaction transaction)

At Transaction.commit() time, ensures that the value of this property, as seen by a given Transaction, has not changed. If another transaction commits a change to this property after the specified transaction starts, the specified transaction will throw TransactionConflictException when it is committed.

Parameters:

transaction - The transaction in which to ensure that the value of the property does not change.

setValue

public final void setValue(@Nonnull
                           Transaction transaction,
                           T value)

Sets the value of this property in the context of the specified transaction. The changed value will not be visible to other transactions until Transaction.commit() is called. Calling this method may cause a TransactionConflictException to be raised at Transaction.commit() time. See the Remarks section for more information.

Calling this method may cause the transaction to raise a TransactionConflictException at commit time. This will happen if another transaction changes this same TransactedProperty and it commits after this transaction starts. Consider using TransactionContext.doTransactionally(agi.foundation.compatibility.Action1<agi.foundation.Transaction>) to automatically retry a transaction until it commits successfully.

Parameters:

transaction - The transaction in which to set the value.

value - The new value of the property.