Interface HubConnection

  • All Known Implementing Classes:
    XmlRpcHubConnection

    public interface HubConnection
    Represents a registered client's connection to a running hub. An application typically obtains an instance of this class from a ClientProfile object.

    It is good practice to call unregister() when the connection is finished with; however if it is not called explicitly, the connection will unregister itself on object finalisation or JVM termination, as long as the JVM shuts down cleanly.

    Since:
    15 Jul 2008
    Author:
    Mark Taylor
    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      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.
      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.
      void reply​(java.lang.String msgId, java.util.Map response)
      Supplies a response to a previously received message.
      void setCallable​(CallableClient callable)
      Tells the hub how it can perform callbacks on the client by providing a CallableClient object.
      void unregister()
      Unregisters the client and terminates this connection.
    • Method Detail

      • getRegInfo

        RegInfo getRegInfo()
        Returns the registration information associated with this connection.
        Returns:
        registration info
      • setCallable

        void setCallable​(CallableClient callable)
                  throws SampException
        Tells the hub how it can perform callbacks on the client by providing a CallableClient object. This is required before the client can declare subscriptions or make asynchronous calls.
        Parameters:
        callable - callable client
        Throws:
        SampException
      • ping

        void ping()
           throws SampException
        Tests whether the connection is currently open.
        Throws:
        SampException - if the hub has disappeared or communications are disrupted in some other way
      • declareMetadata

        void declareMetadata​(java.util.Map meta)
                      throws SampException
        Declares this registered client's metadata.
        Parameters:
        meta - Metadata-like map
        Throws:
        SampException
      • getMetadata

        Metadata getMetadata​(java.lang.String clientId)
                      throws SampException
        Returns the metadata for another registered client.
        Parameters:
        clientId - public id for another registered client
        Returns:
        metadata map
        Throws:
        SampException
      • declareSubscriptions

        void declareSubscriptions​(java.util.Map subs)
                           throws SampException
        Declares this registered client's MType subscriptions.

        Only permitted if this client is already callable.

        Parameters:
        subs - Subscriptions-like map
        Throws:
        SampException
      • getSubscriptions

        Subscriptions getSubscriptions​(java.lang.String clientId)
                                throws SampException
        Returns the subscriptions for another registered client.
        Parameters:
        clientId - public id for another registered client
        Returns:
        subscriptions map
        Throws:
        SampException
      • getRegisteredClients

        java.lang.String[] getRegisteredClients()
                                         throws SampException
        Returns the list of client public IDs for those clients currently registered.
        Returns:
        array of client ids, excluding the one for this client
        Throws:
        SampException
      • getSubscribedClients

        java.util.Map getSubscribedClients​(java.lang.String mtype)
                                    throws SampException
        Returns a map of subscriptions for a given MType.
        Parameters:
        mtype - MType
        Returns:
        map in which the keys are the public IDs of clients subscribed to mtype
        Throws:
        SampException
      • notify

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

        java.util.List notifyAll​(java.util.Map msg)
                          throws SampException
        Sends a message to all subscribed clients without wanting a response.
        Parameters:
        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 recipientId,
                              java.lang.String msgTag,
                              java.util.Map msg)
                       throws SampException
        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.

        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

        java.util.Map callAll​(java.lang.String msgTag,
                              java.util.Map msg)
                       throws SampException
        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.

        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

        Response callAndWait​(java.lang.String recipientId,
                             java.util.Map msg,
                             int timeout)
                      throws SampException
        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.
        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

        void reply​(java.lang.String msgId,
                   java.util.Map response)
            throws SampException
        Supplies a response to a previously received message.
        Parameters:
        msgId - ID associated with earlier send
        response - Response-like map
        Throws:
        SampException