Debian Codegraph @

src/java/org/astrogrid/samp/client/HubConnection.java

raw
1 package org.astrogrid.samp.client;
2
3 import java.util.List;
4 import java.util.Map;
5 import org.astrogrid.samp.Metadata;
6 import org.astrogrid.samp.RegInfo;
7 import org.astrogrid.samp.Response;
8 import org.astrogrid.samp.Subscriptions;
9
10 /**
11 * Represents a registered client's connection to a running hub.
12 * An application typically obtains an instance of this class
13 * from a {@link ClientProfile} object.
14 *
15 * <p>It is good practice to call {@link #unregister} when the connection
16 * is finished with; however if it is not called explicitly, the
17 * connection will unregister itself on object finalisation or JVM termination,
18 * as long as the JVM shuts down cleanly.
19 *
20 * @author Mark Taylor
21 * @since 15 Jul 2008
22 */
23 public interface HubConnection {
24
25 /**
26 * Returns the registration information associated with this connection.
27 *
28 * @return registration info
29 */
30 RegInfo getRegInfo();
31
32 /**
33 * Tells the hub how it can perform callbacks on the client by providing
34 * a CallableClient object. This is required before the client
35 * can declare subscriptions or make asynchronous calls.
36 *
37 * @param callable callable client
38 */
39 void setCallable( CallableClient callable ) throws SampException;
40
41 /**
42 * Tests whether the connection is currently open.
43 *
44 * @throws SampException if the hub has disappeared or communications
45 * are disrupted in some other way
46 */
47 void ping() throws SampException;
48
49 /**
50 * Unregisters the client and terminates this connection.
51 */
52 void unregister() throws SampException;
53
54 /**
55 * Declares this registered client's metadata.
56 *
57 * @param meta {@link org.astrogrid.samp.Metadata}-like map
58 */
59 void declareMetadata( Map meta ) throws SampException;
60
61 /**
62 * Returns the metadata for another registered client.
63 *
64 * @param clientId public id for another registered client
65 * @return metadata map
66 */
67 Metadata getMetadata( String clientId ) throws SampException;
68
69 /**
70 * Declares this registered client's MType subscriptions.
71 *
72 * <p>Only permitted if this client is already callable.
73 *
74 * @param subs {@link org.astrogrid.samp.Subscriptions}-like map
75 */
76 void declareSubscriptions( Map subs ) throws SampException;
77
78 /**
79 * Returns the subscriptions for another registered client.
80 *
81 * @param clientId public id for another registered client
82 * @return subscriptions map
83 */
84 Subscriptions getSubscriptions( String clientId ) throws SampException;
85
86 /**
87 * Returns the list of client public IDs for those clients currently
88 * registered.
89 *
90 * @return array of client ids, excluding the one for this client
91 */
92 String[] getRegisteredClients() throws SampException;
93
94 /**
95 * Returns a map of subscriptions for a given MType.
96 *
97 * @param mtype MType
98 * @return map in which the keys are the public IDs of clients subscribed
99 * to <code>mtype</code>
100 */
101 Map getSubscribedClients( String mtype ) throws SampException;
102
103 /**
104 * Sends a message to a given client without wanting a response.
105 *
106 * @param recipientId public-id of client to receive message
107 * @param msg {@link org.astrogrid.samp.Message}-like map
108 */
109 void notify( String recipientId, Map msg ) throws SampException;
110
111 /**
112 * Sends a message to all subscribed clients without wanting a response.
113 *
114 * @param msg {@link org.astrogrid.samp.Message}-like map
115 * @return list of public-ids for clients to which the notify will be sent
116 */
117 List notifyAll( Map msg ) throws SampException;
118
119 /**
120 * Sends a message to a given client expecting a response.
121 * The <code>receiveResponse</code> method of this connection's
122 * {@link CallableClient} will be called with a
123 * response at some time in the future.
124 *
125 * <p>Only permitted if this client is already callable.
126 *
127 * @param recipientId public-id of client to receive message
128 * @param msgTag arbitrary string tagging this message for caller's
129 * benefit
130 * @param msg {@link org.astrogrid.samp.Message}-like map
131 * @return message ID
132 */
133 String call( String recipientId, String msgTag, Map msg )
134 throws SampException;
135
136 /**
137 * Sends a message to all subscribed clients expecting responses.
138 * The <code>receiveResponse</code> method of this connection's
139 * {@link CallableClient} will be called with responses at some
140 * time in the future.
141 *
142 * <p>Only permitted if this client is already callable.
143 *
144 * @param msgTag arbitrary string tagging this message for caller's
145 * benefit
146 * @param msg {@link org.astrogrid.samp.Message}-like map
147 * @return public-id->msg-id map for clients to which an attempt to
148 * send the call will be made
149 */
150 Map callAll( String msgTag, Map msg ) throws SampException;
151
152 /**
153 * Sends a message synchronously to a client, waiting for the response.
154 * If more seconds elapse than the value of the <code>timeout</code>
155 * parameter, an exception will result.
156 *
157 * @param recipientId public-id of client to receive message
158 * @param msg {@link org.astrogrid.samp.Message}-like map
159 * @param timeout timeout in seconds, or &lt;0 for no timeout
160 * @return response
161 */
162 Response callAndWait( String recipientId, Map msg, int timeout )
163 throws SampException;
164
165 /**
166 * Supplies a response to a previously received message.
167 *
168 * @param msgId ID associated with earlier send
169 * @param response {@link org.astrogrid.samp.Response}-like map
170 */
171 void reply( String msgId, Map response ) throws SampException;
172 }