Package org.astrogrid.samp.xmlrpc

# Class XmlRpcHubConnection

java.lang.Object
org.astrogrid.samp.xmlrpc.XmlRpcHubConnection

All Implemented Interfaces:
  `HubConnection`

public abstract class XmlRpcHubConnection extends Object implements HubConnection
Partial HubConnection implementation based on XML-RPC. No implementation is provided for the `HubConnection.setCallable(org.astrogrid.samp.client.CallableClient)` method. This is a useful base class for XML-RPC-based profile implementations, but it is not perfectly general: some assumptions, compatible with the Standard Profile, are made about the way that XML-RPC calls are mapped on to SAMP hub interface calls.

Since:
  16 Jul 2008
Author:
  Mark Taylor, Sylvain Lafrasse

## Constructor Summary

Constructors
Constructor
Description
`XmlRpcHubConnection(SampXmlRpcClient xClient, String prefix, List registerArgs)`
Constructor.

## 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.
`Object`
`exec(String methodName, Object[] params)`
Makes an XML-RPC call to the SAMP hub represented by this connection.
`abstract Object`
`getClientKey()`
Returns an object which is used as the first argument of most XML-RPC calls to the hub.
`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.
`Object`
`rawExec(String fqName, List paramList)`
Actually makes an XML-RPC call to the SAMP hub represented by this connection.
`void`
`reply(String msgId, Map response)`
Supplies a response to a previously received message.
`void`
`unregister()`
Unregisters the client and terminates this connection.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Methods inherited from interface org.astrogrid.samp.client.HubConnection

`setCallable`

## Constructor Details

### XmlRpcHubConnection

public XmlRpcHubConnection(SampXmlRpcClient xClient, String prefix, List registerArgs) throws SampException
Constructor.

Parameters:
  `xClient` - XML-RPC client
  `prefix` - string prepended to all hub interface method names to turn them into XML-RPC method names
  `registerArgs` - arguments to the profile-specific "register" method to initiate this connection
Throws:
  `SampException`

## Method Details

### getRegInfo

public RegInfo getRegInfo()
Description copied from interface: `HubConnection`
Returns the registration information associated with this connection.

Specified by:
  `getRegInfo` in interface `HubConnection`
Returns:
  registration info

### ping

public void ping() throws SampException
Description copied from interface: `HubConnection`
Tests whether the connection is currently open.

Specified by:
  `ping` in interface `HubConnection`
Throws:
  `SampException` - if the hub has disappeared or communications are disrupted in some other way

### unregister

public void unregister() throws SampException
Description copied from interface: `HubConnection`
Unregisters the client and terminates this connection.

Specified by:
  `unregister` in interface `HubConnection`
Throws:
  `SampException`

### declareMetadata

public void declareMetadata(Map meta) throws SampException
Description copied from interface: `HubConnection`
Declares this registered client's metadata.

Specified by:
  `declareMetadata` in interface `HubConnection`
Parameters:
  `meta` - `Metadata`-like map
Throws:
  `SampException`

### getMetadata

public Metadata getMetadata(String clientId) throws SampException
Description copied from interface: `HubConnection`
Returns the metadata for another registered client.

Specified by:
  `getMetadata` in interface `HubConnection`
Parameters:
  `clientId` - public id for another registered client
Returns:
  metadata map
Throws:
  `SampException`

### declareSubscriptions

public void declareSubscriptions(Map subs) throws SampException
Description copied from interface: `HubConnection`
Declares this registered client's MType subscriptions.

Only permitted if this client is already callable.

Specified by:
  `declareSubscriptions` in interface `HubConnection`
Parameters:
  `subs` - `Subscriptions`-like map
Throws:
  `SampException`

### getSubscriptions

public Subscriptions getSubscriptions(String clientId) throws SampException
Description copied from interface: `HubConnection`
Returns the subscriptions for another registered client.

Specified by:
  `getSubscriptions` in interface `HubConnection`
Parameters:
  `clientId` - public id for another registered client
Returns:
  subscriptions map
Throws:
  `SampException`

### getRegisteredClients

public String[] getRegisteredClients() throws SampException
Description copied from interface: `HubConnection`
Returns the list of client public IDs for those clients currently registered.

Specified by:
  `getRegisteredClients` in interface `HubConnection`
Returns:
  array of client ids, excluding the one for this client
Throws:
  `SampException`

### getSubscribedClients

public Map getSubscribedClients(String mtype) throws SampException
Description copied from interface: `HubConnection`
Returns a map of subscriptions for a given MType.

Specified by:
  `getSubscribedClients` in interface `HubConnection`
Parameters:
  `mtype` - MType
Returns:
  map in which the keys are the public IDs of clients subscribed to `mtype`
Throws:
  `SampException`

### notify

public void notify(String recipientId, Map msg) throws SampException
Description copied from interface: `HubConnection`
Sends a message to a given client without wanting a response.

Specified by:
  `notify` in interface `HubConnection`
Parameters:
  `recipientId` - public-id of client to receive message
  `msg` - `Message`-like map
Throws:
  `SampException`

### notifyAll

public List notifyAll(Map msg) throws SampException
Description copied from interface: `HubConnection`
Sends a message to all subscribed clients without wanting a response.

Specified by:
  `notifyAll` in interface `HubConnection`
Parameters:
  `msg` - `Message`-like map
Returns:
  list of public-ids for clients to which the notify will be sent
Throws:
  `SampException`

### call

public String call(String recipientId, String msgTag, Map msg) throws SampException
Description copied from interface: `HubConnection`
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.

Specified by:
  `call` in interface `HubConnection`
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

public Map callAll(String msgTag, Map msg) throws SampException
Description copied from interface: `HubConnection`
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.

Specified by:
  `callAll` in interface `HubConnection`
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

public Response callAndWait(String recipientId, Map msg, int timeout) throws SampException
Description copied from interface: `HubConnection`
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.

Specified by:
  `callAndWait` in interface `HubConnection`
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

public void reply(String msgId, Map response) throws SampException
Description copied from interface: `HubConnection`
Supplies a response to a previously received message.

Specified by:
  `reply` in interface `HubConnection`
Parameters:
  `msgId` - ID associated with earlier send
  `response` - `Response`-like map
Throws:
  `SampException`

### getClientKey

public abstract Object getClientKey()
Returns an object which is used as the first argument of most XML-RPC calls to the hub.

Returns:
  SAMP-friendly object to identify this client

### exec

public Object exec(String methodName, Object[] params) throws SampException
Makes an XML-RPC call to the SAMP hub represented by this connection. The result of `getClientKey()` is passed as the first argument of the XML-RPC call.

Parameters:
  `methodName` - unqualified SAMP hub API method name
  `params` - array of method parameters
Returns:
  XML-RPC call return value
Throws:
  `SampException`

### rawExec

public Object rawExec(String fqName, List paramList) throws SampException
Actually makes an XML-RPC call to the SAMP hub represented by this connection.

Parameters:
  `fqName` - fully qualified SAMP hub API method name
  `paramList` - list of method parameters
Returns:
  XML-RPC call return value
Throws:
  `SampException`