package org.astrogrid.samp.client; import java.util.List; import java.util.Map; import org.astrogrid.samp.Metadata; import org.astrogrid.samp.RegInfo; import org.astrogrid.samp.Response; import org.astrogrid.samp.Subscriptions; /** * Represents a registered client's connection to a running hub. * An application typically obtains an instance of this class * from a {@link ClientProfile} object. * *
It is good practice to call {@link #unregister} when the connection * is finished with; however if it is not called explicitly, the * connection will unregister itself on object finalisation or JVM termination, * as long as the JVM shuts down cleanly. * * @author Mark Taylor * @since 15 Jul 2008 */ public interface HubConnection { /** * Returns the registration information associated with this connection. * * @return registration info */ RegInfo getRegInfo(); /** * Tells the hub how it can perform callbacks on the client by providing * a CallableClient object. This is required before the client * can declare subscriptions or make asynchronous calls. * * @param callable callable client */ void setCallable( CallableClient callable ) throws SampException; /** * Tests whether the connection is currently open. * * @throws SampException if the hub has disappeared or communications * are disrupted in some other way */ void ping() throws SampException; /** * Unregisters the client and terminates this connection. */ void unregister() throws SampException; /** * Declares this registered client's metadata. * * @param meta {@link org.astrogrid.samp.Metadata}-like map */ void declareMetadata( Map meta ) throws SampException; /** * Returns the metadata for another registered client. * * @param clientId public id for another registered client * @return metadata map */ Metadata getMetadata( String clientId ) throws SampException; /** * Declares this registered client's MType subscriptions. * *
Only permitted if this client is already callable.
*
* @param subs {@link org.astrogrid.samp.Subscriptions}-like map
*/
void declareSubscriptions( Map subs ) throws SampException;
/**
* Returns the subscriptions for another registered client.
*
* @param clientId public id for another registered client
* @return subscriptions map
*/
Subscriptions getSubscriptions( String clientId ) throws SampException;
/**
* Returns the list of client public IDs for those clients currently
* registered.
*
* @return array of client ids, excluding the one for this client
*/
String[] getRegisteredClients() throws SampException;
/**
* Returns a map of subscriptions for a given MType.
*
* @param mtype MType
* @return map in which the keys are the public IDs of clients subscribed
* to mtype
*/
Map getSubscribedClients( String mtype ) throws SampException;
/**
* Sends a message to a given client without wanting a response.
*
* @param recipientId public-id of client to receive message
* @param msg {@link org.astrogrid.samp.Message}-like map
*/
void notify( String recipientId, Map msg ) throws SampException;
/**
* Sends a message to all subscribed clients without wanting a response.
*
* @param msg {@link org.astrogrid.samp.Message}-like map
* @return list of public-ids for clients to which the notify will be sent
*/
List notifyAll( Map msg ) throws SampException;
/**
* Sends a message to a given client expecting a response.
* The receiveResponse method of this connection's
* {@link CallableClient} will be called with a
* response at some time in the future.
*
*
Only permitted if this client is already callable.
*
* @param recipientId public-id of client to receive message
* @param msgTag arbitrary string tagging this message for caller's
* benefit
* @param msg {@link org.astrogrid.samp.Message}-like map
* @return message ID
*/
String call( String recipientId, String msgTag, Map msg )
throws SampException;
/**
* Sends a message to all subscribed clients expecting responses.
* The receiveResponse method of this connection's
* {@link CallableClient} will be called with responses at some
* time in the future.
*
*
Only permitted if this client is already callable.
*
* @param msgTag arbitrary string tagging this message for caller's
* benefit
* @param msg {@link org.astrogrid.samp.Message}-like map
* @return public-id->msg-id map for clients to which an attempt to
* send the call will be made
*/
Map callAll( String msgTag, Map msg ) throws SampException;
/**
* Sends a message synchronously to a client, waiting for the response.
* If more seconds elapse than the value of the timeout
* parameter, an exception will result.
*
* @param recipientId public-id of client to receive message
* @param msg {@link org.astrogrid.samp.Message}-like map
* @param timeout timeout in seconds, or <0 for no timeout
* @return response
*/
Response callAndWait( String recipientId, Map msg, int timeout )
throws SampException;
/**
* Supplies a response to a previously received message.
*
* @param msgId ID associated with earlier send
* @param response {@link org.astrogrid.samp.Response}-like map
*/
void reply( String msgId, Map response ) throws SampException;
}