Package 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
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 Details

### 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`