org.astrogrid.samp.client

Interface HubConnection

All Known Implementing Classes:

XmlRpcHubConnection

public interface HubConnection

Represents a registered client's connection to a running hub. An application typically obtains an instance of this class from a ClientProfile object.

It is good practice to call 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.

Since:

15 Jul 2008

Author:

Mark Taylor

Method Summary

Modifier and Type	Method and Description
String	call(String recipientId, String msgTag, Map msg) Sends a message to a given client expecting a response.
Map	callAll(String msgTag, Map msg) Sends a message to all subscribed clients expecting responses.
Response	callAndWait(String recipientId, Map msg, int timeout) Sends a message synchronously to a client, waiting for the response.
void	declareMetadata(Map meta) Declares this registered client's metadata.
void	declareSubscriptions(Map subs) Declares this registered client's MType subscriptions.
Metadata	getMetadata(String clientId) Returns the metadata for another registered client.
RegInfo	getRegInfo() Returns the registration information associated with this connection.
String[]	getRegisteredClients() Returns the list of client public IDs for those clients currently registered.
Map	getSubscribedClients(String mtype) Returns a map of subscriptions for a given MType.
Subscriptions	getSubscriptions(String clientId) Returns the subscriptions for another registered client.
void	notify(String recipientId, Map msg) Sends a message to a given client without wanting a response.
List	notifyAll(Map msg) Sends a message to all subscribed clients without wanting a response.
void	ping() Tests whether the connection is currently open.
void	reply(String msgId, Map response) Supplies a response to a previously received message.
void	setCallable(CallableClient callable) Tells the hub how it can perform callbacks on the client by providing a CallableClient object.
void	unregister() Unregisters the client and terminates this connection.

Method Detail

getRegInfo

RegInfo getRegInfo()

Returns the registration information associated with this connection.

Returns:

registration info

setCallable

void setCallable(CallableClient callable)
          throws SampException

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.

Parameters:

callable - callable client

Throws:

SampException

ping

void ping()
   throws SampException

Tests whether the connection is currently open.

Throws:

SampException - if the hub has disappeared or communications are disrupted in some other way

unregister

void unregister()
         throws SampException

Unregisters the client and terminates this connection.

Throws:

SampException

declareMetadata

void declareMetadata(Map meta)
              throws SampException

Declares this registered client's metadata.

Parameters:

meta - Metadata-like map

Throws:

SampException

getMetadata

Metadata getMetadata(String clientId)
              throws SampException

Returns the metadata for another registered client.

Parameters:

clientId - public id for another registered client

Returns:

metadata map

Throws:

SampException

declareSubscriptions

void declareSubscriptions(Map subs)
                   throws SampException

Declares this registered client's MType subscriptions.

Only permitted if this client is already callable.

Parameters:

subs - Subscriptions-like map

Throws:

SampException

getSubscriptions

Subscriptions getSubscriptions(String clientId)
                        throws SampException

Returns the subscriptions for another registered client.

Parameters:

clientId - public id for another registered client

Returns:

subscriptions map

Throws:

SampException

getRegisteredClients

String[] getRegisteredClients()
                       throws SampException

Returns the list of client public IDs for those clients currently registered.

Returns:

array of client ids, excluding the one for this client

Throws:

SampException

getSubscribedClients

Map getSubscribedClients(String mtype)
                  throws SampException

Returns a map of subscriptions for a given MType.

Parameters:

mtype - MType

Returns:

map in which the keys are the public IDs of clients subscribed to mtype

Throws:

SampException

notify

void notify(String recipientId,
            Map msg)
     throws SampException

Sends a message to a given client without wanting a response.

Parameters:

recipientId - public-id of client to receive message

msg - Message-like map

Throws:

SampException

notifyAll

List notifyAll(Map msg)
        throws SampException

Sends a message to all subscribed clients without wanting a response.

Parameters:

msg - Message-like map

Returns:

list of public-ids for clients to which the notify will be sent

Throws:

SampException

call

String call(String recipientId,
            String msgTag,
            Map msg)
     throws SampException

Sends a message to a given client expecting a response. The receiveResponse method of this connection's CallableClient will be called with a response at some time in the future.

Only permitted if this client is already callable.

Parameters:

recipientId - public-id of client to receive message

msgTag - arbitrary string tagging this message for caller's benefit

msg - Message-like map

Returns:

message ID

Throws:

SampException

callAll

Map callAll(String msgTag,
            Map msg)
     throws SampException

Sends a message to all subscribed clients expecting responses. The receiveResponse method of this connection's CallableClient will be called with responses at some time in the future.

Only permitted if this client is already callable.

Parameters:

msgTag - arbitrary string tagging this message for caller's benefit

msg - Message-like map

Returns:

public-id->msg-id map for clients to which an attempt to send the call will be made

Throws:

SampException

callAndWait

Response callAndWait(String recipientId,
                     Map msg,
                     int timeout)
              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.

Parameters:

recipientId - public-id of client to receive message

msg - Message-like map

timeout - timeout in seconds, or <0 for no timeout

Returns:

response

Throws:

SampException

reply

void reply(String msgId,
           Map response)
    throws SampException

Supplies a response to a previously received message.

Parameters:

msgId - ID associated with earlier send

response - Response-like map

Throws:

SampException