public abstract class XmlRpcHubConnection extends java.lang.Object implements HubConnection
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.Modifier and Type | Field and Description |
---|---|
private static java.util.logging.Logger |
logger_ |
private java.lang.String |
prefix_ |
private RegInfo |
regInfo_ |
private boolean |
unregistered_ |
private SampXmlRpcClient |
xClient_ |
Constructor and Description |
---|
XmlRpcHubConnection(SampXmlRpcClient xClient,
java.lang.String prefix,
java.util.List registerArgs)
Constructor.
|
Modifier and Type | Method and 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.
|
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
setCallable
private final SampXmlRpcClient xClient_
private final java.lang.String prefix_
private final RegInfo regInfo_
private boolean unregistered_
private static final java.util.logging.Logger logger_
public XmlRpcHubConnection(SampXmlRpcClient xClient, java.lang.String prefix, java.util.List registerArgs) throws SampException
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 connectionSampException
public RegInfo getRegInfo()
HubConnection
getRegInfo
in interface HubConnection
public void ping() throws SampException
HubConnection
ping
in interface HubConnection
SampException
- if the hub has disappeared or communications
are disrupted in some other waypublic void unregister() throws SampException
HubConnection
unregister
in interface HubConnection
SampException
public void declareMetadata(java.util.Map meta) throws SampException
HubConnection
declareMetadata
in interface HubConnection
meta
- Metadata
-like mapSampException
public Metadata getMetadata(java.lang.String clientId) throws SampException
HubConnection
getMetadata
in interface HubConnection
clientId
- public id for another registered clientSampException
public void declareSubscriptions(java.util.Map subs) throws SampException
HubConnection
Only permitted if this client is already callable.
declareSubscriptions
in interface HubConnection
subs
- Subscriptions
-like mapSampException
public Subscriptions getSubscriptions(java.lang.String clientId) throws SampException
HubConnection
getSubscriptions
in interface HubConnection
clientId
- public id for another registered clientSampException
public java.lang.String[] getRegisteredClients() throws SampException
HubConnection
getRegisteredClients
in interface HubConnection
SampException
public java.util.Map getSubscribedClients(java.lang.String mtype) throws SampException
HubConnection
getSubscribedClients
in interface HubConnection
mtype
- MTypemtype
SampException
public void notify(java.lang.String recipientId, java.util.Map msg) throws SampException
HubConnection
notify
in interface HubConnection
recipientId
- public-id of client to receive messagemsg
- Message
-like mapSampException
public java.util.List notifyAll(java.util.Map msg) throws SampException
HubConnection
notifyAll
in interface HubConnection
msg
- Message
-like mapSampException
public java.lang.String call(java.lang.String recipientId, java.lang.String msgTag, java.util.Map msg) throws SampException
HubConnection
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.
call
in interface HubConnection
recipientId
- public-id of client to receive messagemsgTag
- arbitrary string tagging this message for caller's
benefitmsg
- Message
-like mapSampException
public java.util.Map callAll(java.lang.String msgTag, java.util.Map msg) throws SampException
HubConnection
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.
callAll
in interface HubConnection
msgTag
- arbitrary string tagging this message for caller's
benefitmsg
- Message
-like mapSampException
public Response callAndWait(java.lang.String recipientId, java.util.Map msg, int timeout) throws SampException
HubConnection
timeout
parameter, an exception will result.callAndWait
in interface HubConnection
recipientId
- public-id of client to receive messagemsg
- Message
-like maptimeout
- timeout in seconds, or <0 for no timeoutSampException
public void reply(java.lang.String msgId, java.util.Map response) throws SampException
HubConnection
reply
in interface HubConnection
msgId
- ID associated with earlier sendresponse
- Response
-like mapSampException
public abstract java.lang.Object getClientKey()
public java.lang.Object exec(java.lang.String methodName, java.lang.Object[] params) throws SampException
getClientKey()
is passed as the first argument
of the XML-RPC call.methodName
- unqualified SAMP hub API method nameparams
- array of method parametersSampException
public java.lang.Object rawExec(java.lang.String fqName, java.util.List paramList) throws SampException
fqName
- fully qualified SAMP hub API method nameparamList
- list of method parametersSampException
private void finish()
public void finalize() throws java.lang.Throwable
finalize
in class java.lang.Object
java.lang.Throwable
private static java.lang.Object asType(java.lang.Object obj, java.lang.Class clazz, java.lang.String name) throws SampException
obj
- object to castclazz
- class to cast toname
- SAMP name of typeSampException
- if cast attempt failedprivate java.lang.String asString(java.lang.Object obj) throws SampException
obj
- objectSampException
- if cast attempt failedprivate java.util.List asList(java.lang.Object obj) throws SampException
obj
- objectSampException
- if cast attempt failedprivate java.util.Map asMap(java.lang.Object obj) throws SampException
obj
- objectSampException
- if cast attempt failed