DocumentNodeInternalTransaction Method

Spotfire 14.2 API Reference
Starts an internal transaction on the document model by executing the specified executor delegate.

Namespace:  Spotfire.Dxp.Framework.DocumentModel
Assembly:  Spotfire.Dxp.Framework (in Spotfire.Dxp.Framework.dll) Version: 64.0.19329.3263 (64.0.19329.3263)
Syntax

C#
protected void InternalTransaction(
	Executor executor
)

Parameters

executor
Type: Spotfire.Dxp.Framework.DocumentModelExecutor
The delegate to execute.
Remarks

If there is already an ongoing transaction, internal or normal, then the transaction is included in the current transaction.

As with normal transactions, all commands that are executed as a result of the operations performed by executor will be recorded in the transaction so that the transaction can be unexecuted if the user requests an undo.

All internal events raised by operations performed by the executor are enqueued until the outermost internal transation completes. Duplicate internal events are removed while the executor is running. Thus if a property X is changed several times during the internal transaction, only one internal event will be raise to listeners on changes of X.

Internal transactions are intended to be used when implementing methods that perform large, composite operations on a sub tree in the document that need to appear atomic from the point of view of internal event handlers. All scenarios where it is motivated to use an internal transaction involve internal event handlers that trigger on changes in a sub tree and then access properties in the changed subtree under the assumption that some invariant is upheld. In such cases, wrapping the changes made by the operation in an internal transaction is essential since it guarantees that any internal event handlers are called first after all changes have been made and the invariant holds.

For example, consider a custom node, MyCustomNode, that contains two undoable cross reference properties to data columns, ColumnReference1 and ColumnReference2, with the invariant that they either both refer to data columns or both are null. Suppose that there is an internal event handler that triggers when either ColumnReference1 or ColumnReference2 is changed. If a method on MyCustomNode changes the references without using an internal transaction, the event handler will be invoked immediately when the first reference is changed. In this case, the event handler can access ColumnReference1 and ColumnReference2 while MyCustomNode is in a transient inconsistent state where the invariant is not upheld.

CAVEAT: In an operation that uses an internal transaction, do not change properties outside of the sub tree that defines the operations! Doing so might place the document in a transient inconsistent state and cause a crash if the document is accessed within the internal transaction.

Spotfire uses internal event handlers to keep different parts of the document in synch. For instance, the filters in a filtering scheme are synchronized with the columns in the data tables by internal event handlers. Thus if an internal transaction is wrapped around code that first removes some data columns and then inspects the filters, the filters will be read in an inconsistent state.

Version Information

Supported in: 14.2, 14.1, 14.0, 12.5, 12.4, 12.3, 12.2, 12.1, 12.0, 11.8, 11.7, 11.6, 11.5, 11.4
See Also

Reference