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