Skip to main content

Pentaho+ documentation is moving!

The new product documentation portal is here. Check it out now at docs.hitachivantara.com

 

Hitachi Vantara Lumada and Pentaho Documentation

Transaction

pentaho.type.action Transaction

A Transaction object stores information about changes performed to instances.

When a transaction is the ambient transaction, it stores the changes performed to any instances. All of the changes performed are temporary and no change events are emitted, until the transaction is committed.

The ambient transaction is accessible through Transaction.current.

All of the changes are immediately visible, through any read operations of the modified instances, while the transaction is the ambient transaction.

If a transaction ceases to be the ambient transaction, then all of the changes that it captured suddenly become inaccessible.

If a transaction is later committed, and is successful, every change becomes permanent. Otherwise, if the transaction is simply disposed of, all the changes it captured are lost.

Managing the ambient transaction is best handled implicitly, by delegating to a TransactionScope object.

AMD Module

require(["pentaho/type/action/Transaction"], function(Transaction) { /* code goes here */ });

Extends

Implements

Constructor

Name Description
new Transaction()

Creates a Transaction.

Members

Name Description
current :  pentaho.type.action.Transaction
Static

Gets the ambient transaction, if any, or null.

__isInside :  boolean

Indicates if currently calling any of the methods: execute, executeWill, _onPhaseFinally__executePhaseFinally.

action :  pentaho.type.action.Base

Gets the action of the action execution.

base :  function
Protected

If a method has been overridden, then the base method provides access to the overridden method.

error :  Error | pentaho.lang.UserError

Gets the reason for a rejected action execution, or null.

isCanceled :  boolean

Gets a value that indicates if the action execution has been canceled.

isCurrent :  boolean

Gets a value that indicates if this transaction is the current transaction.

isDone :  boolean

Gets a value that indicates if the action execution completed successfully.

isExecuting :  boolean

Gets a value that indicates if the action execution is executing.

isFailed :  boolean

Gets a value that indicates if the action execution has failed.

isFinished :  boolean

Gets a value that indicates if the action execution has finished.

isReadOnly :  boolean

Gets a value that indicates if the transaction is in a read-only state.

isRejected :  boolean

Gets a value that indicates if the action execution has been rejected.

isSettled :  boolean

Gets a value that indicates if the action execution has been settled.

isSync :  boolean

Gets a value that indicates if the execution is synchronous.

isUnstarted :  boolean

Gets a value that indicates if the action execution is in the unstarted state.

promise :  Promise

Gets a promise for the result (or error) of this action execution.

result :  *

Gets the result of a successful action execution, if any.

state :  pentaho.type.action.States

Gets the current action execution state.

target :  pentaho.type.mixins.Container

Gets the target of the action execution.

version :  number

Gets the current transaction version.

Methods

Name Description
enter() : pentaho.type.action.TransactionScope
Static

Enters a scope of change.

enterCommitted() : pentaho.type.action.CommittedScope
Static

Enters a read-committed scope.

getChangesetsPending(container) : Array.<pentaho.type.action.Changeset>
Static

Gets any changesets still being delivered through notifications in the commit phase of transactions.

_doDefault() : Promise
Protected

Performs the default "execution" for the associated action.

_lockAction()
Protected

Locks the action.

_onPhaseDo() : Promise
Protected

Called during the action's do phase.

_onPhaseFinally()
Protected

Called during the action's finally phase.

_onPhaseInit()
Protected

Called during the action execution's initialize phase.

_onPhaseWill()
Protected

Called during the action execution's will phase.

_validate() : Array.<Error>
Protected

Validates that the action execution is valid for entering the will phase.

done(result) : pentaho.type.action.Execution

Called from an action observer to settle the action execution as being done, optionally giving a result value.

ensureChangeset(target) : pentaho.type.action.Changeset

Called to obtain a changeset for a given container in this transaction.

enter() : pentaho.type.action.TransactionScope

Enters the transaction and returns a new transaction scope to control the transaction.

execute() : pentaho.type.action.Execution

Executes the action.

executeWill() : pentaho.type.action.Execution

Executes up to the 'will' phase of the action.

extend(source, keyArgs) : object

Extend an object with the properties of another.

getAmbientReferences(container) : pentaho.type.ReferenceList

Gets the ambient references of a given container, if any.

getChangeset(uid) : pentaho.type.action.Changeset

Gets the changeset of an instance, given its unique identifier.

reject(reason) : pentaho.type.action.Execution

Called to settle the action execution as rejected.

Constructor Details

new Transaction()

Creates a Transaction.

Source: javascript/web/pentaho/type/action/Transaction.js, line 87

Members Details

current:  pentaho.type.action.Transaction
Static

Gets the ambient transaction, if any, or null.

Source: javascript/web/pentaho/type/action/Transaction.js, line 835

__isInside:  boolean

Indicates if currently calling any of the methods: execute, executeWill, _onPhaseFinally__executePhaseFinally.

Source: javascript/web/pentaho/action/Execution.js, line 202

Inherited From: pentaho.action.Execution#__isInside

Default Value: false

See also: pentaho.action.Execution#__callInside

action:  pentaho.type.action.Base

Gets the action of the action execution.

Once the action execution enters the will phase, this object gets frozen and can no longer be modified.

Source: javascript/web/pentaho/action/Execution.js, line 229

Overrides: pentaho.action.Execution#action

base:  function
Protected

If a method has been overridden, then the base method provides access to the overridden method.

Can also be called from within a constructor function.

Source: javascript/web/pentaho/lang/Base.js, line 299

Inherited From: pentaho.lang.Base#base

error:  Error | pentaho.lang.UserError

Gets the reason for a rejected action execution, or null.

This property only returns a non-null value if isRejected is true.

Source: javascript/web/pentaho/action/Execution.js, line 323

Inherited From: pentaho.action.Execution#error

isCanceled:  boolean

Gets a value that indicates if the action execution has been canceled.

An action execution is considered canceled if its state has the canceled bit on.

Source: javascript/web/pentaho/action/Execution.js, line 391

Inherited From: pentaho.action.Execution#isCanceled

See also: pentaho.type.action.Execution#isRejected

isCurrent:  boolean

Gets a value that indicates if this transaction is the current transaction.

Source: javascript/web/pentaho/type/action/Transaction.js, line 379

isDone:  boolean

Gets a value that indicates if the action execution completed successfully.

An action execution is considered done if its state has the did bit on.

Source: javascript/web/pentaho/action/Execution.js, line 440

Inherited From: pentaho.action.Execution#isDone

See also: pentaho.type.action.Execution#isSettled , pentaho.type.action.Execution#result

isExecuting:  boolean

Gets a value that indicates if the action execution is executing.

An action execution is considered executing if it has started but not yet finished, i.e., if its state is not the unstarted state or any of the finished states.

Source: javascript/web/pentaho/action/Execution.js, line 424

Inherited From: pentaho.action.Execution#isExecuting

See also: pentaho.type.action.Execution#isUnstarted , pentaho.type.action.Execution#isFinished

isFailed:  boolean

Gets a value that indicates if the action execution has failed.

An action execution is considered failed if its state has the failed bit on.

Source: javascript/web/pentaho/action/Execution.js, line 406

Inherited From: pentaho.action.Execution#isFailed

See also: pentaho.type.action.Execution#isRejected

isFinished:  boolean

Gets a value that indicates if the action execution has finished.

An action execution is considered finished if its state has the finished bit on.

When finished, one of the bits did, canceled or failed must also be on.

Source: javascript/web/pentaho/action/Execution.js, line 462

Inherited From: pentaho.action.Execution#isFinished

See also: pentaho.type.action.Execution#isSettled

isReadOnly:  boolean

Gets a value that indicates if the transaction is in a read-only state.

A transaction becomes read-only when it is previewed, committed or rejected.

Source: javascript/web/pentaho/type/action/Transaction.js, line 204

isRejected:  boolean

Gets a value that indicates if the action execution has been rejected.

An action execution is considered rejected if its state has one of the following bits on: canceled or failed.

Source: javascript/web/pentaho/action/Execution.js, line 376

Inherited From: pentaho.action.Execution#isRejected

See also: pentaho.type.action.Execution#isCanceled , pentaho.type.action.Execution#isFailed , pentaho.type.action.Execution#isDone , pentaho.type.action.Execution#isSettled , pentaho.type.action.Execution#error

isSettled:  boolean

Gets a value that indicates if the action execution has been settled.

An action execution is considered settled if its state has one of the following bits on: did, failed or canceled.

When an execution is settled it may not yet be [finished]{@see pentaho.type.action.Execution#isFinished}.

Source: javascript/web/pentaho/action/Execution.js, line 356

Inherited From: pentaho.action.Execution#isSettled

See also: pentaho.type.action.Execution#isCanceled , pentaho.type.action.Execution#isFailed , pentaho.type.action.Execution#isDone

isSync:  boolean

Gets a value that indicates if the execution is synchronous.

Source: javascript/web/pentaho/action/Execution.js, line 248

Overrides: pentaho.action.Execution#isSync

isUnstarted:  boolean

Gets a value that indicates if the action execution is in the unstarted state.

Source: javascript/web/pentaho/action/Execution.js, line 334

Inherited From: pentaho.action.Execution#isUnstarted

promise:  Promise

Gets a promise for the result (or error) of this action execution.

This promise can be requested anytime, before the execution has started, during execution, or after execution has finished. It can also be requested whether or not the associated action is synchronous or asynchronous.

The promise is fulfilled with the action execution's result or rejected with the action execution's error.

Source: javascript/web/pentaho/action/Execution.js, line 485

Inherited From: pentaho.action.Execution#promise

result:  *

Gets the result of a successful action execution, if any.

This property only returns a non-undefined value if isDone is true.

Source: javascript/web/pentaho/action/Execution.js, line 310

Inherited From: pentaho.action.Execution#result

state:  pentaho.type.action.States

Gets the current action execution state.

Source: javascript/web/pentaho/action/Execution.js, line 279

Inherited From: pentaho.action.Execution#state

See also: pentaho.type.action.Execution#isUnstarted , pentaho.type.action.Execution#isExecuting , pentaho.type.action.Execution#isSettled , pentaho.type.action.Execution#isDone , pentaho.type.action.Execution#isRejected , pentaho.type.action.Execution#isCanceled , pentaho.type.action.Execution#isFailed , pentaho.type.action.Execution#isFinished

target:  pentaho.type.mixins.Container

Gets the target of the action execution.

Source: javascript/web/pentaho/type/action/Transaction.js, line 232

Overrides: pentaho.action.Execution#target

version:  number

Gets the current transaction version.

Beware, this version number is not the same as that of pentaho.type.mixins.Container#$version.

Initially, a transaction has version 0. This number is then incremented per each individual made change. Each change indicates the version it caused the transaction to assume: pentaho.type.action.Change#transactionVersion.

Source: javascript/web/pentaho/type/action/Transaction.js, line 191

Methods Details

enter() : pentaho.type.action.TransactionScope
Static

Enters a scope of change.

To mark the changes in the scope as error, call its reject method.

To end the scope of change successfully, dispose the returned transaction scope, by calling its dispose method.

If the scope initiated a transaction, then that transaction is committed. Otherwise, if an ambient transaction already existed when the change scope was created, that transaction is left uncommitted.

To end the scope with an error, call its reject method.

Source: javascript/web/pentaho/type/action/Transaction.js, line 860

Returns:
Name Description
pentaho.type.action.TransactionScope

The new transaction scope.

enterCommitted() : pentaho.type.action.CommittedScope
Static

Enters a read-committed scope.

Within this scope there is no current transaction and reading the properties of instances obtains their committed values.

Source: javascript/web/pentaho/type/action/Transaction.js, line 873

Returns:
Name Description
pentaho.type.action.CommittedScope

The read-committed scope.

getChangesetsPending(container) : Array.<pentaho.type.action.Changeset>
Static

Gets any changesets still being delivered through notifications in the commit phase of transactions.

If a transaction is started and committed from within the change:finally listener of another, then multiple changesets may be returned.

Source: javascript/web/pentaho/type/action/Transaction.js, line 889

Parameters:
Name Default Value Summary
container : pentaho.type.mixins.Container

The container.

Returns:
Name Description
Array.<pentaho.type.action.Changeset>

An array of changesets, if any changeset exists; null otherwise.

_doDefault() : Promise
Protected

Performs the default "execution" for the associated action.

When the associated action is asynchronous, this method may return a promise. If the promise gets rejected, the action is rejected with the same rejection reason. However, if the promise gets fulfilled, its value is always ignored.

Source: javascript/web/pentaho/action/Execution.js, line 615

Inherited From: pentaho.action.Execution#_doDefault

Returns:
Name Description
Promise
  • A promise for the completion of the default execution of an asynchronous action, or null.
_lockAction()
Protected

Locks the action.

The default implementation locks the action by using the Object.freeze() method.

Source: javascript/web/pentaho/action/Execution.js, line 891

Overrides: pentaho.action.Execution#_lockAction

_onPhaseDo() : Promise
Protected

Called during the action's do phase.

The default implementation does nothing.

Source: javascript/web/pentaho/action/Execution.js, line 1052

Overrides: pentaho.action.Execution#_onPhaseDo

Returns:
Name Description
Promise | null

A promise to the completion of the asynchronous do listener, of an asynchronous action, or null.

_onPhaseFinally()
Protected

Called during the action's finally phase.

The default implementation does nothing.

Source: javascript/web/pentaho/action/Execution.js, line 1063

Overrides: pentaho.action.Execution#_onPhaseFinally

_onPhaseInit()
Protected

Called during the action execution's initialize phase.

The default implementation does nothing.

Source: javascript/web/pentaho/action/Execution.js, line 1029

Overrides: pentaho.action.Execution#_onPhaseInit

_onPhaseWill()
Protected

Called during the action execution's will phase.

The default implementation does nothing.

Source: javascript/web/pentaho/action/Execution.js, line 1039

Overrides: pentaho.action.Execution#_onPhaseWill

_validate() : Array.<Error>
Protected

Validates that the action execution is valid for entering the will phase.

The default implementation validates the action.

Source: javascript/web/pentaho/action/Execution.js, line 903

Overrides: pentaho.action.Execution#_validate

Returns:
Name Description
Array.<Error> | null

A non-empty array of errors, if any; otherwise null.

done(result) : pentaho.type.action.Execution

Called from an action observer to settle the action execution as being done, optionally giving a result value.

Source: javascript/web/pentaho/action/Execution.js, line 631

Inherited From: pentaho.action.Execution#done

Parameters:
Name Default Value Summary
result : *
Optional

The result of the action execution, if any.

Returns:
Name Description
pentaho.type.action.Execution

The value of this.

Throws:
Name Description
pentaho.lang.OperationInvalidError

When the action execution is not in the do state.

ensureChangeset(target) : pentaho.type.action.Changeset

Called to obtain a changeset for a given container in this transaction.

Source: javascript/web/pentaho/type/action/Transaction.js, line 309

Parameters:
Name Default Value Summary
target : pentaho.type.mixins.Container

The changeset target container.

Returns:
Name Description
pentaho.type.action.Changeset

The existing or created changeset.

Throws:
Name Description
pentaho.lang.OperationInvalidError

When the transaction has already been previewed, committed or rejected, and thus can no longer be changed.

See also: pentaho.type.action.Changeset#__onChildChangesetCreated

enter() : pentaho.type.action.TransactionScope

Enters the transaction and returns a new transaction scope to control the transaction.

Source: javascript/web/pentaho/type/action/Transaction.js, line 393

Returns:
Name Description
pentaho.type.action.TransactionScope

The new transaction scope.

Throws:
Name Description
pentaho.lang.OperationInvalidError

When the transaction is resolved.

pentaho.type.action.TransactionRejectedError

When entering the root scope of the transaction and the transaction is automatically rejected due to a concurrency error.

execute() : pentaho.type.action.Execution

Executes the action.

When the associated action is asynchronous, or it is not know if it is synchronous or asynchronous, upon return of this method, obtain the value of the promise property and wait for its resolution.

Source: javascript/web/pentaho/action/Execution.js, line 540

Inherited From: pentaho.action.Execution#execute

Returns:
Name Description
pentaho.type.action.Execution

The value of this.

executeWill() : pentaho.type.action.Execution

Executes up to the 'will' phase of the action.

Source: javascript/web/pentaho/action/Execution.js, line 562

Inherited From: pentaho.action.Execution#executeWill

Returns:
Name Description
pentaho.type.action.Execution

The value of this.

extend(source, keyArgs) : object

Extend an object with the properties of another.

Methods that are overridden are accessible through this.base.

This object is extended, but its class doesn't change.

Source: javascript/web/pentaho/lang/Base.js, line 1040

Inherited From: pentaho.lang.Base#extend

Parameters:
Name Default Value Summary
source : object

The instance specification.

keyArgs : object
Optional

The keyword arguments.

Parameters:
Name Default Value Summary
exclude : object
Optional

A map of property names to exclude from source.

Returns:
Name Description
object

This object.

getAmbientReferences(container) : pentaho.type.ReferenceList

Gets the ambient references of a given container, if any.

Source: javascript/web/pentaho/type/action/Transaction.js, line 292

Parameters:
Name Default Value Summary
container : pentaho.type.mixins.Container

The container.

Returns:
Name Description
pentaho.type.ReferenceList

The reference list, or null.

getChangeset(uid) : pentaho.type.action.Changeset

Gets the changeset of an instance, given its unique identifier.

If no changeset has been added for the specified instance, null is returned.

Source: javascript/web/pentaho/type/action/Transaction.js, line 247

Parameters:
Name Default Value Summary
uid : string

The unique identifier of the instance.

Returns:
Name Description
pentaho.type.action.Changeset

The changeset, or null.

reject(reason) : pentaho.type.action.Execution

Called to settle the action execution as rejected.

The execution is considered failed if reason is an instance of Error (which is not an instance of UserError) or if it is an instance of RuntimeError.

Otherwise, the execution is considered canceled if reason is a string or an instance of UserError (which is not an instance of RuntimeError).

When unstarted, the execution's 'finally' phase is run. Otherwise, it is run later, when the execution reaches that phase.

Source: javascript/web/pentaho/action/Execution.js, line 704

Inherited From: pentaho.action.Execution#reject

Parameters:
Name Default Value Summary
reason : string | Error
Optional

The reason for the rejection.

Returns:
Name Description
pentaho.type.action.Execution

The value of this.

Throws:
Name Description
pentaho.lang.OperationInvalidError

When the action execution is not in one of the states unstarted, init, will or do.

See also: pentaho.type.action.Execution#isRejected , pentaho.type.action.Execution#isCanceled , pentaho.type.action.Execution#isFailed , pentaho.type.action.Execution#error

Example

define([
 "pentaho/lang/UserError",
 "pentaho/lang/RuntimeError"
], function(UserError, RuntimeError) {

 // ...

 target.on("fly", {
 will: function(event) {

 // Canceling the action execution
 // - Method 1
 event.reject("Cannot do this action now.");

 // - Method 2
 event.reject(new UserError("Cannot do this action now."));

 // Failing the action execution
 // - Method 1 (message is not adequate to be shown to the user):
 event.reject(new Error("Null Pointer Exception."));

 // - Method 2 (message is adequate to be shown to the user):
 event.reject(new RuntimeError("The server is currently unreachable."));
 }
 });

 // ...
});