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

Base

  1. Last updated
  2. Save as PDF

pentaho.type.action.Base

The action.Base class represents a certain model of actions.

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

Note that the associated type class is to be used to configure metadata information about actions. For example: label and description metadata are to be used in user interfaces to portray the action to the user.

Synchronous or Asynchronous

An action can be synchronous or asynchronous, as determined by the type property, Base.Type#isSync. The execution of a synchronous action is completed synchronously. An asynchronous action, however, has an asynchronous "do" phase, and thus only fully completes asynchronously. To support these two kinds of actions, two execution methods exist: execute and executeAsync. For an unknown kind of action, use execute if you are not concerned about the outcome of the action execution. Use executeAsync if you are concerned about the outcome of the action.

Action model

The following is a detailed description of the action model:

  1. When an action is constructed, it is in the candidate state. It merely represents a possible, or candidate, action that can be executed.

    At this point, it has no associated target or _executor.

    Its label and description, and anything else that defines exactly what the action ultimately does, can still be freely modified.

    In this state, the action cannot be marked done or be rejected.

  2. When either the execute or the executeAsync method is called, the action enters the init phase and is set to the init state.

    The action's target and _executor are set to the ones provided as arguments in the said methods.

    The _onPhaseInit method is called, which, by default, delegates to the set executor, if any, by calling its init method.

    The action's label and description, and anything else that defines exactly what the action ultimately does, can still be freely modified.

    The action can be marked rejected, in which case it is set to either the canceled or the failed state, and the finally phase is entered.

    Otherwise, the action automatically transits to the will phase.

  3. In the will phase, what the action will do, along with its label and description, is now settled and cannot be changed anymore -- an action can now be canceled based on what exactly it will do.

    The action is set to the will state.

    From now on, calling isEditable will return false and calling _assertEditable will throw an error.

    The _onPhaseWill method is called, which, by default, delegates to the set executor, if any, by calling its will method.

    The action can be marked rejected, in which case it is set to either the canceled or the failed state, and the finally phase is entered.

    Otherwise, the action automatically transits to the do phase.

  4. In the do phase, the action execution, proper, is carried out. The action is set to the do state.

    The _onPhaseDo method is called, which, by default, delegates to the set executor, if any, by calling its do method.

    The action cannot be canceled anymore, but can, however, be marked failed, by rejecting it with a runtime error, in which case it is set to the failed state, and the finally phase is entered.

    Alternatively, the action can be marked done.

    If after calling _onPhaseDo the action is not yet done or rejected, the _doDefault is called, allowing the action class to provide a default implementation.

    Finally, the action is set to the did state, and the finally phase is entered.

  5. When in the finally phase, the action is finished, with or without success, and is in one of the canceled, failed or did states.

    The _onPhaseFinally method is called, which, by default, delegates to the set executor, if any, by calling its finally method.

    If the action was done, an action result may be available, while if the action was rejected, an action error may be available.

AMD Module 

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

See also:  pentaho.type.action.spec.IBase , pentaho.type.action.spec.IBaseProto , pentaho.type.action.spec.IBaseTypeProto

Extends

Constructor

Name Description
new Base(spec)
 
Abstract

Creates an action instance given its specification.

Classes

Name Summary
Type

The base class of action types.

Members

Name Description
$isValid : boolean

Determines if this value is a valid instance of its type.
$key : string

Gets the key of the value.
$type : pentaho.type.Value.Type

Gets the type of this instance.
_executor : pentaho.type.action.IObserver
 
Protected

Gets the executor to which the actual action execution is delegated.
description : __nonEmptyString

Gets or sets the description of this action.
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 has been canceled.
isCandidate : boolean

Gets a value that indicates if the action is in a candidate state.
isDone : boolean

Gets a value that indicates if the action executed successfully.
isEditable : boolean

Gets a value that indicates if the action is editable.
isExecuting : boolean

Gets a value that indicates if the action is executing.
isFailed : boolean

Gets a value that indicates if the action has failed.
isFinished : boolean

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

Gets a value that indicates if the action has been rejected.
label : __nonEmptyString

Gets or sets the label of this action.
promise : Promise

Gets a promise for the result (or error) of this action's execution, if ever.
result : any

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

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

Gets the target where the action is executing or has executed.

Methods

Name Description
extend(name, instSpec, classSpec, keyArgs) : Class.<pentaho.type.Value>
 
Static

Creates a subtype of this one.
_assertEditable()
 
Protected

Asserts that the action is editable and throws an error if not.
_configure(config)
 
Protected

Configures this value with a given non-nully configuration.
_doDefault() : Promise

Performs the default "action" of this 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's initialize phase.
_onPhaseWill()
 
Protected

Called during the action's will phase.
_setTarget(target)
 
Protected

Called to validate and set the action's target, upon execution.
assertValid()

Ensures that the value is valid, and throws the first validation error if it is not.
clone() : pentaho.type.Value

Creates a shallow clone of this value.
configure(config) : pentaho.type.Value

Configures this value with a given configuration.
done(result) : pentaho.type.action.Base

Called from an action observer to mark the action as being done, optionally given a result value.
equals(other) : boolean

Determines if a given value, of the same type, represents the same entity.
execute(target, executor) : pentaho.type.action.Base

Executes the action on a given target and, optionally, with a given executor, and does not wait for its outcome.
executeAsync(target, executor) : Promise

Executes the action on a given target and, optionally, with a given executor, and waits for its outcome.
reject(reason) : pentaho.type.action.Base

Called from an action observer to mark the action as rejected.
toJSON() : UJsonValue

Creates a top-level JSON specification that describes this instance.
toSpec(keyArgs) : pentaho.type.spec.UInstance

Creates a specification that describes this value.
toSpecInContext(keyArgs) : any

Creates a specification that describes this instance.
validate() : Array.<pentaho.type.ValidationError>

Determines if this value is a valid instance of its type.

Constructor Details

new Base(spec)
 
Abstract

Creates an action instance given its specification.

Source: javascript/web/pentaho/type/action/base.js, line 273

Parameters:
Name Default Value Summary
spec : pentaho.type.action.spec.IBase
 
Optional

An action specification.

See also:  pentaho.type.action.spec.IBase , pentaho.type.action.spec.IBaseProto , pentaho.type.action.spec.IBaseTypeProto

Members Details

$isValid: boolean

Determines if this value is a valid instance of its type.

This attribute calls validate and returns a boolean value indicating if it returned no errors.

Source: javascript/web/pentaho/type/value.js, line 123

Inherited From: pentaho.type.Value#$isValid

$key: string

Gets the key of the value.

The key of a value must identify it among values of the same concrete type. Two values of the same concrete type and with the same key represent the same entity.

The default implementation returns the result of calling toString().

Source: javascript/web/pentaho/type/value.js, line 82

Inherited From: pentaho.type.Value#$key

See also:  pentaho.type.Value#equals , pentaho.type.Value.Type#areEqual

$type: pentaho.type.Value.Type

Gets the type of this instance.

Source: javascript/web/pentaho/type/value.js, line 246

Overrides: pentaho.type.Element#$type

_executor: pentaho.type.action.IObserver
 
Protected

Gets the executor to which the actual action execution is delegated.

This property contains the value of the executor argument passed to execute or executeAsync, and is null before execution.

Source: javascript/web/pentaho/type/action/base.js, line 746

description: __nonEmptyString

Gets or sets the description of this action.

When not set to a non-empty local value, the description of the action type, pentaho.type.Type#description is returned.

Can only be set while the action is in an editable state.

Source: javascript/web/pentaho/type/action/base.js, line 380

error: Error | pentaho.lang.UserError

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

This property can only return a non-null value if pentaho.type.action.Base#isRejected is true.

Source: javascript/web/pentaho/type/action/base.js, line 464

isCanceled: boolean

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

Source: javascript/web/pentaho/type/action/base.js, line 510

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

isCandidate: boolean

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

Source: javascript/web/pentaho/type/action/base.js, line 532

isDone: boolean

Gets a value that indicates if the action executed successfully.

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

See also:  pentaho.type.action.Base#result

isEditable: boolean

Gets a value that indicates if the action is editable.

An action is considered editable if its state is one of init or will.

Source: javascript/web/pentaho/type/action/base.js, line 478

isExecuting: boolean

Gets a value that indicates if the action is executing.

An action is executing if its state is one of init, will or do.

Source: javascript/web/pentaho/type/action/base.js, line 550

See also:  pentaho.type.action.Base#isCandidate , pentaho.type.action.Base#isFinished

isFailed: boolean

Gets a value that indicates if the action has failed.

Source: javascript/web/pentaho/type/action/base.js, line 522

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

isFinished: boolean

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

An action has finished execution if its state is one of did, canceled or failed.

Source: javascript/web/pentaho/type/action/base.js, line 581

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

isRejected: boolean

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

An action is considered rejected if its state is one of init or will.

Source: javascript/web/pentaho/type/action/base.js, line 498

See also:  pentaho.type.action.Base#isCanceled , pentaho.type.action.Base#isFailed , pentaho.type.action.Base#isDone , pentaho.type.action.Base#isFinished , pentaho.type.action.Base#error

label: __nonEmptyString

Gets or sets the label of this action.

When not set to a non-empty local value, the label of the action type, pentaho.type.Type#label is returned.

Can only be set while the action is in an editable state.

Source: javascript/web/pentaho/type/action/base.js, line 359

promise: Promise

Gets a promise for the result (or error) of this action's execution, if ever.

This promise can be requested anytime, before starting execution, during execution, or after finishing execution of this action. Also, it can be requested whether or not the action is synchronous or asynchronous.

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

Source: javascript/web/pentaho/type/action/base.js, line 601

result: any

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

This property can only return a non-undefined value if pentaho.type.action.Base#isDone is true.

Source: javascript/web/pentaho/type/action/base.js, line 451

state: pentaho.type.action.States

Gets the current action state.

Source: javascript/web/pentaho/type/action/base.js, line 399

target: pentaho.type.action.ITarget

Gets the target where the action is executing or has executed.

This property contains the value of the target argument passed to execute or executeAsync, and is null before execution.

Source: javascript/web/pentaho/type/action/base.js, line 713

Methods Details

extend(name, instSpec, classSpec, keyArgs) : Class.<pentaho.type.Value>
 
Static

Creates a subtype of this one.

For more information on class extension, in general, see pentaho.lang.Base.extend.

Source: javascript/web/pentaho/type/action/base.js, line 50

Parameters:
Name Default Value Summary
name : string
 
Optional

The name of the created class; used for debugging purposes.
instSpec : pentaho.type.action.spec.IBaseProto
 
Optional

The instance specification.
classSpec : Object
 
Optional

The static specification.
keyArgs : Object
 
Optional

The keyword arguments.
Returns:
Name Description
Class.<pentaho.type.Value>

The new value instance subclass.

See also:  pentaho.type.Instance.extend

_assertEditable()
 
Protected

Asserts that the action is editable and throws an error if not.

Call this helper method at the start of general property setters.

Source: javascript/web/pentaho/type/action/base.js, line 412

Throws:
Name Description
pentaho.lang.OperationInvalidError

When the action is not editable.
_configure(config)
 
Protected

Configures this value with a given non-nully configuration.

The default implementation does nothing.

Source: javascript/web/pentaho/type/value.js, line 178

Inherited From: pentaho.type.Value#_configure

Parameters:
Name Default Value Summary
config : any

The configuration.
_doDefault() : Promise

Performs the default "action" of this action.

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

Source: javascript/web/pentaho/type/action/base.js, line 760

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

Called during the action's do phase.

The default implementation calls the executor's do listener, if any.

Source: javascript/web/pentaho/type/action/base.js, line 1183

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 calls the executor's finally listener, if any.

Source: javascript/web/pentaho/type/action/base.js, line 1198

_onPhaseInit()
 
Protected

Called during the action's initialize phase.

The default implementation calls the executor's init listener, if any.

Source: javascript/web/pentaho/type/action/base.js, line 1150

_onPhaseWill()
 
Protected

Called during the action's will phase.

The default implementation calls the executor's will listener, if any.

Source: javascript/web/pentaho/type/action/base.js, line 1165

_setTarget(target)
 
Protected

Called to validate and set the action's target, upon execution.

Override to perform additional validations after calling the base implementation.

Source: javascript/web/pentaho/type/action/base.js, line 726

Parameters:
Name Default Value Summary
target : pentaho.type.action.ITarget

The action's target.
assertValid()

Ensures that the value is valid, and throws the first validation error if it is not.

This method calls the validate method.

Source: javascript/web/pentaho/type/value.js, line 152

Inherited From: pentaho.type.Value#assertValid

Throws:
Name Description
pentaho.type.ValidationError

When the value is not valid, the first error returned by the validate method.
clone() : pentaho.type.Value

Creates a shallow clone of this value.

Source: javascript/web/pentaho/type/value.js, line 86

Overrides: pentaho.type.Element#clone

Returns:
Name Description
pentaho.type.Value

The value clone.
Implements:
configure(config) : pentaho.type.Value

Configures this value with a given configuration.

Source: javascript/web/pentaho/type/value.js, line 165

Inherited From: pentaho.type.Value#configure

Parameters:
Name Default Value Summary
config : any

The configuration.
Returns:
Name Description
pentaho.type.Value

This instance.
done(result) : pentaho.type.action.Base

Called from an action observer to mark the action as being done, optionally given a result value.

Source: javascript/web/pentaho/type/action/base.js, line 775

Parameters:
Name Default Value Summary
result : any
 
Optional

The result of the action, if any.
Returns:
Name Description
pentaho.type.action.Base

The value of this.
Throws:
Name Description
pentaho.lang.OperationInvalidError

When the action is not in the do state.
equals(other) : boolean

Determines if a given value, of the same type, represents the same entity.

The default implementation delegates the operation to the _isEqual method.

Source: javascript/web/pentaho/type/value.js, line 107

Inherited From: pentaho.type.Value#equals

Parameters:
Name Default Value Summary
other : any

A value to test for equality.
Returns:
Name Description
boolean

true if the given value is equal to this one; or, false, otherwise.

See also:  pentaho.type.Value#$key , pentaho.type.Value.Type#areEqual

execute(target, executor) : pentaho.type.action.Base

Executes the action on a given target and, optionally, with a given executor, and does not wait for its outcome.

This method can be called on synchronous or asynchronous actions. However, in the latter case, this method is only suitable for fire-and-forget scenarios, where it is not needed to know the action outcome.

Source: javascript/web/pentaho/type/action/base.js, line 661

Parameters:
Name Default Value Summary
target : pentaho.type.action.ITarget

The action's target.
executor : pentaho.type.action.IObserver
 
Optional

An action observer to act as action controller/executor. Unlike normal event/action observers, the functions of executor observers are called with the executor as the value of the JavaScript this context.
Returns:
Name Description
pentaho.type.action.Base

The value of this.

See also:  pentaho.type.action.ITarget#executeAsync , pentaho.type.action.ITarget#act

executeAsync(target, executor) : Promise

Executes the action on a given target and, optionally, with a given executor, and waits for its outcome.

This method can be called on synchronous or asynchronous actions, and can be used when uniformity in treatment is desired and it is needed to know their outcome.

Source: javascript/web/pentaho/type/action/base.js, line 688

Parameters:
Name Default Value Summary
target : pentaho.type.action.ITarget

The action's target.
executor : pentaho.type.action.IObserver
 
Optional

An action observer to act as action controller/executor. Unlike normal event/action observers, the functions of executor observers are called with the executor as the value of the JavaScript this context.
Returns:
Name Description
Promise

A promise that is fulfilled with the action's result or rejected with the action's error.

See also:  pentaho.type.action.ITarget#execute , pentaho.type.action.ITarget#actAsync

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

Called from an action observer to mark the action as rejected.

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

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

Source: javascript/web/pentaho/type/action/base.js, line 843

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

The reason for the rejection.
Returns:
Name Description
pentaho.type.action.Base

The value of this.
Throws:
Name Description
pentaho.lang.OperationInvalidError

When canceling and the action is not in one of the states init or will.
pentaho.lang.OperationInvalidError

When failing and the action is not executing.

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

Example

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

 // ...

 target.on("fly", {
 will: function(action) {
 // Canceling the action
 // .. Method 1
 action.reject("Cannot do this action now.");

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

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

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

 // ...
});
toJSON() : UJsonValue

Creates a top-level JSON specification that describes this instance.

Attributes which do not have a JSON-compatible specification are omitted. Specifically, for inline types, attributes with a function value are not supported.

This method simply calls pentaho.type.Instance#toSpec with argument keyArgs.isJson as true and exists for seamless integration with JavaScript's JSON.stringify method.

Source: javascript/web/pentaho/type/instance.js, line 210

Inherited From: pentaho.type.Instance#toJSON

Returns:
Name Description
UJsonValue

A JSON-compatible specification.

See also:  pentaho.type.Instance#toSpec

Implements:
toSpec(keyArgs) : pentaho.type.spec.UInstance

Creates a specification that describes this value.

If an ambient specification context, currently exists, it is used to manage the serialization process. Otherwise, one is created and set as current. Then, the actual work is delegated to pentaho.type.Instance#toSpecInContext.

Source: javascript/web/pentaho/type/value.js, line 184

Inherited From: pentaho.type.Value#toSpec

Parameters:
Name Default Value Summary
keyArgs : Object
 
Optional

The keyword arguments object. Passed to every value and type serialized within this scope.

Please see the documentation of value subclasses for information on additional, supported keyword arguments.

Parameters:
Name Default Value Summary
isJson : boolean
 
Optional
 false

Generates a JSON-compatible specification. Attributes which do not have a JSON-compatible specification are omitted.
declaredType : pentaho.type.Type
 
Optional

The base type of this value's storage location. If the value does not have this exact type, its inline type property must be included in the specification. Otherwise, it can be omitted. When unspecified, the inline type property is only included if forceType is true.
forceType : boolean
 
Optional
 false

Forces inclusion of the inline type property, _, in the specification.
omitFormatted : boolean
 
Optional
 false

Omits the formatted value on Simple values' specifications.
preferPropertyArray : boolean
 
Optional
 false

Indicates that, if possible, array form is used for Complex values' specifications.

The array form of a complex value cannot be used when its type must be inlined.
includeDefaults : boolean
 
Optional
 false

When true, all of the properties of Complex values are serialized. When false, the default, only properties whose value is different from their default value are serialized.

Only applies to complex values that are serialized in object form. In array form, all of the properties of complex values are serialized independently of their value.
omitProps : Object
 
Optional

An object whose own property names with a truthy value are the names of the properties of the current complex type to omit from the serialization.

Only applies when a complex is output in object form. In array form, all properties are output whatever their value.

This argument only applies to complex values and is not passed through to the values of their properties.
Returns:
Name Description
pentaho.type.spec.UInstance

A specification of this value.
toSpecInContext(keyArgs) : any

Creates a specification that describes this instance.

Source: javascript/web/pentaho/type/instance.js, line 190

Overrides: pentaho.type.Element#toSpecInContext

Parameters:
Name Default Value Summary
keyArgs : Object
 
Optional

The keyword arguments' object. Passed to every instance and type serialized within this scope.

Please see the documentation of subclasses for information on additional, supported keyword arguments.
Returns:
Name Description
any

A specification of this instance.

See also:  pentaho.type.Instance#toSpec

validate() : Array.<pentaho.type.ValidationError>

Determines if this value is a valid instance of its type.

The default implementation delegates to pentaho.type.Value.Type#_validate.

Source: javascript/web/pentaho/type/value.js, line 137

Inherited From: pentaho.type.Value#validate

Returns:
Name Description
Array.<pentaho.type.ValidationError>

A non-empty array of errors or null.

See also:  pentaho.type.Value#$isValid

  1. Back to top

Recommended articles

  1. Version
    8.0
  2. Tags
    This page has no tags.