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 }