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.EventListener;
18 import java.util.List;
19
20 /* ------------------------------------------------------------ */
21 /** A Bayeux Client.
22 * <p>
23 * A client may subscribe to channels and publish messages to channels.
24 * Client instances should not be directly created by uses, but should
25 * be obtained via the {@link Bayeux#getClient(String)} or {@link Bayeux#newClient(String, Receiver)}
26 * methods.
27 * </p>
28 * <p>
29 * Three types of client may be represented by this interface:<nl>
30 * <li>The server representation of a remote client connected via HTTP</li>
31 * <li>A server side client</li>
32 * <li>A java client connected to a remote Bayeux server</li>
33 * </nl>
34 */
35 public interface Client
36 {
37 /* ------------------------------------------------------------ */
38 public abstract String getId();
39
40 /* ------------------------------------------------------------ */
41 /** Publish data from this client.
42 * This is equivalent to {@link Bayeux#publish(Client, String, Object, String)} with this client passed
43 * as the fromClient.
44 * @deprecated use {@link Channel#publish(Client, Object, String)}
45 * @param data The data itself which must be an Object that can be encoded with {@link JSON}.
46 * @param toChannel The Channel ID to which the data is targetted
47 * @param msgId optional message ID or null for automatic generation of a message ID.
48 */
49 public void publish(String toChannel, Object data, String msgId);
50
51 /* ------------------------------------------------------------ */
52 /** Subscribe this client to a channel.
53 * This is equivalent to {@link Bayeux#subscribe(String, Client)} with this client passed.
54 * Equivalent to getChannel(toChannel).subscribe(subscriber).
55 * @deprecated use {@link Channel#subscribe(Client)}
56 * @param toChannel
57 */
58 public void subscribe(String toChannel);
59
60 /* ------------------------------------------------------------ */
61 /** Unsubscribe this client from a channel.
62 * This is equivalent to {@link Bayeux#unsubscribe(String, Client)} with this client passed.
63 * @deprecated use {@link Channel#unsubscribe(Client)}
64 * @param toChannel
65 */
66 public void unsubscribe(String toChannel);
67
68 /* ------------------------------------------------------------ */
69 public abstract boolean hasMessages();
70
71 /* ------------------------------------------------------------ */
72 /** Take any messages queued for a client.
73 *
74 */
75 public abstract List<Message> takeMessages();
76
77 /* ------------------------------------------------------------ */
78 /** Deliver a message to this client only
79 * Deliver a message directly to the client. The message is not
80 * filtered or published to a channel.
81 * @deprecated use {@link #deliver(Client, String, Object, String)}
82 * @param from The Client that published the message, or null if not known/available
83 * @param message
84 */
85 public void deliver(Client from, Message message);
86
87 /* ------------------------------------------------------------ */
88 public void deliver(Client from, String toChannel, Object data, String id);
89
90 /* ------------------------------------------------------------ */
91 /**
92 * @deprecated use {@link #addListener(EventListener)}
93 */
94 public void setListener(Listener listener);
95
96 /* ------------------------------------------------------------ */
97 /**
98 * @deprecated Returns only the first listener added
99 */
100 public Listener getListener();
101
102 /* ------------------------------------------------------------ */
103 public void addListener(EventListener listener);
104
105 /* ------------------------------------------------------------ */
106 public void removeListener(EventListener listener);
107
108 /* ------------------------------------------------------------ */
109 /**
110 * @return True if the client is local. False if this client is either a remote HTTP client or
111 * a java client to a remote server.
112 */
113 public boolean isLocal();
114
115
116 /* ------------------------------------------------------------ */
117 /** Start a batch of messages.
118 * Messages will not be delivered remotely until the corresponding
119 * endBatch is called. Batches may be nested and messages are only sent
120 * once all batches are ended.
121 */
122 public void startBatch();
123
124 /* ------------------------------------------------------------ */
125 /** End a batch of messages.
126 * Messages will not be delivered that have been queued since the previous
127 * startBatch is called. Batches may be nested and messages are only sent
128 * once all batches are ended.
129 */
130 public void endBatch();
131
132
133 }