Debian Codegraph @

src/java/org/astrogrid/samp/xmlrpc/HubActor.java

raw
1 package org.astrogrid.samp.xmlrpc;
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 * Standard Profile hub.
10 *
11 * @author Mark Taylor
12 * @since 15 Jul 2008
13 */
14 interface HubActor {
15
16 /**
17 * Throws an exception if service is not operating.
18 */
19 void ping() throws SampException;
20
21 /**
22 * Throws an exception if service is not operating.
23 *
24 * @param privateKey ignored
25 */
26 void ping( String privateKey ) throws SampException;
27
28 /**
29 * Registers a new client and returns a map with registration information.
30 *
31 * @param secret registration password
32 * @return {@link org.astrogrid.samp.RegInfo}-like map.
33 */
34 Map register( String secret ) throws SampException;
35
36 /**
37 * Unregisters a registered client.
38 *
39 * @param privateKey calling client private key
40 */
41 void unregister( String privateKey ) throws SampException;
42
43 /**
44 * Sets the XML-RPC URL to use for callbacks for a callable client.
45 *
46 * @param privateKey calling client private key
47 * @param url XML-RPC endpoint for client API callbacks
48 */
49 void setXmlrpcCallback( String privateKey, String url )
50 throws SampException;
51
52 /**
53 * Declares metadata for the calling client.
54 *
55 * @param privateKey calling client private key
56 * @param meta {@link org.astrogrid.samp.Metadata}-like map
57 */
58 void declareMetadata( String privateKey, Map meta )
59 throws SampException;
60
61 /**
62 * Returns metadata for a given client.
63 *
64 * @param privateKey calling client private key
65 * @param clientId public ID for client whose metadata is required
66 * @return {@link org.astrogrid.samp.Metadata}-like map
67 */
68 Map getMetadata( String privateKey, String clientId )
69 throws SampException;
70
71 /**
72 * Declares subscription information for the calling client.
73 *
74 * @param privateKey calling client private key
75 * @param subs {@link org.astrogrid.samp.Subscriptions}-like map
76 */
77 void declareSubscriptions( String privateKey, Map subs )
78 throws SampException;
79
80 /**
81 * Returns subscriptions for a given client.
82 *
83 * @param privateKey calling client private key
84 * @return {@link org.astrogrid.samp.Subscriptions}-like map
85 */
86 Map getSubscriptions( String privateKey, String clientId )
87 throws SampException;
88
89 /**
90 * Returns a list of the public-ids of all currently registered clients.
91 *
92 * @param privateKey calling client private key
93 * @return list of Strings
94 */
95 List getRegisteredClients( String privateKey ) throws SampException;
96
97 /**
98 * Returns a map of the clients subscribed to a given MType.
99 *
100 * @param privateKey calling client private key
101 * @param mtype MType of interest
102 * @return map in which the keys are the public-ids of clients subscribed
103 * to <code>mtype</code>
104 */
105 Map getSubscribedClients( String privateKey, String mtype )
106 throws SampException;
107
108 /**
109 * Sends a message to a given client without wanting a response.
110 *
111 * @param privateKey calling client private key
112 * @param recipientId public-id of client to receive message
113 * @param msg {@link org.astrogrid.samp.Message}-like map
114 */
115 void notify( String privateKey, String recipientId, Map msg )
116 throws SampException;
117
118 /**
119 * Sends a message to all subscribed clients without wanting a response.
120 *
121 * @param privateKey calling client private key
122 * @param msg {@link org.astrogrid.samp.Message}-like map
123 * @return list of public-ids for clients to which the notify will be sent
124 */
125 List notifyAll( String privateKey, Map msg ) throws SampException;
126
127 /**
128 * Sends a message to a given client expecting a response.
129 *
130 * @param privateKey calling client private key
131 * @param recipientId public-id of client to receive message
132 * @param msgTag arbitrary string tagging this message for caller's
133 * benefit
134 * @param msg {@link org.astrogrid.samp.Message}-like map
135 * @return message ID
136 */
137 String call( String privateKey, String recipientId, String msgTag,
138 Map msg ) throws SampException;
139
140 /**
141 * Sends a message to all subscribed clients expecting responses.
142 *
143 * @param privateKey calling client private key
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 privateKey, String msgTag, Map msg )
151 throws SampException;
152
153 /**
154 * Sends a message synchronously to a client.
155 *
156 * @param privateKey calling client private key
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 encoded as a SAMP int
160 * @return {@link org.astrogrid.samp.Response}-like map
161 */
162 Map callAndWait( String privateKey, String recipientId, Map msg,
163 String timeout ) throws SampException;
164
165 /**
166 * Responds to a previously sent message.
167 *
168 * @param privateKey calling client private key
169 * @param msgId ID associated with earlier send
170 * @param response {@link org.astrogrid.samp.Response}-like map
171 */
172 void reply( String privateKey, String msgId, Map response )
173 throws SampException;
174 }