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 }