Debian Codegraph @

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

raw
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 interface for asynchronous message-passing channels.
17 *
18 * This interface is useful for writing code in a message-passing style that's
19 * independent of the underlying communication medium. It's also useful for
20 * adding decorators that wrap message channels and add extra functionality on
21 * top. For example, {@link goog.messaging.BufferedChannel} enqueues messages
22 * until communication is established, while {@link goog.messaging.MultiChannel}
23 * splits a single underlying channel into multiple virtual ones.
24 *
25 * Decorators should be passed their underlying channel(s) in the constructor,
26 * and should assume that those channels are already connected. Decorators are
27 * responsible for disposing of the channels they wrap when the decorators
28 * themselves are disposed. Decorators should also follow the APIs of the
29 * individual methods listed below.
30 *
31 */
32
33
34 goog.provide('goog.messaging.MessageChannel');
35
36
37
38 /**
39 * @interface
40 */
41 goog.messaging.MessageChannel = function() {};
42
43
44 /**
45 * Initiates the channel connection. When this method is called, all the
46 * information needed to connect the channel has to be available.
47 *
48 * Implementers should only require this method to be called if the channel
49 * needs to be configured in some way between when it's created and when it
50 * becomes active. Otherwise, the channel should be immediately active and this
51 * method should do nothing but immediately call opt_connectCb.
52 *
53 * @param {Function=} opt_connectCb Called when the channel has been connected
54 * and is ready to use.
55 */
56 goog.messaging.MessageChannel.prototype.connect = function(opt_connectCb) {};
57
58
59 /**
60 * Gets whether the channel is connected.
61 *
62 * If {@link #connect} is not required for this class, this should always return
63 * true. Otherwise, this should return true by the time the callback passed to
64 * {@link #connect} has been called and always after that.
65 *
66 * @return {boolean} Whether the channel is connected.
67 */
68 goog.messaging.MessageChannel.prototype.isConnected = function() {};
69
70
71 /**
72 * Registers a service to be called when a message is received.
73 *
74 * Implementers shouldn't impose any restrictions on the service names that may
75 * be registered. If some services are needed as control codes,
76 * {@link goog.messaging.MultiMessageChannel} can be used to safely split the
77 * channel into "public" and "control" virtual channels.
78 *
79 * @param {string} serviceName The name of the service.
80 * @param {function((string|!Object))} callback The callback to process the
81 * incoming messages. Passed the payload. If opt_objectPayload is set, the
82 * payload is decoded and passed as an object.
83 * @param {boolean=} opt_objectPayload If true, incoming messages for this
84 * service are expected to contain an object, and will be deserialized from
85 * a string automatically if necessary. It's the responsibility of
86 * implementors of this class to perform the deserialization.
87 */
88 goog.messaging.MessageChannel.prototype.registerService = function(
89 serviceName, callback, opt_objectPayload) {};
90
91
92 /**
93 * Registers a service to be called when a message is received that doesn't
94 * match any other services.
95 *
96 * @param {function(string, (string|!Object))} callback The callback to process
97 * the incoming messages. Passed the service name and the payload. Since
98 * some channels can pass objects natively, the payload may be either an
99 * object or a string.
100 */
101 goog.messaging.MessageChannel.prototype.registerDefaultService = function(
102 callback) {};
103
104
105 /**
106 * Sends a message over the channel.
107 *
108 * @param {string} serviceName The name of the service this message should be
109 * delivered to.
110 * @param {string|!Object} payload The value of the message. If this is an
111 * Object, it is serialized to a string before sending if necessary. It's
112 * the responsibility of implementors of this class to perform the
113 * serialization.
114 */
115 goog.messaging.MessageChannel.prototype.send = function(serviceName, payload) {
116 };