Package org.astrogrid.samp.xmlrpc

Class 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

    • 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

    • Field Detail

      • 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

      • 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

      • 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