Debian Codegraph @

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

raw
1 // Copyright 2011 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 The leaf node of a {@link goog.messaging.PortNetwork}. Callers
17 * connect to the operator, and request connections with other contexts from it.
18 *
19 */
20
21 goog.provide('goog.messaging.PortCaller');
22
23 goog.require('goog.Disposable');
24 goog.require('goog.async.Deferred');
25 goog.require('goog.messaging.DeferredChannel');
26 goog.require('goog.messaging.PortChannel');
27 goog.require('goog.messaging.PortNetwork'); // interface
28 goog.require('goog.object');
29
30
31
32 /**
33 * The leaf node of a network.
34 *
35 * @param {!goog.messaging.MessageChannel} operatorPort The channel for
36 * communicating with the operator. The other side of this channel should be
37 * passed to {@link goog.messaging.PortOperator#addPort}. Must be either a
38 * {@link goog.messaging.PortChannel} or a decorator wrapping a PortChannel;
39 * in particular, it must be able to send and receive {@link MessagePort}s.
40 * @constructor
41 * @extends {goog.Disposable}
42 * @implements {goog.messaging.PortNetwork}
43 * @final
44 */
45 goog.messaging.PortCaller = function(operatorPort) {
46 goog.messaging.PortCaller.base(this, 'constructor');
47
48 /**
49 * The channel to the {@link goog.messaging.PortOperator} for this network.
50 *
51 * @type {!goog.messaging.MessageChannel}
52 * @private
53 */
54 this.operatorPort_ = operatorPort;
55
56 /**
57 * The collection of channels for communicating with other contexts in the
58 * network. Each value can contain a {@link goog.aync.Deferred} and/or a
59 * {@link goog.messaging.MessageChannel}.
60 *
61 * If the value contains a Deferred, then the channel is a
62 * {@link goog.messaging.DeferredChannel} wrapping that Deferred. The Deferred
63 * will be resolved with a {@link goog.messaging.PortChannel} once we receive
64 * the appropriate port from the operator. This is the situation when this
65 * caller requests a connection to another context; the DeferredChannel is
66 * used to queue up messages until we receive the port from the operator.
67 *
68 * If the value does not contain a Deferred, then the channel is simply a
69 * {@link goog.messaging.PortChannel} communicating with the given context.
70 * This is the situation when this context received a port for the other
71 * context before it was requested.
72 *
73 * If a value exists for a given key, it must contain a channel, but it
74 * doesn't necessarily contain a Deferred.
75 *
76 * @type {!Object<{deferred: goog.async.Deferred,
77 * channel: !goog.messaging.MessageChannel}>}
78 * @private
79 */
80 this.connections_ = {};
81
82 this.operatorPort_.registerService(
83 goog.messaging.PortNetwork.GRANT_CONNECTION_SERVICE,
84 goog.bind(this.connectionGranted_, this), true /* opt_json */);
85 };
86 goog.inherits(goog.messaging.PortCaller, goog.Disposable);
87
88
89 /** @override */
90 goog.messaging.PortCaller.prototype.dial = function(name) {
91 if (name in this.connections_) {
92 return this.connections_[name].channel;
93 }
94
95 this.operatorPort_.send(
96 goog.messaging.PortNetwork.REQUEST_CONNECTION_SERVICE, name);
97 var deferred = new goog.async.Deferred();
98 var channel = new goog.messaging.DeferredChannel(deferred);
99 this.connections_[name] = {deferred: deferred, channel: channel};
100 return channel;
101 };
102
103
104 /**
105 * Registers a connection to another context in the network. This is called when
106 * the operator sends us one end of a {@link MessageChannel}, either because
107 * this caller requested a connection with another context, or because that
108 * context requested a connection with this caller.
109 *
110 * It's possible that the remote context and this one request each other roughly
111 * concurrently. The operator doesn't keep track of which contexts have been
112 * connected, so it will create two separate {@link MessageChannel}s in this
113 * case. However, the first channel created will reach both contexts first, so
114 * we simply ignore all connections with a given context after the first.
115 *
116 * @param {!Object|string} message The name of the context
117 * being connected and the port connecting the context.
118 * @private
119 */
120 goog.messaging.PortCaller.prototype.connectionGranted_ = function(message) {
121 var args = /** @type {{name: string, port: MessagePort}} */ (message);
122 var port = args['port'];
123 var entry = this.connections_[args['name']];
124 if (entry && (!entry.deferred || entry.deferred.hasFired())) {
125 // If two PortCallers request one another at the same time, the operator may
126 // send out a channel for connecting them multiple times. Since both callers
127 // will receive the first channel's ports first, we can safely ignore and
128 // close any future ports.
129 port.close();
130 } else if (!args['success']) {
131 throw new Error(args['message']);
132 } else {
133 port.start();
134 var channel = new goog.messaging.PortChannel(port);
135 if (entry) {
136 entry.deferred.callback(channel);
137 } else {
138 this.connections_[args['name']] = {channel: channel, deferred: null};
139 }
140 }
141 };
142
143
144 /** @override */
145 goog.messaging.PortCaller.prototype.disposeInternal = function() {
146 goog.dispose(this.operatorPort_);
147 goog.object.forEach(this.connections_, goog.dispose);
148 delete this.operatorPort_;
149 delete this.connections_;
150 goog.messaging.PortCaller.base(this, 'disposeInternal');
151 };