1
// Copyright 2010 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 An abstract superclass for message channels that handles the
17
 * repetitive details of registering and dispatching to services. This is more
18
 * useful for full-fledged channels than for decorators, since decorators
19
 * generally delegate service registering anyway.
20
 *
21
 */
22

23

24
goog.provide('goog.messaging.AbstractChannel');
25

26
goog.require('goog.Disposable');
27
goog.require('goog.json');
28
goog.require('goog.log');
29
goog.require('goog.messaging.MessageChannel');  // interface
30

31

32

33
/**
34
 * Creates an abstract message channel.
35
 *
36
 * @constructor
37
 * @extends {goog.Disposable}
38
 * @implements {goog.messaging.MessageChannel}
39
 */
40
goog.messaging.AbstractChannel = function() {
41
  goog.messaging.AbstractChannel.base(this, 'constructor');
42

43
  /**
44
   * The services registered for this channel.
45
   * @type {Object<string, {callback: function((string|!Object)),
46
                             objectPayload: boolean}>}
47
   * @private
48
   */
49
  this.services_ = {};
50
};
51
goog.inherits(goog.messaging.AbstractChannel, goog.Disposable);
52

53

54
/**
55
 * The default service to be run when no other services match.
56
 *
57
 * @type {?function(string, (string|!Object))}
58
 * @private
59
 */
60
goog.messaging.AbstractChannel.prototype.defaultService_;
61

62

63
/**
64
 * Logger for this class.
65
 * @type {goog.log.Logger}
66
 * @protected
67
 */
68
goog.messaging.AbstractChannel.prototype.logger =
69
    goog.log.getLogger('goog.messaging.AbstractChannel');
70

71

72
/**
73
 * Immediately calls opt_connectCb if given, and is otherwise a no-op. If
74
 * subclasses have configuration that needs to happen before the channel is
75
 * connected, they should override this and {@link #isConnected}.
76
 * @override
77
 */
78
goog.messaging.AbstractChannel.prototype.connect = function(opt_connectCb) {
79
  if (opt_connectCb) {
80
    opt_connectCb();
81
  }
82
};
83

84

85
/**
86
 * Always returns true. If subclasses have configuration that needs to happen
87
 * before the channel is connected, they should override this and
88
 * {@link #connect}.
89
 * @override
90
 */
91
goog.messaging.AbstractChannel.prototype.isConnected = function() {
92
  return true;
93
};
94

95

96
/** @override */
97
goog.messaging.AbstractChannel.prototype.registerService = function(
98
    serviceName, callback, opt_objectPayload) {
99
  this.services_[serviceName] = {
100
    callback: callback,
101
    objectPayload: !!opt_objectPayload
102
  };
103
};
104

105

106
/** @override */
107
goog.messaging.AbstractChannel.prototype.registerDefaultService = function(
108
    callback) {
109
  this.defaultService_ = callback;
110
};
111

112

113
/** @override */
114
goog.messaging.AbstractChannel.prototype.send = goog.abstractMethod;
115

116

117
/**
118
 * Delivers a message to the appropriate service. This is meant to be called by
119
 * subclasses when they receive messages.
120
 *
121
 * This method takes into account both explicitly-registered and default
122
 * services, as well as making sure that JSON payloads are decoded when
123
 * necessary. If the subclass is capable of passing objects as payloads, those
124
 * objects can be passed in to this method directly. Otherwise, the (potentially
125
 * JSON-encoded) strings should be passed in.
126
 *
127
 * @param {string} serviceName The name of the service receiving the message.
128
 * @param {string|!Object} payload The contents of the message.
129
 * @protected
130
 */
131
goog.messaging.AbstractChannel.prototype.deliver = function(
132
    serviceName, payload) {
133
  var service = this.getService(serviceName, payload);
134
  if (!service) {
135
    return;
136
  }
137

138
  var decodedPayload =
139
      this.decodePayload(serviceName, payload, service.objectPayload);
140
  if (goog.isDefAndNotNull(decodedPayload)) {
141
    service.callback(decodedPayload);
142
  }
143
};
144

145

146
/**
147
 * Find the service object for a given service name. If there's no service
148
 * explicitly registered, but there is a default service, a service object is
149
 * constructed for it.
150
 *
151
 * @param {string} serviceName The name of the service receiving the message.
152
 * @param {string|!Object} payload The contents of the message.
153
 * @return {?{callback: function((string|!Object)), objectPayload: boolean}} The
154
 *     service object for the given service, or null if none was found.
155
 * @protected
156
 */
157
goog.messaging.AbstractChannel.prototype.getService = function(
158
    serviceName, payload) {
159
  var service = this.services_[serviceName];
160
  if (service) {
161
    return service;
162
  } else if (this.defaultService_) {
163
    var callback = goog.partial(this.defaultService_, serviceName);
164
    var objectPayload = goog.isObject(payload);
165
    return {callback: callback, objectPayload: objectPayload};
166
  }
167

168
  goog.log.warning(this.logger, 'Unknown service name "' + serviceName + '"');
169
  return null;
170
};
171

172

173
/**
174
 * Converts the message payload into the format expected by the registered
175
 * service (either JSON or string).
176
 *
177
 * @param {string} serviceName The name of the service receiving the message.
178
 * @param {string|!Object} payload The contents of the message.
179
 * @param {boolean} objectPayload Whether the service expects an object or a
180
 *     plain string.
181
 * @return {string|Object} The payload in the format expected by the service, or
182
 *     null if something went wrong.
183
 * @protected
184
 */
185
goog.messaging.AbstractChannel.prototype.decodePayload = function(
186
    serviceName, payload, objectPayload) {
187
  if (objectPayload && goog.isString(payload)) {
188
    try {
189
      return goog.json.parse(payload);
190
    } catch (err) {
191
      goog.log.warning(
192
          this.logger, 'Expected JSON payload for ' + serviceName + ', was "' +
193
              payload + '"');
194
      return null;
195
    }
196
  } else if (!objectPayload && !goog.isString(payload)) {
197
    return goog.json.serialize(payload);
198
  }
199
  return payload;
200
};
201

202

203
/** @override */
204
goog.messaging.AbstractChannel.prototype.disposeInternal = function() {
205
  goog.messaging.AbstractChannel.base(this, 'disposeInternal');
206
  delete this.services_;
207
  delete this.defaultService_;
208
};
209

210