Debian Codegraph @

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

raw
1 package org.astrogrid.samp.client;
2
3 /**
4 * Defines an object that can be used to register with a running SAMP hub.
5 * Registration takes the form of providing a connection object which
6 * a client can use to perform further hub interactions.
7 * Client-side implementations will take care of communications,
8 * mapping between profile-specific transport mechanisms and the
9 * methods of the generated {@link HubConnection} objects.
10 *
11 * <p>The usual way for a prospective SAMP client to obtain an instance of
12 * this class is by using {@link DefaultClientProfile#getProfile}.
13 *
14 * <p>This interface is so-named partly for historical reasons;
15 * "HubConnectionFactory" might have been more appropriate.
16 *
17 * @author Mark Taylor
18 * @since 15 Jul 2008
19 */
20 public interface ClientProfile {
21
22 /**
23 * Attempts to register with a SAMP hub and return a corresponding
24 * connection object. Some profile-specific hub discovery mechanism
25 * is used to locate the hub.
26 * If no hub is running, null will normally be returned.
27 *
28 * @return hub connection representing a new registration, or null
29 * @throws SampException in case of some unexpected error
30 */
31 HubConnection register() throws SampException;
32
33 /**
34 * Indicates whether a hub contactable by this profile appears to be
35 * running. This is intended to execute reasonably quickly.
36 * It should not go as far as registering.
37 *
38 * @return true iff it looks like a hub is running
39 */
40 boolean isHubRunning();
41 }