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