Debian Codegraph @

closure-library/closure/goog/messaging/respondingchannel.js

raw
1 // Copyright 2012 The Closure Library Authors. All Rights Reserved.
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS-IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14
15 /**
16 * @fileoverview Definition of goog.messaging.RespondingChannel, which wraps a
17 * MessageChannel and allows the user to get the response from the services.
18 *
19 */
20
21
22 goog.provide('goog.messaging.RespondingChannel');
23
24 goog.require('goog.Disposable');
25 goog.require('goog.log');
26 goog.require('goog.messaging.MultiChannel');
27
28
29
30 /**
31 * Creates a new RespondingChannel wrapping a single MessageChannel.
32 * @param {goog.messaging.MessageChannel} messageChannel The messageChannel to
33 * to wrap and allow for responses. This channel must not have any existing
34 * services registered. All service registration must be done through the
35 * {@link RespondingChannel#registerService} api instead. The other end of
36 * channel must also be a RespondingChannel.
37 * @constructor
38 * @extends {goog.Disposable}
39 */
40 goog.messaging.RespondingChannel = function(messageChannel) {
41 goog.messaging.RespondingChannel.base(this, 'constructor');
42
43 /**
44 * The message channel wrapped in a MultiChannel so we can send private and
45 * public messages on it.
46 * @type {goog.messaging.MultiChannel}
47 * @private
48 */
49 this.messageChannel_ = new goog.messaging.MultiChannel(messageChannel);
50
51 /**
52 * Map of invocation signatures to function callbacks. These are used to keep
53 * track of the asyncronous service invocations so the result of a service
54 * call can be passed back to a callback in the calling frame.
55 * @type {Object<number, function(Object)>}
56 * @private
57 */
58 this.sigCallbackMap_ = {};
59
60 /**
61 * The virtual channel to send private messages on.
62 * @type {goog.messaging.MultiChannel.VirtualChannel}
63 * @private
64 */
65 this.privateChannel_ = this.messageChannel_.createVirtualChannel(
66 goog.messaging.RespondingChannel.PRIVATE_CHANNEL_);
67
68 /**
69 * The virtual channel to send public messages on.
70 * @type {goog.messaging.MultiChannel.VirtualChannel}
71 * @private
72 */
73 this.publicChannel_ = this.messageChannel_.createVirtualChannel(
74 goog.messaging.RespondingChannel.PUBLIC_CHANNEL_);
75
76 this.privateChannel_.registerService(
77 goog.messaging.RespondingChannel.CALLBACK_SERVICE_,
78 goog.bind(this.callbackServiceHandler_, this), true);
79 };
80 goog.inherits(goog.messaging.RespondingChannel, goog.Disposable);
81
82
83 /**
84 * The name of the method invocation callback service (used internally).
85 * @type {string}
86 * @const
87 * @private
88 */
89 goog.messaging.RespondingChannel.CALLBACK_SERVICE_ = 'mics';
90
91
92 /**
93 * The name of the channel to send private control messages on.
94 * @type {string}
95 * @const
96 * @private
97 */
98 goog.messaging.RespondingChannel.PRIVATE_CHANNEL_ = 'private';
99
100
101 /**
102 * The name of the channel to send public messages on.
103 * @type {string}
104 * @const
105 * @private
106 */
107 goog.messaging.RespondingChannel.PUBLIC_CHANNEL_ = 'public';
108
109
110 /**
111 * The next signature index to save the callback against.
112 * @type {number}
113 * @private
114 */
115 goog.messaging.RespondingChannel.prototype.nextSignatureIndex_ = 0;
116
117
118 /**
119 * Logger object for goog.messaging.RespondingChannel.
120 * @type {goog.log.Logger}
121 * @private
122 */
123 goog.messaging.RespondingChannel.prototype.logger_ =
124 goog.log.getLogger('goog.messaging.RespondingChannel');
125
126
127 /**
128 * Gets a random number to use for method invocation results.
129 * @return {number} A unique random signature.
130 * @private
131 */
132 goog.messaging.RespondingChannel.prototype.getNextSignature_ = function() {
133 return this.nextSignatureIndex_++;
134 };
135
136
137 /** @override */
138 goog.messaging.RespondingChannel.prototype.disposeInternal = function() {
139 goog.dispose(this.messageChannel_);
140 delete this.messageChannel_;
141 // Note: this.publicChannel_ and this.privateChannel_ get disposed by
142 // this.messageChannel_
143 delete this.publicChannel_;
144 delete this.privateChannel_;
145 };
146
147
148 /**
149 * Sends a message over the channel.
150 * @param {string} serviceName The name of the service this message should be
151 * delivered to.
152 * @param {string|!Object} payload The value of the message. If this is an
153 * Object, it is serialized to a string before sending if necessary.
154 * @param {function(?Object)} callback The callback invoked with
155 * the result of the service call.
156 */
157 goog.messaging.RespondingChannel.prototype.send = function(
158 serviceName, payload, callback) {
159
160 var signature = this.getNextSignature_();
161 this.sigCallbackMap_[signature] = callback;
162
163 var message = {};
164 message['signature'] = signature;
165 message['data'] = payload;
166
167 this.publicChannel_.send(serviceName, message);
168 };
169
170
171 /**
172 * Receives the results of the peer's service results.
173 * @param {!Object|string} message The results from the remote service
174 * invocation.
175 * @private
176 */
177 goog.messaging.RespondingChannel.prototype.callbackServiceHandler_ = function(
178 message) {
179
180 var signature = message['signature'];
181 var result = message['data'];
182
183 if (signature in this.sigCallbackMap_) {
184 var callback =
185 /** @type {function(Object)} */ (this.sigCallbackMap_[signature]);
186 callback(result);
187 delete this.sigCallbackMap_[signature];
188 } else {
189 goog.log.warning(this.logger_, 'Received signature is invalid');
190 }
191 };
192
193
194 /**
195 * Registers a service to be called when a message is received.
196 * @param {string} serviceName The name of the service.
197 * @param {function(!Object)} callback The callback to process the
198 * incoming messages. Passed the payload.
199 */
200 goog.messaging.RespondingChannel.prototype.registerService = function(
201 serviceName, callback) {
202 this.publicChannel_.registerService(
203 serviceName, goog.bind(this.callbackProxy_, this, callback), true);
204 };
205
206
207 /**
208 * A intermediary proxy for service callbacks to be invoked and return their
209 * their results to the remote caller's callback.
210 * @param {function((string|!Object))} callback The callback to process the
211 * incoming messages. Passed the payload.
212 * @param {!Object|string} message The message containing the signature and
213 * the data to invoke the service callback with.
214 * @private
215 */
216 goog.messaging.RespondingChannel.prototype.callbackProxy_ = function(
217 callback, message) {
218
219 var resultMessage = {};
220 resultMessage['data'] = callback(message['data']);
221 resultMessage['signature'] = message['signature'];
222 // The callback invoked above may have disposed the channel so check if it
223 // exists.
224 if (this.privateChannel_) {
225 this.privateChannel_.send(
226 goog.messaging.RespondingChannel.CALLBACK_SERVICE_, resultMessage);
227 }
228 };