Interface WebHubActor

  • All Known Implementing Classes:
    WebHubXmlRpcHandler.WebHubActorImpl

    interface WebHubActor
    Defines the XML-RPC methods which must be implemented by a Web Profile hub. The register method is handled separately, since it has special requirements as regards the HTTP request that it arrives on.
    Since:
    2 Feb 2011
    Author:
    Mark Taylor
    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      void allowReverseCallbacks​(java.lang.String privateKey, java.lang.String allow)
      Indicates that the client will or will not be calling pullCallbacks(java.lang.String, java.lang.String) to receive callable client-type callbacks until further notice.
      java.lang.String call​(java.lang.String privateKey, 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 privateKey, java.lang.String msgTag, java.util.Map msg)
      Sends a message to all subscribed clients expecting responses.
      java.util.Map callAndWait​(java.lang.String privateKey, java.lang.String recipientId, java.util.Map msg, java.lang.String timeout)
      Sends a message synchronously to a client.
      void declareMetadata​(java.lang.String privateKey, java.util.Map meta)
      Declares metadata for the calling client.
      void declareSubscriptions​(java.lang.String privateKey, java.util.Map subs)
      Declares subscription information for the calling client.
      java.util.Map getMetadata​(java.lang.String privateKey, java.lang.String clientId)
      Returns metadata for a given client.
      java.util.List getRegisteredClients​(java.lang.String privateKey)
      Returns a list of the public-ids of all currently registered clients.
      java.util.Map getSubscribedClients​(java.lang.String privateKey, java.lang.String mtype)
      Returns a map of the clients subscribed to a given MType.
      java.util.Map getSubscriptions​(java.lang.String privateKey, java.lang.String clientId)
      Returns subscriptions for a given client.
      void notify​(java.lang.String privateKey, java.lang.String recipientId, java.util.Map msg)
      Sends a message to a given client without wanting a response.
      java.util.List notifyAll​(java.lang.String privateKey, java.util.Map msg)
      Sends a message to all subscribed clients without wanting a response.
      void ping()
      Throws an exception if service is not operating.
      void ping​(java.lang.String privateKey)
      Throws an exception if service is not operating.
      java.util.List pullCallbacks​(java.lang.String privateKey, java.lang.String timeout)
      Waits for up to a certain length of time for any callbacks to be delivered.
      void reply​(java.lang.String privateKey, java.lang.String msgId, java.util.Map response)
      Responds to a previously sent message.
      void unregister​(java.lang.String privateKey)
      Unregisters a registered client.
    • Method Detail

      • ping

        void ping​(java.lang.String privateKey)
           throws SampException
        Throws an exception if service is not operating.
        Parameters:
        privateKey - ignored
        Throws:
        SampException
      • unregister

        void unregister​(java.lang.String privateKey)
                 throws SampException
        Unregisters a registered client.
        Parameters:
        privateKey - calling client private key
        Throws:
        SampException
      • declareMetadata

        void declareMetadata​(java.lang.String privateKey,
                             java.util.Map meta)
                      throws SampException
        Declares metadata for the calling client.
        Parameters:
        privateKey - calling client private key
        meta - Metadata-like map
        Throws:
        SampException
      • getMetadata

        java.util.Map getMetadata​(java.lang.String privateKey,
                                  java.lang.String clientId)
                           throws SampException
        Returns metadata for a given client.
        Parameters:
        privateKey - calling client private key
        clientId - public ID for client whose metadata is required
        Returns:
        Metadata-like map
        Throws:
        SampException
      • declareSubscriptions

        void declareSubscriptions​(java.lang.String privateKey,
                                  java.util.Map subs)
                           throws SampException
        Declares subscription information for the calling client.
        Parameters:
        privateKey - calling client private key
        subs - Subscriptions-like map
        Throws:
        SampException
      • getSubscriptions

        java.util.Map getSubscriptions​(java.lang.String privateKey,
                                       java.lang.String clientId)
                                throws SampException
        Returns subscriptions for a given client.
        Parameters:
        privateKey - calling client private key
        Returns:
        Subscriptions-like map
        Throws:
        SampException
      • getRegisteredClients

        java.util.List getRegisteredClients​(java.lang.String privateKey)
                                     throws SampException
        Returns a list of the public-ids of all currently registered clients.
        Parameters:
        privateKey - calling client private key
        Returns:
        list of Strings
        Throws:
        SampException
      • getSubscribedClients

        java.util.Map getSubscribedClients​(java.lang.String privateKey,
                                           java.lang.String mtype)
                                    throws SampException
        Returns a map of the clients subscribed to a given MType.
        Parameters:
        privateKey - calling client private key
        mtype - MType of interest
        Returns:
        map in which the keys are the public-ids of clients subscribed to mtype
        Throws:
        SampException
      • notify

        void notify​(java.lang.String privateKey,
                    java.lang.String recipientId,
                    java.util.Map msg)
             throws SampException
        Sends a message to a given client without wanting a response.
        Parameters:
        privateKey - calling client private key
        recipientId - public-id of client to receive message
        msg - Message-like map
        Throws:
        SampException
      • notifyAll

        java.util.List notifyAll​(java.lang.String privateKey,
                                 java.util.Map msg)
                          throws SampException
        Sends a message to all subscribed clients without wanting a response.
        Parameters:
        privateKey - calling client private key
        msg - Message-like map
        Returns:
        list of public-ids for clients to which the notify will be sent
        Throws:
        SampException
      • call

        java.lang.String call​(java.lang.String privateKey,
                              java.lang.String recipientId,
                              java.lang.String msgTag,
                              java.util.Map msg)
                       throws SampException
        Sends a message to a given client expecting a response.
        Parameters:
        privateKey - calling client private key
        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

        java.util.Map callAll​(java.lang.String privateKey,
                              java.lang.String msgTag,
                              java.util.Map msg)
                       throws SampException
        Sends a message to all subscribed clients expecting responses.
        Parameters:
        privateKey - calling client private key
        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

        java.util.Map callAndWait​(java.lang.String privateKey,
                                  java.lang.String recipientId,
                                  java.util.Map msg,
                                  java.lang.String timeout)
                           throws SampException
        Sends a message synchronously to a client.
        Parameters:
        privateKey - calling client private key
        recipientId - public-id of client to receive message
        msg - Message-like map
        timeout - timeout in seconds encoded as a SAMP int
        Returns:
        Response-like map
        Throws:
        SampException
      • reply

        void reply​(java.lang.String privateKey,
                   java.lang.String msgId,
                   java.util.Map response)
            throws SampException
        Responds to a previously sent message.
        Parameters:
        privateKey - calling client private key
        msgId - ID associated with earlier send
        response - Response-like map
        Throws:
        SampException
      • allowReverseCallbacks

        void allowReverseCallbacks​(java.lang.String privateKey,
                                   java.lang.String allow)
                            throws SampException
        Indicates that the client will or will not be calling pullCallbacks(java.lang.String, java.lang.String) to receive callable client-type callbacks until further notice.
        Parameters:
        privateKey - calling client private key
        allow - flag indicating that the client will/will not be pulling callbacks, encoded as a SAMP boolean ("1"/"0")
        Throws:
        SampException
      • pullCallbacks

        java.util.List pullCallbacks​(java.lang.String privateKey,
                                     java.lang.String timeout)
                              throws SampException
        Waits for up to a certain length of time for any callbacks to be delivered.
        Parameters:
        privateKey - calling client private key
        timeout - timeout in seconds encoded as a SAMP int
        Returns:
        list of Callback-like maps ready for processing by the client; may be empty if none are ready
        Throws:
        SampException