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

Field Summary

Fields
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 Summary

Constructors
Constructor and 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 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.

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 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(java.util.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(java.lang.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(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 interface HubConnection
    
    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 interface HubConnection
    
    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 interface HubConnection
    
    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 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(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 interface HubConnection
    
    Parameters:
    
    recipientId - public-id of client to receive message
    
    msg - 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 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 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. 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 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. 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(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 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(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 interface HubConnection
    
    Parameters:
    
    msgId - ID associated with earlier send
    
    response - 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 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 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 name
    
    paramList - 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 class java.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 cast
    
    clazz - class to cast to
    
    name - 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

Class XmlRpcHubConnection

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

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

Field Detail

xClient_

prefix_

regInfo_

unregistered_

logger_

Constructor Detail

XmlRpcHubConnection

Method Detail

getRegInfo

ping

unregister

declareMetadata

getMetadata

declareSubscriptions

getSubscriptions

getRegisteredClients

getSubscribedClients

notify

notifyAll

call

callAll

callAndWait

reply

getClientKey

exec

rawExec

finish

finalize

asType

asString

asList

asMap