1 // ======================================================================== 2 // Copyright 2007 Dojo Foundation 3 // ------------------------------------------------------------------------ 4 // Licensed under the Apache License, Version 2.0 (the "License"); 5 // you may not use this file except in compliance with the License. 6 // You may obtain a copy of the License at 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // Unless required by applicable law or agreed to in writing, software 9 // distributed under the License is distributed on an "AS IS" BASIS, 10 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 11 // See the License for the specific language governing permissions and 12 // limitations under the License. 13 //======================================================================== 14 15 package dojox.cometd; 16 17 import java.util.Collection; 18 19 /* ------------------------------------------------------------ */ 20 /** Bayeux Interface. 21 * This interface represents the server side API for the Bayeux messaging protocol. 22 * <p> 23 * The implementation of Bayeux will be registered as a {@link javax.servlet.ServletContext} attribute 24 * with the name "dojox.cometd.bayeux". This may be set prior to the context being initialized 25 * (if the instance is shared between contexts) or during context initialization. 26 * <p> 27 * Bayeux implementations must be thread safe and multiple threads may simultaneously 28 * call Bayeux methods. 29 * 30 */ 31 public interface Bayeux 32 { 33 /**Meta definitions for channels*/ 34 public static final String META="/meta"; 35 /**Meta definitions for channels*/ 36 public static final String META_SLASH="/meta/"; 37 /**Meta definitions for channels - connect message*/ 38 public static final String META_CONNECT="/meta/connect"; 39 /**Meta definitions for channels - client messsage*/ 40 public static final String META_CLIENT="/meta/client"; 41 /**Meta definitions for channels - disconnect messsage*/ 42 public static final String META_DISCONNECT="/meta/disconnect"; 43 /**Meta definitions for channels - handshake messsage*/ 44 public static final String META_HANDSHAKE="/meta/handshake"; 45 /**Meta definitions for channels - ping messsage*/ 46 public static final String META_PING="/meta/ping"; 47 /**Meta definitions for channels - status messsage*/ 48 public static final String META_STATUS="/meta/status"; 49 /**Meta definitions for channels - subscribe messsage*/ 50 public static final String META_SUBSCRIBE="/meta/subscribe"; 51 /**Meta definitions for channels - unsubscribe messsage*/ 52 public static final String META_UNSUBSCRIBE="/meta/unsubscribe"; 53 /*Field names inside Bayeux messages*/ 54 /**Field names inside Bayeux messages - clientId field*/ 55 public static final String CLIENT_FIELD="clientId"; 56 /**Field names inside Bayeux messages - data field*/ 57 public static final String DATA_FIELD="data"; 58 /**Field names inside Bayeux messages - channel field*/ 59 public static final String CHANNEL_FIELD="channel"; 60 /**Field names inside Bayeux messages - id field*/ 61 public static final String ID_FIELD="id"; 62 /**Field names inside Bayeux messages - error field*/ 63 public static final String ERROR_FIELD="error"; 64 /**Field names inside Bayeux messages - timestamp field*/ 65 public static final String TIMESTAMP_FIELD="timestamp"; 66 /**Field names inside Bayeux messages - transport field*/ 67 public static final String TRANSPORT_FIELD="transport"; 68 /**Field names inside Bayeux messages - advice field*/ 69 public static final String ADVICE_FIELD="advice"; 70 /**Field names inside Bayeux messages - successful field*/ 71 public static final String SUCCESSFUL_FIELD="successful"; 72 /**Field names inside Bayeux messages - subscription field*/ 73 public static final String SUBSCRIPTION_FIELD="subscription"; 74 /**Field names inside Bayeux messages - ext field*/ 75 public static final String EXT_FIELD="ext"; 76 /**Field names inside Bayeux messages - connectionType field*/ 77 public static final String CONNECTION_TYPE_FIELD="connectionType"; 78 /**Field names inside Bayeux messages - version field*/ 79 public static final String VERSION_FIELD="version"; 80 /**Field names inside Bayeux messages - minimumVersion field*/ 81 public static final String MIN_VERSION_FIELD="minimumVersion"; 82 /**Field names inside Bayeux messages - supportedConnectionTypes field*/ 83 public static final String SUPP_CONNECTION_TYPE_FIELD="supportedConnectionTypes"; 84 /**Field names inside Bayeux messages - json-comment-filtered field*/ 85 public static final String JSON_COMMENT_FILTERED_FIELD="json-comment-filtered"; 86 /**Field names inside Bayeux messages - reconnect field*/ 87 public static final String RECONNECT_FIELD = "reconnect"; 88 /**Field names inside Bayeux messages - interval field*/ 89 public static final String INTERVAL_FIELD = "interval"; 90 /**Field values inside Bayeux messages - retry response*/ 91 public static final String RETRY_RESPONSE = "retry"; 92 /**Field values inside Bayeux messages - handshake response*/ 93 public static final String HANDSHAKE_RESPONSE = "handshake"; 94 /**Field values inside Bayeux messages - none response*/ 95 public static final String NONE_RESPONSE = "none"; 96 /**Service channel names-starts with*/ 97 public static final String SERVICE="/service"; 98 /**Service channel names-trailing slash*/ 99 public static final String SERVICE_SLASH="/service/"; 100 /*Transport types*/ 101 /**Transport types - long polling*/ 102 public static final String TRANSPORT_LONG_POLL="long-polling"; 103 /**Transport types - callback polling*/ 104 public static final String TRANSPORT_CALLBACK_POLL="callback-polling"; 105 /**Transport types - iframe*/ 106 public static final String TRANSPORT_IFRAME="iframe"; 107 /**Transport types - flash*/ 108 public static final String TRANSPORT_FLASH="flash"; 109 /** ServletContext attribute name used to obtain the Bayeux object */ 110 public static final String DOJOX_COMETD_BAYEUX="dojox.cometd.bayeux"; 111 /*http field names*/ 112 /**http helpers - text/json content type*/ 113 public static final String JSON_CONTENT_TYPE="text/json"; 114 /**http helpers - parameter name for json message*/ 115 public static final String MESSAGE_PARAMETER="message"; 116 /**http helpers - name of the jsonp parameter*/ 117 public static final String JSONP_PARAMETER="jsonp"; 118 /**http helpers - default name of the jsonp callback function*/ 119 public static final String JSONP_DEFAULT_NAME="jsonpcallback"; 120 121 /* ------------------------------------------------------------ */ 122 /** 123 * @deprecated user {@link Channel#addDataFilter(DataFilter)} 124 */ 125 public void addFilter(String channels, DataFilter filter); 126 127 /* ------------------------------------------------------------ */ 128 /** Deliver a message to a client. 129 * @deprecated use {@link Client#deliver(Client, Message)} 130 */ 131 public void deliver(Client fromClient, Client toClient, String toChannel, Message message); 132 133 /* ------------------------------------------------------------ */ 134 /** Get a Channel instance by ID. 135 * @param channelId The Channel ID 136 * @param create If true, a channel will be created if it does not exist. 137 * @return A Channel instance or null if it does not exist and create is false. 138 */ 139 public Channel getChannel(String channelId,boolean create); 140 141 /* ------------------------------------------------------------ */ 142 /** Get all known channels. 143 * @return A collection of all known channel instances. 144 */ 145 public Collection<Channel> getChannels(); 146 147 /* ------------------------------------------------------------ */ 148 public Client getClient(String clientId); 149 150 /* ------------------------------------------------------------ */ 151 public Collection<Client> getClients(); 152 153 /* ------------------------------------------------------------ */ 154 public SecurityPolicy getSecurityPolicy(); 155 156 /* ------------------------------------------------------------ */ 157 public boolean hasChannel(String channel); 158 159 /* ------------------------------------------------------------ */ 160 public boolean hasClient(String clientId); 161 162 /* ------------------------------------------------------------ */ 163 /** 164 * @deprecated use {@link #newClient(String)} 165 */ 166 public Client newClient(String idprefix, Listener listener); 167 168 /* ------------------------------------------------------------ */ 169 public Client newClient(String idprefix); 170 171 /* ------------------------------------------------------------ */ 172 /** Deliver data to a channel. 173 * @deprecated use {@link Channel#publish(Client, Object, String)} 174 * @param fromClient The client sending the data 175 * @param data The data itself which must be an Object that can be encoded with {@link JSON}. 176 * @param toChannel The Channel ID to which the data is targetted 177 * @param msgId optional message ID or null for automatic generation of a message ID. 178 */ 179 public void publish(Client fromClient, String toChannel, Object data, String msgId); 180 181 /* ------------------------------------------------------------ */ 182 public Channel removeChannel(String channel); 183 184 /* ------------------------------------------------------------ */ 185 public Client removeClient(String clientId); 186 187 /* ------------------------------------------------------------ */ 188 /** 189 * @deprecated user {@link Channel#removeDataFilter(DataFilter)} 190 */ 191 public void removeFilter(String channels, DataFilter filter); 192 193 /* ------------------------------------------------------------ */ 194 /** Set the security policy for the Bayeux instance. 195 * <p> 196 * The Security Policy will be called to check access for all handshakes, 197 * subscriptions and publishing. 198 * 199 * @param securityPolicy The security policy instance. 200 */ 201 public void setSecurityPolicy(SecurityPolicy securityPolicy); 202 203 /* ------------------------------------------------------------ */ 204 /** Subscribe to a channel. 205 * Equivalent to getChannel(toChannel).subscribe(subscriber). 206 * @deprecated use {@link Channel#subscribe(Client)} 207 * @param toChannel 208 * @param subscriber 209 * @param createChannel. Create the channel if it does not exist 210 */ 211 public void subscribe(String toChannel, Client subscriber); 212 213 /* ------------------------------------------------------------ */ 214 /** Unsubscribe to a channel 215 * @deprecated use {@link Channel#unsubscribe(Client)} 216 * @param toChannel 217 * @param subscriber 218 */ 219 public void unsubscribe(String toChannel, Client subscriber); 220 221 222 }