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

EventSource

pentaho.lang. EventSource

The EventSource class is an implementation IEventSource that can be used as mixin class for classes that emit events.

The class publicly exposes the IEventSource interface, allowing the registration and unregistration of event listeners/observers. The ability to emit events is, however, only exposed via the protected interface, through the methods: _emit, _emitSafe, _emitGeneric and _emitGenericAllAsync. The methods _emit and _emitSafe are to be used with events of the Event type. The methods _emitGeneric and _emitGenericAllAsync can be used with any event type and expose more control options.

To ascertain whether any listeners are registered for a certain event type and, optionally, phase, use _hasListeners.

AMD Module

require(["pentaho/lang/EventSource"], function(EventSource) { /* code goes here */ });

Implements

Constructor

Name Description
new EventSource()

This class was not designed to be constructed directly. It was designed to be used as a mixin.

Methods

Name Description
_emit(event) : pentaho.lang.Event
Protected

Emits an unstructured event and returns it, unless it was canceled.

_emitGeneric(source, eventArgs, type, phase, keyArgs) : boolean
Protected

Emits an event given an arbitrary payload object, its type and phase. Returns the event payload object, unless the event is canceled.

_emitGenericAllAsync(source, eventArgs, type, phase, keyArgs) : Promise.<object>
Protected

Emits an event asynchronously, given an arbitrary payload object, its type and phase, and succeeding if every listener succeeds.

_emitSafe(event) : pentaho.lang.Event
Protected

Variation of the _emit method in which errors thrown by event listeners are caught and logged.

_hasListeners(type, phase) : boolean
Protected

Determines if there are any registrations for a given event type and, optionally, phase.

off(typeOrHandle, observer)

Removes one registration given its handle, or all registrations of a given event type (or types) and observer (or listener function).

on(type, observer, keyArgs) : pentaho.lang.IEventRegistrationHandle

Registers an observer (or listener function) for an event(s) of a given type(s).

Constructor Details

new EventSource()

This class was not designed to be constructed directly. It was designed to be used as a mixin.

Source: javascript/web/pentaho/lang/EventSource.js, line 78

Methods Details

_emit(event) : pentaho.lang.Event
Protected

Emits an unstructured event and returns it, unless it was canceled.

When this method is called, the listeners of existing registrations are notified synchronously, by priority order and then registration order, until either the event is canceled or all of the listeners have been notified.

It is safe to register or unregister to/from an event type while it is being emitted. However, changes are only taken into account in subsequent emissions.

If a listener function throws an error, the event processing is interrupted. No more registrations are processed and the error is passed to the caller.

Source: javascript/web/pentaho/lang/EventSource.js, line 269

Parameters:
Name Default Value Summary
event : pentaho.lang.Event

The event object.

Returns:
Name Description
pentaho.lang.Event | null

The given event object or null, when canceled.

See also: pentaho.lang.EventSource#_emitSafe , pentaho.lang.EventSource#_emitGeneric

_emitGeneric(source, eventArgs, type, phase, keyArgs) : boolean
Protected

Emits an event given an arbitrary payload object, its type and phase. Returns the event payload object, unless the event is canceled.

Source: javascript/web/pentaho/lang/EventSource.js, line 325

Parameters:
Name Default Value Summary
source : object

The this value of listener functions.

eventArgs : Array

The arguments of listener functions.

type : nonEmptyString

The type of the event.

phase : nonEmptyString
Optional

The phase of the event. For unstructured events don't specify this argument (or specify a Nully value).

keyArgs : object
Optional

The keyword arguments' object.

Parameters:
Name Default Value Summary
isCanceled : function
Optional

A predicate that indicates if the given event arguments are in a canceled state. Its this value is the value of source.

errorHandler : function
Optional

When specified with a null value, no error handling is performed and errors thrown by listeners are thrown back to this method's caller. When unspecified or specified as undefined, defaults to a function that simply logs the listener errors, and lets execution continue to the following listeners. The function arguments are: the error, the eventArgs, the event type and the event phase. Its this value is the value of source.

interceptor : function
Optional
null

A function which is called for each event listener function, with the arguments listener, source, eventArgs and the index of the listener.

Returns:
Name Description
boolean

false when the event is canceled; true, otherwise.

_emitGenericAllAsync(source, eventArgs, type, phase, keyArgs) : Promise.<object>
Protected

Emits an event asynchronously, given an arbitrary payload object, its type and phase, and succeeding if every listener succeeds.

Listeners are called in parallel.

Returns a promise that is fulfilled or rejected with the event payload object. If any listener throws or rejects, the returned promise is rejected as well.

Source: javascript/web/pentaho/lang/EventSource.js, line 454

Parameters:
Name Default Value Summary
source : object

The this value of listener functions.

eventArgs : Array

The arguments of listener functions.

type : nonEmptyString

The type of the event.

phase : nonEmptyString
Optional

The phase of the event. For unstructured events don't specify this argument (or specify a Nully value).

keyArgs : object
Optional

The keyword arguments' object.

Parameters:
Name Default Value Summary
isCanceled : function
Optional

A predicate that indicates if the given event arguments are in a canceled state. Its this value is the value of source.

getCancellationReason : function
Optional

A function that given the event arguments returns its a cancellation reason, usually an Error. Its this value is the value of source.

errorHandler : function
Optional

When specified with a null value, no error handling is performed. Errors thrown by, or promises rejected by, any listeners cause the whole event to be rejected.

When unspecified or specified as undefined, defaults to a function that simply logs any listener errors, yet always succeeding.

The function arguments are: the error, the event, the event type and the event phase.

Returns:
Name Description
Promise.<object>

A promise. When fulfilled, it is with the value undefined. When rejected due to a thrown error, the rejection reason is that error. When explicitly rejected by the error handler, the given rejection reason is preserved. When rejected due to a cancellation, the rejection reason is the cancellation reason, if any.

_emitSafe(event) : pentaho.lang.Event
Protected

Variation of the _emit method in which errors thrown by event listeners are caught and logged.

If an event listener throws an error, the following event listeners are still processed.

Source: javascript/web/pentaho/lang/EventSource.js, line 291

Parameters:
Name Default Value Summary
event : pentaho.lang.Event

The event object.

Returns:
Name Description
pentaho.lang.Event | null

The given event object or null, when canceled.

See also: pentaho.lang.EventSource#_emit , pentaho.lang.EventSource#_emitGeneric

_hasListeners(type, phase) : boolean
Protected

Determines if there are any registrations for a given event type and, optionally, phase.

This method can be used to avoid creating expensive event objects for an event type and, optionally, phase, that don't have registrations.

Source: javascript/web/pentaho/lang/EventSource.js, line 218

Parameters:
Name Default Value Summary
type : nonEmptyString

The type of the event.

phase : nonEmptyString
Optional

The phase of a structured event. For unstructured events don't specify this argument. For structured events, if this argument is not specified, the result will be true if there are any listeners, for any of the phases.

Returns:
Name Description
boolean

true if the event has any listeners for the given event type and phase; false, otherwise.

Examples

if(this._hasListeners("click")) {

 var event = new Event("click", this, true);

 if(this._emit(event)) {
 // ...
 }
}
if(this._hasListeners("select")) {

 var event = new Event("select");

 if(this._emitGeneric(this, [event], "select", "will")) {

 // Select ...

 this._emitGeneric(this, [event], "select", "finally");
 }
}
Implements:
off(typeOrHandle, observer)

Removes one registration given its handle, or all registrations of a given event type (or types) and observer (or listener function).

To remove an event registration, it is sufficient to call the dispose method of the registration handle returned by on, upon registration. Alternatively, as a convenience syntax, the registration handle can be passed as the single argument to this method.

It is safe to unregister from an event type while it is being emitted. However, any registrations removed during the current emission will still execute.

Specifying an event registration handle that has already been disposed of has no effect. Specifying an event type and observer (or listener function) that have no registrations has no effect.

Source: doc-js/pentaho/lang/IEventSource.jsdoc, line 131

Parameters:
Name Default Value Summary
typeOrHandle : nonEmptyString | Array.<nonEmptyString> | pentaho.lang.IEventRegistrationHandle

The type or types of events, or an event registration handle to dispose of. When a string, it can be a comma-separated list of event types.

observer : pentaho.lang.IEventObserver | pentaho.lang.EventListener | pentaho.lang.EventListenerAsync

The event observer (or listener function). Required when typeOrHandle is not an event registration handle; ignored, otherwise.

See also: pentaho.lang.IEventSource#on

Implements:
on(type, observer, keyArgs) : pentaho.lang.IEventRegistrationHandle

Registers an observer (or listener function) for an event(s) of a given type(s).

Optionally, a listening priority may be specified to adjust the order by which an observer is notified, relative to other listeners.

Note that if an observer is registered more than once to the same event type, a new registration is created each time and its listeners will be called once per registration.

It is safe to register for an event type while it is being emitted. However, new registrations are only taken into account in subsequent emissions.

When type represents multiple event types, the returned event registration handle is a composite registration for all of the event types.

This method is compatible with the dojo/on API.

Source: doc-js/pentaho/lang/IEventSource.jsdoc, line 90

Parameters:
Name Default Value Summary
type : nonEmptyString | Array.<nonEmptyString>

The type or types of events. When a string, it can be a comma-separated list of event types.

observer : pentaho.lang.IEventObserver | pentaho.lang.EventListener | pentaho.lang.EventListenerAsync

The event observer (or listener function).

keyArgs : object
Optional

Keyword arguments.

Parameters:
Name Default Value Summary
priority : number
Optional
0

The listening priority. Higher priority observers are notified of an event before any lower priority observers. The priority can be set to -Infinity or Infinity. In case two observers are assigned the same priority, the registration order determines which is notified first.

Returns:
Name Description
pentaho.lang.IEventRegistrationHandle

An event registration handle that can be used for later removal.

See also: pentaho.lang.IEventSource#off