1 throw new Error("Description for built in functions. Must not be included!"); 2 /** 3 * @fileOverview 4 * Documentation of a DIM service Subscription 5 */ 6 7 /** 8 * @class 9 * 10 * Subscription to a DIM service. 11 * 12 * This class represents the subscription to a DIM service. Received 13 * events are first copied to an even queue internally, to avoid 14 * any processing blocking the DIM thread (which could block the 15 * whole network as a result). Then the events are processed. 16 * If a callback is installed, the processing will take place in 17 * another JavaScript thread. Physically it will run synchronously 18 * with the other JavaScript threads. However, the processing blocks 19 * event processing. Consequetly, processing should on average be 20 * faster than the frequency with which events arrive to ensure they 21 * will not fill up the memory and possible reactions to there 22 * contents will happen within a reasonable time and not delayed 23 * too much. 24 * 25 * Each subscription must exist only once, therefore the function-call 26 * can be used to check for an open subscription. 27 * 28 * @param {String} service 29 * Name of the DIM service to which a subscription should be made. 30 * Usully of the form SERVER/SUBSCRIPTION. 31 * 32 * @param {Function} [callback] 33 * An optional function which is set as 'onchange' property. 34 * This can avoid to loose th first event after the subscription 35 * before the callback is set by the 'onchange' property (which 36 * is very unlikely). 37 * 38 * @throws 39 * <li>If number or type of arguments is wrong 40 * <li>If an open subscription to the same service already exists. 41 * 42 * @example 43 * var handle1 = Subscription("MAGIC_WEATHER/DATA"); 44 * if (!handle1) 45 * handle1 = new Subscription("MAGIC_WEATHER/DATA"); 46 * var handle2 = new Subscription("TNG_WEATHER/DATA", function(evt) { console.out(JSON.stringify(evt)); }); 47 * ... 48 * handle2.close(); 49 * handle1.close(); 50 */ 51 function Subscription(service, callback) 52 { 53 /** 54 * 55 * The name of the service subscribed to. 56 * 57 * @constant 58 * @type String 59 * 60 */ 61 this.name = service; 62 63 /** 64 * 65 * Boolean value which is set to false if the Subscription was closed. 66 * 67 * @type Boolean 68 * 69 */ 70 this.isOpen = false; 71 72 /** 73 * 74 * Callback in case of event reception. 75 * 76 * To install a callback in case a new event of this Subscription 77 * was received, set this property to a function. The argument 78 * provided to the function is identical with the object returned 79 * by Subscription.get(). For the code executed, the same rules apply 80 * than for a thread created with Thread. 81 * 82 * @type Function 83 * 84 * @example 85 * handle.onchange = function(event) { console.out(JSON.stringify(event); }; 86 * 87 */ 88 this.onchange = callback; 89 90 /** 91 * 92 * Returns the last received event of this subscription. 93 * 94 * @param {Integer} [timeout=0] 95 * A timeout in millisecond to wait for an event to arrive. 96 * This timeout only applied if no event has been received yet 97 * after a new Subscription has been created. If an event 98 * is already available, the event is returned. If the timeout 99 * is 'null', waiting will never timeout until an event was received. 100 * If the timeout is less than zero, no exception will be thrown, 101 * but 'undefined' returned in case of timeout. The corresponding 102 * timeout is then Math.abs(timeout). 103 * 104 * @param {Boolean} [requireNamed=true] 105 * Usually an event is only considered complete, if also the 106 * corresponding decription is available distributed through 107 * the service SERVER/SERVICE_DESC. If an event has no 108 * description or access to the data by name is not important, 109 * requireNamed can be set to false. 110 * 111 * @throws 112 * <li> If number or type of arguments is wrong 113 * <li> After a timeout, if the timeout value was greater or equal zero 114 * <li> If conversion of the received data to an event object has failed 115 * 116 * @returns {Event} 117 * A valid event is returned, undefined in the case waiting for an 118 * event has timed out and exceptions are supressed by a negative 119 * timeout. 120 * 121 * @example 122 * var a = new Subscription("...service does not exist..."); 123 * a.get( 3000, true); // throws an exception 124 * a.get( 3000, false); // throws and exception 125 * a.get(-3000, true); // returns undefined 126 * a.get(-3000, false); // returns undefined 127 * 128 * var a = new Subscription("...service with valid description but no valid data yet..."); 129 * a.get( 3000, true); // throws an exception 130 * a.get( 3000, false); // returns Event.data==null, Event.obj valid but empty 131 * a.get(-3000, true); // return undefined 132 * a.get(-3000, false); // returns Event.data==null, Event.obj valid but emoty 133 * 134 * // Assuming that now valid description is available but data 135 * var a = new Subscription("...service without valid description but valid data..."); 136 * a.get( 3000, true); // throws an exception 137 * a.get( 3000, false); // returns Event.data valid, Event.obj==undefined 138 * a.get(-3000, true); // returns undefined 139 * a.get(-3000, false); // returns Event.data valid, Event.obj==undefined 140 * 141 */ 142 this.get = function() { /* [native code] */ } 143 144 /** 145 * 146 * Unsubscribe from an existing subscription. Note that all open 147 * subscription produce network traffic and should be omitted if 148 * not needed. 149 * 150 * @returns {Boolean} 151 * true if the subscription was still open, false if it was 152 * already closed. 153 * 154 */ 155 this.close = function() { /* [native code] */ } 156 } 157