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 and Description
XmlRpcHubConnection(SampXmlRpcClient xClient, String prefix, List registerArgs) Constructor.

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.
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 Detail

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 Detail

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