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 }