Class Subscription

Subscription to a DIM service. This class represents the subscription to a DIM service. Received events are first copied to an even queue internally, to avoid any processing blocking the DIM thread (which could block the whole network as a result). Then the events are processed. If a callback is installed, the processing will take place in another JavaScript thread. Physically it will run synchronously with the other JavaScript threads. However, the processing blocks event processing. Consequetly, processing should on average be faster than the frequency with which events arrive to ensure they will not fill up the memory and possible reactions to there contents will happen within a reasonable time and not delayed too much. Each subscription must exist only once, therefore the function-call can be used to check for an open subscription.
Defined in: Subscription.js.

Class Summary
Constructor Attributes	Constructor Name and Description
	Subscription(service, callback)

Field Summary
Field Attributes	Field Name and Description
	isOpen Boolean value which is set to false if the Subscription was closed.
<constant>	name The name of the service subscribed to.
	onchange Callback in case of event reception.

Method Summary
Method Attributes	Method Name and Description
	close() Unsubscribe from an existing subscription.
	get(timeout, requireNamed) Returns the last received event of this subscription.

Class Detail

Subscription(service, callback)

   var handle1 = Subscription("MAGIC_WEATHER/DATA");
   if (!handle1)
       handle1 = new Subscription("MAGIC_WEATHER/DATA");
   var handle2 = new Subscription("TNG_WEATHER/DATA", function(evt) { console.out(JSON.stringify(evt)); });
   ...
   handle2.close();
   handle1.close();

Parameters:
{String} service: Name of the DIM service to which a subscription should be made. Usully of the form SERVER/SUBSCRIPTION.
{Function} callback Optional: An optional function which is set as 'onchange' property. This can avoid to loose th first event after the subscription before the callback is set by the 'onchange' property (which is very unlikely).

Throws:
: If number or type of arguments is wrong
If an open subscription to the same service already exists.

Field Detail

{Boolean} isOpen

Boolean value which is set to false if the Subscription was closed.

<constant> {String} name

The name of the service subscribed to.

{Function} onchange

Callback in case of event reception. To install a callback in case a new event of this Subscription was received, set this property to a function. The argument provided to the function is identical with the object returned by Subscription.get(). For the code executed, the same rules apply than for a thread created with Thread.

    handle.onchange = function(event) { console.out(JSON.stringify(event); };

Method Detail

{Boolean} close()

Unsubscribe from an existing subscription. Note that all open subscription produce network traffic and should be omitted if not needed.

Returns:: {Boolean} true if the subscription was still open, false if it was already closed.

{Event} get(timeout, requireNamed)

Returns the last received event of this subscription.

    var a = new Subscription("...service does not exist...");
    a.get( 3000, true);  // throws an exception
    a.get( 3000, false); // throws and exception
    a.get(-3000, true);  // returns undefined
    a.get(-3000, false); // returns undefined

    var a = new Subscription("...service with valid description but no valid data yet...");
    a.get( 3000, true);  // throws an exception
    a.get( 3000, false); // returns Event.data==null, Event.obj valid but empty
    a.get(-3000, true);  // return undefined
    a.get(-3000, false); // returns Event.data==null, Event.obj valid but emoty

    // Assuming that now valid description is available but data
    var a = new Subscription("...service without valid description but valid data...");
    a.get( 3000, true);  // throws an exception
    a.get( 3000, false); // returns Event.data valid, Event.obj==undefined
    a.get(-3000, true);  // returns undefined
    a.get(-3000, false); // returns Event.data valid, Event.obj==undefined

Parameters:
{Integer} timeout Optional, Default: 0: A timeout in millisecond to wait for an event to arrive. This timeout only applied if no event has been received yet after a new Subscription has been created. If an event is already available, the event is returned. If the timeout is 'null', waiting will never timeout until an event was received. If the timeout is less than zero, no exception will be thrown, but 'undefined' returned in case of timeout. The corresponding timeout is then Math.abs(timeout).
{Boolean} requireNamed Optional, Default: true: Usually an event is only considered complete, if also the corresponding decription is available distributed through the service SERVER/SERVICE_DESC. If an event has no description or access to the data by name is not important, requireNamed can be set to false.

Throws:
: If number or type of arguments is wrong
After a timeout, if the timeout value was greater or equal zero
If conversion of the received data to an event object has failed

Returns:: {Event} A valid event is returned, undefined in the case waiting for an event has timed out and exceptions are supressed by a negative timeout.

Classes

Class Subscription