Package org.astrogrid.samp.client
Interface HubConnection
-
- All Known Implementing Classes:
FacadeHubService.FacadeHubConnection
,MessageTrackerHubConnector.MessageTrackerHubConnection
,StandardHubConnection
,UrlTrackerHubConnection
,WebHubConnection
,WrapperHubConnection
,WrapperHubConnection
,XmlRpcHubConnection
public interface HubConnection
Represents a registered client's connection to a running hub. An application typically obtains an instance of this class from aClientProfile
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
All Methods Instance Methods Abstract Methods Modifier and Type Method Description java.lang.String
call(java.lang.String recipientId, java.lang.String msgTag, java.util.Map msg)
Sends a message to a given client expecting a response.java.util.Map
callAll(java.lang.String msgTag, java.util.Map msg)
Sends a message to all subscribed clients expecting responses.Response
callAndWait(java.lang.String recipientId, java.util.Map msg, int timeout)
Sends a message synchronously to a client, waiting for the response.void
declareMetadata(java.util.Map meta)
Declares this registered client's metadata.void
declareSubscriptions(java.util.Map subs)
Declares this registered client's MType subscriptions.Metadata
getMetadata(java.lang.String clientId)
Returns the metadata for another registered client.RegInfo
getRegInfo()
Returns the registration information associated with this connection.java.lang.String[]
getRegisteredClients()
Returns the list of client public IDs for those clients currently registered.java.util.Map
getSubscribedClients(java.lang.String mtype)
Returns a map of subscriptions for a given MType.Subscriptions
getSubscriptions(java.lang.String clientId)
Returns the subscriptions for another registered client.void
notify(java.lang.String recipientId, java.util.Map msg)
Sends a message to a given client without wanting a response.java.util.List
notifyAll(java.util.Map msg)
Sends a message to all subscribed clients without wanting a response.void
ping()
Tests whether the connection is currently open.void
reply(java.lang.String msgId, java.util.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(java.util.Map meta) throws SampException
Declares this registered client's metadata.- Parameters:
meta
-Metadata
-like map- Throws:
SampException
-
getMetadata
Metadata getMetadata(java.lang.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(java.util.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(java.lang.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
java.lang.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
java.util.Map getSubscribedClients(java.lang.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(java.lang.String recipientId, java.util.Map msg) throws SampException
Sends a message to a given client without wanting a response.- Parameters:
recipientId
- public-id of client to receive messagemsg
-Message
-like map- Throws:
SampException
-
notifyAll
java.util.List notifyAll(java.util.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
java.lang.String call(java.lang.String recipientId, java.lang.String msgTag, java.util.Map msg) throws SampException
Sends a message to a given client expecting a response. ThereceiveResponse
method of this connection'sCallableClient
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 messagemsgTag
- arbitrary string tagging this message for caller's benefitmsg
-Message
-like map- Returns:
- message ID
- Throws:
SampException
-
callAll
java.util.Map callAll(java.lang.String msgTag, java.util.Map msg) throws SampException
Sends a message to all subscribed clients expecting responses. ThereceiveResponse
method of this connection'sCallableClient
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 benefitmsg
-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(java.lang.String recipientId, java.util.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 thetimeout
parameter, an exception will result.- Parameters:
recipientId
- public-id of client to receive messagemsg
-Message
-like maptimeout
- timeout in seconds, or <0 for no timeout- Returns:
- response
- Throws:
SampException
-
reply
void reply(java.lang.String msgId, java.util.Map response) throws SampException
Supplies a response to a previously received message.- Parameters:
msgId
- ID associated with earlier sendresponse
-Response
-like map- Throws:
SampException
-
-