Home | Class Index

SDK Version: 3.11.4-302512

Documentation generated on 24 July 2015

Class
caplin.core

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 caplin.core.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 Summary

Attributes Name and Description
caplin.core.Observable()

Constructs a new Observable.

Method Summary

Attributes Name and Description
void addObserver(Object oObserver)

Adds the specified observer to the list of those to be called when caplin.core.Observable#notifyObservers is invoked.
boolean addUniqueObserver(Object oObserver)

Adds the specified observer to the list of those to be called when caplin.core.Observable#notifyObservers is invoked.
Number getCount()

Gets the number of listeners within the observer.
void notify(String sMethodName, ... (Optional))

Invokes the specified method with specified parameters on each of the observers that have been added to this Observable.
void notifyObservers(String sMethodName, Array (Optional))

Invokes the specified method with specified array of parameters on each of the observers that have been added to this Observable.
Array notifyObserversWithTryCatch(String sMethodName, Array pParameters, boolean bThrowExceptions)

Invokes the specified method with a specified array of parameters on each of the observers that have been added to this Observable.
void removeAllObservers()

Removes all observers from this Observable.
boolean removeObserver(Object oObserver)

Removes the specified observer from the list of registered observers.

Constructor Detail

► caplin.core.Observable()

Constructs a new Observable.

Method Detail

► void addObserver(Object oObserver)

Adds the specified observer to the list of those to be called when caplin.core.Observable#notifyObservers is invoked. This method will not prevent a particular observer from being added multiple times. The caplin.core.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
Object oObserver The object to be added as an observer.
Throws
caplin.core.Error
if the specified observer is not an Object, or if it is a native JavaScript String, Number, Boolean or Function.

► boolean addUniqueObserver(Object oObserver)

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

Parameters
Object oObserver The object to be added as an observer.
Throws
caplin.core.Error
if the specified observer is not an Object, or if it is a native JavaScript String, Number, Boolean or Function.
Returns
true if the observer was successfully added or false if it failed because it had already been added before.

► Number getCount()

Gets the number of listeners within the observer.

Returns
The number of listeners within the observer.

► void notify(String sMethodName, ... (Optional))

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
String sMethodName The method to be invoked on each of the registered observers.
... (Optional) Additional parameters are passed to the observer

► void notifyObservers(String sMethodName, Array (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 caplin.core.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
String sMethodName The method to be invoked on each of the registered observers.
Array (Optional) pParameters 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.

► Array notifyObserversWithTryCatch(String sMethodName, Array pParameters, boolean bThrowExceptions)

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 caplin.core.Observable.FailedNotification and an array of these are returned to the caller.

Parameters
String sMethodName The method to be invoked on each of the registered observers.
Array pParameters 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.
boolean bThrowExceptions (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.
Returns
{Array} The list of caplin.core.Observable.FailedNotifications that occured or an empty array if no exceptions occurred.
See
caplin.core.Observable#notifyObservers to notify without guarding against exceptions

► void removeAllObservers()

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

► boolean removeObserver(Object oObserver)

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
Object oObserver The observer to be removed.
Returns
true if the observer has been removed, otherwise false, which indicates that the observer was not registered.