Debian Codegraph @

src/java/org/astrogrid/samp/web/WebHubActor.java

raw
1 package org.astrogrid.samp.web;
2
3 import java.util.List;
4 import java.util.Map;
5 import org.astrogrid.samp.client.SampException;
6
7 /**
8 * Defines the XML-RPC methods which must be implemented by a
9 * Web Profile hub.
10 * The register method is handled separately, since it has special
11 * requirements as regards the HTTP request that it arrives on.
12 *
13 * @author Mark Taylor
14 * @since 2 Feb 2011
15 */
16 interface WebHubActor {
17
18 /**
19 * Throws an exception if service is not operating.
20 */
21 void ping() throws SampException;
22
23 /**
24 * Throws an exception if service is not operating.
25 *
26 * @param privateKey ignored
27 */
28 void ping( String privateKey ) throws SampException;
29
30 /**
31 * Unregisters a registered client.
32 *
33 * @param privateKey calling client private key
34 */
35 void unregister( String privateKey ) throws SampException;
36
37 /**
38 * Declares metadata for the calling client.
39 *
40 * @param privateKey calling client private key
41 * @param meta {@link org.astrogrid.samp.Metadata}-like map
42 */
43 void declareMetadata( String privateKey, Map meta ) throws SampException;
44
45 /**
46 * Returns metadata for a given client.
47 *
48 * @param privateKey calling client private key
49 * @param clientId public ID for client whose metadata is required
50 * @return {@link org.astrogrid.samp.Metadata}-like map
51 */
52 Map getMetadata( String privateKey, String clientId ) throws SampException;
53
54 /**
55 * Declares subscription information for the calling client.
56 *
57 * @param privateKey calling client private key
58 * @param subs {@link org.astrogrid.samp.Subscriptions}-like map
59 */
60 void declareSubscriptions( String privateKey, Map subs )
61 throws SampException;
62
63 /**
64 * Returns subscriptions for a given client.
65 *
66 * @param privateKey calling client private key
67 * @return {@link org.astrogrid.samp.Subscriptions}-like map
68 */
69 Map getSubscriptions( String privateKey, String clientId )
70 throws SampException;
71
72 /**
73 * Returns a list of the public-ids of all currently registered clients.
74 *
75 * @param privateKey calling client private key
76 * @return list of Strings
77 */
78 List getRegisteredClients( String privateKey ) throws SampException;
79
80 /**
81 * Returns a map of the clients subscribed to a given MType.
82 *
83 * @param privateKey calling client private key
84 * @param mtype MType of interest
85 * @return map in which the keys are the public-ids of clients subscribed
86 * to <code>mtype</code>
87 */
88 Map getSubscribedClients( String privateKey, String mtype )
89 throws SampException;
90
91 /**
92 * Sends a message to a given client without wanting a response.
93 *
94 * @param privateKey calling client private key
95 * @param recipientId public-id of client to receive message
96 * @param msg {@link org.astrogrid.samp.Message}-like map
97 */
98 void notify( String privateKey, String recipientId, Map msg )
99 throws SampException;
100
101 /**
102 * Sends a message to all subscribed clients without wanting a response.
103 *
104 * @param privateKey calling client private key
105 * @param msg {@link org.astrogrid.samp.Message}-like map
106 * @return list of public-ids for clients to which the notify will be sent
107 */
108 List notifyAll( String privateKey, Map msg )
109 throws SampException;
110
111 /**
112 * Sends a message to a given client expecting a response.
113 *
114 * @param privateKey calling client private key
115 * @param recipientId public-id of client to receive message
116 * @param msgTag arbitrary string tagging this message for caller's
117 * benefit
118 * @param msg {@link org.astrogrid.samp.Message}-like map
119 * @return message ID
120 */
121 String call( String privateKey, String recipientId, String msgTag, Map msg )
122 throws SampException;
123
124 /**
125 * Sends a message to all subscribed clients expecting responses.
126 *
127 * @param privateKey calling client private key
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 public-id->msg-id map for clients to which an attempt to
132 * send the call will be made
133 */
134 Map callAll( String privateKey, String msgTag, Map msg )
135 throws SampException;
136
137 /**
138 * Sends a message synchronously to a client.
139 *
140 * @param privateKey calling client private key
141 * @param recipientId public-id of client to receive message
142 * @param msg {@link org.astrogrid.samp.Message}-like map
143 * @param timeout timeout in seconds encoded as a SAMP int
144 * @return {@link org.astrogrid.samp.Response}-like map
145 */
146 Map callAndWait( String privateKey, String recipientId, Map msg,
147 String timeout ) throws SampException;
148
149 /**
150 * Responds to a previously sent message.
151 *
152 * @param privateKey calling client private key
153 * @param msgId ID associated with earlier send
154 * @param response {@link org.astrogrid.samp.Response}-like map
155 */
156 void reply( String privateKey, String msgId, Map response )
157 throws SampException;
158
159 /**
160 * Indicates that the client will or will not be calling
161 * {@link #pullCallbacks} to receive callable client-type
162 * callbacks until further notice.
163 *
164 * @param privateKey calling client private key
165 * @param allow flag indicating that the client will/will not
166 * be pulling callbacks, encoded as a SAMP boolean ("1"/"0")
167 */
168 void allowReverseCallbacks( String privateKey, String allow )
169 throws SampException;
170
171 /**
172 * Waits for up to a certain length of time for any callbacks to be
173 * delivered.
174 *
175 * @param privateKey calling client private key
176 * @param timeout timeout in seconds encoded as a SAMP int
177 * @return list of {@link Callback}-like maps ready for
178 * processing by the client; may be empty if none are ready
179 */
180 List pullCallbacks( String privateKey, String timeout )
181 throws SampException;
182 }