Debian Codegraph @

src/java/org/astrogrid/samp/hub/HubService.java

raw
1 package org.astrogrid.samp.hub;
2
3 import java.util.List;
4 import java.util.Map;
5 import org.astrogrid.samp.client.HubConnection;
6 import org.astrogrid.samp.client.SampException;
7
8 /**
9 * Interface defining the work that the hub has to do.
10 * This is independent of profile or transport, and just concerns
11 * keeping track of clients and routing messages between them.
12 *
13 * @author Mark Taylor
14 * @since 15 Jul 2008
15 */
16 public interface HubService {
17
18 /**
19 * Begin operation. The {@link #register} method should not be
20 * called until the hub has been started.
21 */
22 void start();
23
24 /**
25 * Creates a new connection to this hub service, thereby initiating
26 * a new registered client.
27 *
28 * <p>It is the responsibility of the returned connection, not the
29 * user of that connection, to broadcast the various
30 * <code>samp.hub.event.*</code> notifications at the appropriate times.
31 *
32 * <p>Most of the <code>HubConnection</code> methods are declared to
33 * throw <code>SampException</code>, however, implementations may
34 * throw unchecked exceptions if that is more convenient;
35 * users of the connection should be prepared to catch these if
36 * they occur.
37 *
38 * @param profileToken identifier for the profile acting as gatekeeper
39 * for this connection
40 * @return new hub connection representing registration of a new client
41 */
42 HubConnection register( ProfileToken profileToken ) throws SampException;
43
44 /**
45 * Forcibly terminates any connections created by a previous call of
46 * {@link #register}
47 * with a particular <code>profileToken</code>.
48 * Any necessary hub events will be sent.
49 *
50 * @param profileToken previous argument to <code>register</code>
51 */
52 void disconnectAll( ProfileToken profileToken );
53
54 /**
55 * Indicates whether this hub service is currently open for operations.
56 *
57 * @return true iff called between {@link #start} and {@link #shutdown}
58 */
59 boolean isHubRunning();
60
61 /**
62 * Tidies up any resources owned by this object.
63 * Should be called when no longer required.
64 */
65 void shutdown();
66 }