Skip to main content
Version Pentaho
Hitachi Vantara Lumada and Pentaho Documentation

Execution

  1. Last updated
  2. Save as PDF

pentaho.type.action. Execution

The action.Execution class represents a certain model of action execution.

This class manages the execution of an action and enforces the multiple phases by which all actions, generically, go through, which are: "init", "will", "do", and "finally".

Synchronous or Asynchronous

The associated action can be synchronous or asynchronous, as determined by the type property, pentaho.type.action.BaseType#isSync. The execution of a synchronous action is completed synchronously. while that of an asynchronous action only completes asynchronously, due to its asynchronous "do" phase.

The execute method handles the execution of both types of actions. When the associated action is asynchronous, or it is not know if it is synchronous or asynchronous, after calling execute, obtain the value of the promise property and wait for its resolution.

Execution model

The following is a detailed description of the action execution model:

  1. When an action execution is constructed, it is in the unstarted state.

    The action's label and description properties, and any other property which defines what it ultimately does, can still be freely modified.

    In this state, the execution cannot be settled by marking it done or rejected.

  2. When the execute method is called, the execution enters the init phase:

    The action's label and description properties, and any other property which defines what it ultimately does, can be freely modified at this stage.

    The execution can be settled by marking it rejected in which case it transits to the finally phase.

    Otherwise, if the associated action is not valid, the execution is automatically rejected with the first reported validation error.

    Otherwise, the execution automatically transits to the will phase.

  3. In the will phase, what the associated action will do is already determined and cannot change anymore:

    • the state is set to will;
    • the associated action is frozen, using Object.freeze, and should not be modified anymore (e.g. by modifying nested objects); trying to modify direct properties of the action will throw a TypeError;
    • the _onPhaseWill method is called.

    From this point on, an execution can be canceled based on what exactly the associated action will do.

    The execution can be settled by marking it rejected, in which case it transits to the finally phase.

    Otherwise, the execution automatically transits to the do phase.

  4. In the do phase, the execution, proper, is carried out:

    • the state is set to do;
    • the _onPhaseDo method is called.
    • if after calling _onPhaseDo, the execution is not yet done or rejected, the _doDefault method is called, allowing the action execution class to clearly handle a default behaviour.

    The execution can be settled by marking it rejected or, alternatively, done.

    In either case, the execution transits to the finally phase.

  5. In the beginning of the finally phase, the execution is considered settled, with or without success.

    If this phase was entered due to a rejection, the execution is in one of the states canceled or failed, depending on the type of rejection reason, isRejected is true, and an error may be available.

    Otherwise, the execution was successful and it is in the did state. Property isDone now returns true and a result may be available.

    The _onPhaseFinally method is called.

    The finished state bit is set to on. Property isFinished now returns true.

AMD Module 

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

Extends

Constructor

Name Description
new Execution(action, target)
Abstract

Creates an action execution instance for a given action and target.

Members

Name Description
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.
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.
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.
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 : any

Gets the result of a successful action execution, if any.
state : pentaho.type.action.States

Gets the current action execution state.
target : pentaho.type.action.ITarget

Gets the target of the action execution.

Methods

Name Description
_doDefault() : Promise
Protected

Performs the default "execution" for the associated 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.
done(result) : pentaho.type.action.Execution

Called from an action observer to settle the action execution as being done, optionally giving a result value.
execute() : pentaho.type.action.Execution

Executes the action.
extend(source, keyArgs) : Object

Extend an object with the properties of another.
reject(reason) : pentaho.type.action.Execution

Called to settle the action execution as rejected.

Constructor Details

new Execution(action, target)
Abstract

Creates an action execution instance for a given action and target.

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

Parameters:
Name Default Value Summary
action : pentaho.type.action.Base

The action to execute. A clone of it is used.
target : pentaho.type.action.ITarget

The target on which to execute.

Members Details

action: pentaho.type.action.Base

Gets the action of the action execution.

This property returns a clone of the action argument passed to the constructor.

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

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

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/type/action/Execution.js, line 328

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/type/action/Execution.js, line 396

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

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/type/action/Execution.js, line 445

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/type/action/Execution.js, line 429

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/type/action/Execution.js, line 411

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/type/action/Execution.js, line 467

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

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/type/action/Execution.js, line 381

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/type/action/Execution.js, line 361

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

isUnstarted: boolean

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

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

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/type/action/Execution.js, line 490

result: any

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/type/action/Execution.js, line 315

state: pentaho.type.action.States

Gets the current action execution state.

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

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.action.ITarget

Gets the target of the action execution.

This property returns the value of the target argument passed to the constructor.

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

Methods Details

_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/type/action/Execution.js, line 574

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

Called during the action's do phase.

The default implementation does nothing.

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

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/type/action/Execution.js, line 983

_onPhaseInit()
Protected

Called during the action execution's initialize phase.

The default implementation does nothing.

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

_onPhaseWill()
Protected

Called during the action execution's will phase.

The default implementation does nothing.

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

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/type/action/Execution.js, line 590

Parameters:
Name Default Value Summary
result : any
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.
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/type/action/Execution.js, line 548

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 unstarted state.
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 1037

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.
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).

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

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 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."));
 }
 });

 // ...
});
  1. Back to top

Recommended articles

  1. Classifications
    This page has no classifications.
  2. Tags
    This page has no tags.