Package org.astrogrid.samp.xmlrpc
Class XmlRpcHubConnection
- java.lang.Object
-
- org.astrogrid.samp.xmlrpc.XmlRpcHubConnection
-
- All Implemented Interfaces:
HubConnection
- Direct Known Subclasses:
StandardHubConnection
,WebHubConnection
public abstract class XmlRpcHubConnection extends java.lang.Object implements HubConnection
Partial HubConnection implementation based on XML-RPC. No implementation is provided for theHubConnection.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
-
-
Field Summary
Fields Modifier and Type Field Description private static java.util.logging.Logger
logger_
private java.lang.String
prefix_
private RegInfo
regInfo_
private boolean
unregistered_
private SampXmlRpcClient
xClient_
-
Constructor Summary
Constructors Constructor Description XmlRpcHubConnection(SampXmlRpcClient xClient, java.lang.String prefix, java.util.List registerArgs)
Constructor.
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description private java.util.List
asList(java.lang.Object obj)
Utility method to cast an object to a list.private java.util.Map
asMap(java.lang.Object obj)
Utility method to cast an object to a map.private java.lang.String
asString(java.lang.Object obj)
Utility method to cast an object to a string.private static java.lang.Object
asType(java.lang.Object obj, java.lang.Class clazz, java.lang.String name)
Utility method to cast an object to a given SAMP-like type.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.java.lang.Object
exec(java.lang.String methodName, java.lang.Object[] params)
Makes an XML-RPC call to the SAMP hub represented by this connection.void
finalize()
Unregisters if not already unregistered.private void
finish()
Unregisters if not already unregistered.abstract java.lang.Object
getClientKey()
Returns an object which is used as the first argument of most XML-RPC calls to the hub.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.java.lang.Object
rawExec(java.lang.String fqName, java.util.List paramList)
Actually makes an XML-RPC call to the SAMP hub represented by this connection.void
reply(java.lang.String msgId, java.util.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, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
-
Methods inherited from interface org.astrogrid.samp.client.HubConnection
setCallable
-
-
-
-
Field Detail
-
xClient_
private final SampXmlRpcClient xClient_
-
prefix_
private final java.lang.String prefix_
-
regInfo_
private final RegInfo regInfo_
-
unregistered_
private boolean unregistered_
-
logger_
private static final java.util.logging.Logger logger_
-
-
Constructor Detail
-
XmlRpcHubConnection
public XmlRpcHubConnection(SampXmlRpcClient xClient, java.lang.String prefix, java.util.List registerArgs) throws SampException
Constructor.- Parameters:
xClient
- XML-RPC clientprefix
- string prepended to all hub interface method names to turn them into XML-RPC method namesregisterArgs
- 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 interfaceHubConnection
- 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 interfaceHubConnection
- 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 interfaceHubConnection
- Throws:
SampException
-
declareMetadata
public void declareMetadata(java.util.Map meta) throws SampException
Description copied from interface:HubConnection
Declares this registered client's metadata.- Specified by:
declareMetadata
in interfaceHubConnection
- Parameters:
meta
-Metadata
-like map- Throws:
SampException
-
getMetadata
public Metadata getMetadata(java.lang.String clientId) throws SampException
Description copied from interface:HubConnection
Returns the metadata for another registered client.- Specified by:
getMetadata
in interfaceHubConnection
- Parameters:
clientId
- public id for another registered client- Returns:
- metadata map
- Throws:
SampException
-
declareSubscriptions
public void declareSubscriptions(java.util.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 interfaceHubConnection
- Parameters:
subs
-Subscriptions
-like map- Throws:
SampException
-
getSubscriptions
public Subscriptions getSubscriptions(java.lang.String clientId) throws SampException
Description copied from interface:HubConnection
Returns the subscriptions for another registered client.- Specified by:
getSubscriptions
in interfaceHubConnection
- Parameters:
clientId
- public id for another registered client- Returns:
- subscriptions map
- Throws:
SampException
-
getRegisteredClients
public java.lang.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 interfaceHubConnection
- Returns:
- array of client ids, excluding the one for this client
- Throws:
SampException
-
getSubscribedClients
public java.util.Map getSubscribedClients(java.lang.String mtype) throws SampException
Description copied from interface:HubConnection
Returns a map of subscriptions for a given MType.- Specified by:
getSubscribedClients
in interfaceHubConnection
- Parameters:
mtype
- MType- Returns:
- map in which the keys are the public IDs of clients subscribed
to
mtype
- Throws:
SampException
-
notify
public void notify(java.lang.String recipientId, java.util.Map msg) throws SampException
Description copied from interface:HubConnection
Sends a message to a given client without wanting a response.- Specified by:
notify
in interfaceHubConnection
- Parameters:
recipientId
- public-id of client to receive messagemsg
-Message
-like map- Throws:
SampException
-
notifyAll
public java.util.List notifyAll(java.util.Map msg) throws SampException
Description copied from interface:HubConnection
Sends a message to all subscribed clients without wanting a response.- Specified by:
notifyAll
in interfaceHubConnection
- Parameters:
msg
-Message
-like map- Returns:
- list of public-ids for clients to which the notify will be sent
- Throws:
SampException
-
call
public java.lang.String call(java.lang.String recipientId, java.lang.String msgTag, java.util.Map msg) throws SampException
Description copied from interface:HubConnection
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.
- Specified by:
call
in interfaceHubConnection
- 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
public java.util.Map callAll(java.lang.String msgTag, java.util.Map msg) throws SampException
Description copied from interface:HubConnection
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.
- Specified by:
callAll
in interfaceHubConnection
- 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
public Response callAndWait(java.lang.String recipientId, java.util.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 thetimeout
parameter, an exception will result.- Specified by:
callAndWait
in interfaceHubConnection
- 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
public void reply(java.lang.String msgId, java.util.Map response) throws SampException
Description copied from interface:HubConnection
Supplies a response to a previously received message.- Specified by:
reply
in interfaceHubConnection
- Parameters:
msgId
- ID associated with earlier sendresponse
-Response
-like map- Throws:
SampException
-
getClientKey
public abstract java.lang.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 java.lang.Object exec(java.lang.String methodName, java.lang.Object[] params) throws SampException
Makes an XML-RPC call to the SAMP hub represented by this connection. The result ofgetClientKey()
is passed as the first argument of the XML-RPC call.- Parameters:
methodName
- unqualified SAMP hub API method nameparams
- array of method parameters- Returns:
- XML-RPC call return value
- Throws:
SampException
-
rawExec
public java.lang.Object rawExec(java.lang.String fqName, java.util.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 nameparamList
- list of method parameters- Returns:
- XML-RPC call return value
- Throws:
SampException
-
finish
private void finish()
Unregisters if not already unregistered. May harmlessly be called multiple times.
-
finalize
public void finalize() throws java.lang.Throwable
Unregisters if not already unregistered.- Overrides:
finalize
in classjava.lang.Object
- Throws:
java.lang.Throwable
-
asType
private static java.lang.Object asType(java.lang.Object obj, java.lang.Class clazz, java.lang.String name) throws SampException
Utility method to cast an object to a given SAMP-like type.- Parameters:
obj
- object to castclazz
- class to cast toname
- SAMP name of type- Returns:
- obj
- Throws:
SampException
- if cast attempt failed
-
asString
private java.lang.String asString(java.lang.Object obj) throws SampException
Utility method to cast an object to a string.- Parameters:
obj
- object- Returns:
- object as string
- Throws:
SampException
- if cast attempt failed
-
asList
private java.util.List asList(java.lang.Object obj) throws SampException
Utility method to cast an object to a list.- Parameters:
obj
- object- Returns:
- object as list
- Throws:
SampException
- if cast attempt failed
-
asMap
private java.util.Map asMap(java.lang.Object obj) throws SampException
Utility method to cast an object to a map.- Parameters:
obj
- object- Returns:
- object as map
- Throws:
SampException
- if cast attempt failed
-
-