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 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
};
152

153