Caplin Trader 5.1.0

Class: module:br-util/Observable

module:br-util/Observable()

An Observable is a generic implementation of the Observer design pattern that allows an object that wants to notify other objects (the observers) of events that it raises to do so by using the Observable to handle the boiler plate code, such as the registration and management of the list of observers.

Example:

 function RecordDataProvider() {
  this.m_oObservable = new Observable();
 }

 RecordDataProvider.prototype.addListener = function(oListener) {
  this.m_oObservable.addObserver(oListener);
 };

RecordDataProvider.prototype.removeListener = function(oListener) {
 this.m_oObservable.removeObserver(oListener);
};

RecordDataProvider.prototype.processRecordUpdate = function(sRecordName, mRecordDataMap) {
 this.m_oObservable.notifyObservers("recordUpdated", [ sRecordName, mRecordDataMap ]);
};

Constructor

new module:br-util/Observable()

Constructs a new Observable.

Methods

(static) FailedNotification(observer, methodName, exception)

Constructs a new Observable.FailedNotification with the specified observer, method name and exception.

Parameters:
Name Type Description
observer Object

The observer that threw the exception whilst processing a notification.
methodName String

The name of the method that was invoked.
exception Object

The exception that was thrown.

(static) FailedNotification#getException() → {String}

Gets the exception that was thrown.

Returns:

The exception.

Type
String

(static) FailedNotification#getMethodName() → {String}

Gets the name of the method that was invoked.

Returns:

The method name.

Type
String

(static) FailedNotification#getObserver() → {Object}

Gets the observer that threw the exception.

Returns:

The observer.

Type
Object

addObserver(observer)

Adds the specified observer to the list of those to be called when module:br-util/Observable#notifyObservers is invoked. This method will not prevent a particular observer from being added multiple times. The module:br-util/Observable#addUniqueObserver method should be used for this behaviour. If an observer is added multiple times it will receive every notification once for each time it has been registered.

Parameters:
Name Type Description
observer Object

The object to be added as an observer.
Throws:

if the specified observer is not an Object, or if it is a native JavaScript String, Number, Boolean or Function.

Type
Error

addUniqueObserver(observer) → {Boolean}

Adds the specified observer to the list of those to be called when module:br-util/Observable#notifyObservers is invoked. This method prevents a observer that has already been added to an Observable from being added again. The module:br-util/Observable#addObserver method should be used if duplicates are allowed.

Parameters:
Name Type Description
observer Object

The object to be added as an observer.
Throws:

if the specified observer is not an Object, or if it is a native JavaScript String, Number, Boolean or Function.

Type
Error
Returns:

true if the observer was successfully added or false if it failed because it had already been added before.

Type
Boolean

getAllObservers() → {Array}

Gets a list of all the observers that have been registered with this Observable.

Returns:

A list of the observers that have been registered.

Type
Array

getCount()

Gets the number of listeners within the observer.

Returns:

The number of listeners within the observer.

notify(methodName)

Invokes the specified method with specified parameters on each of the observers that have been added to this Observable. Please note that this method does not attempt to catch any exceptions that may be thrown by the caller. It is recommended that before adding an observer to the Observable, it should be tested to ensure it conforms to the expected interface, and if not it should be rejected.

Parameters:
Name Type Description
methodName String

The method to be invoked on each of the registered observers.
\{...\}

(Optional) Additional parameters are passed to the observer.

notifyObservers(methodName, (Optional))

Invokes the specified method with specified array of parameters on each of the observers that have been added to this Observable. Please note that this method does not attempt to catch any exceptions that may be thrown by the caller. If this is an issue then the module:br-util/Observable#notifyObserversWithTryCatch method should be used instead. It is recommended that before adding an observer to the Observable, it should be tested to ensure it conforms to the expected interface, and if not it should be rejected.

Parameters:
Name Type Description
methodName String

The method to be invoked on each of the registered observers.
(Optional) Array

parameters An array of the parameters to be passed into the specified method. The first element of the array will be the first parameter in the callback method, the second element the second parameter, and so on.

notifyObserversWithTryCatch(methodName, parameters, throwExceptions) → {Array}

Invokes the specified method with a specified array of parameters on each of the observers that have been added to this Observable. This method wraps each call to the observer in a try..catch block so that if any observer throws an exception it will get caught and the execution will continue to the remaining observers. When exceptions occur, they are wrapped in module:br-util/Observable/FailedNotification and an array of these are returned to the caller.

Parameters:
Name Type Description
methodName String

The method to be invoked on each of the registered observers.
parameters Array

An array of the parameters to be passed into the specified method. The first element of the array will be the first parameter in the callback method, the second element the second parameter, and so on.
throwExceptions boolean

(optional) You can use this parameter if you wish the exception array to be thrown rather than returned. If no exceptions occur then nothing will be thrown and the method will return normally.
See:
  • Observable#notifyObservers to notify without guarding against exceptions.
Returns:

The list of Observable.FailedNotifications that occured or an empty array if no exceptions occurred.

Type
Array

removeAllObservers()

Removes all observers from this Observable. They will no longer be informed of any events that are raised on it.

removeObserver(observer) → {Boolean}

Removes the specified observer from the list of registered observers. It will no longer be notified of any events that are raised on this Observable.

Parameters:
Name Type Description
observer Object

The observer to be removed.
Returns:

true if the observer has been removed, otherwise false, which indicates that the observer was not registered.

Type
Boolean