Package org.astrogrid.samp.client

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

    Modifier and Type
    Method
    Description
    String
    call(String recipientId, String msgTag, Map msg)
    Sends a message to a given client expecting a response.
    Map
    callAll(String msgTag, Map msg)
    Sends a message to all subscribed clients expecting responses.
    Response
    callAndWait(String recipientId, Map msg, int timeout)
    Sends a message synchronously to a client, waiting for the response.
    void
    declareMetadata(Map meta)
    Declares this registered client's metadata.
    void
    declareSubscriptions(Map subs)
    Declares this registered client's MType subscriptions.
    Metadata
    getMetadata(String clientId)
    Returns the metadata for another registered client.
    RegInfo
    getRegInfo()
    Returns the registration information associated with this connection.
    String[]
    getRegisteredClients()
    Returns the list of client public IDs for those clients currently registered.
    Map
    getSubscribedClients(String mtype)
    Returns a map of subscriptions for a given MType.
    Subscriptions
    getSubscriptions(String clientId)
    Returns the subscriptions for another registered client.
    void
    notify(String recipientId, Map msg)
    Sends a message to a given client without wanting a response.
    List
    notifyAll(Map msg)
    Sends a message to all subscribed clients without wanting a response.
    void
    ping()
    Tests whether the connection is currently open.
    void
    reply(String msgId, 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 Details

    • 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

    • unregister

      void unregister() throws SampException
      Unregisters the client and terminates this connection.
      Throws:
      SampException

    • declareMetadata

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

    • getMetadata

      Metadata getMetadata(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(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(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

      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

      Map getSubscribedClients(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(String recipientId, 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

      List notifyAll(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

      String call(String recipientId, String msgTag, 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

      Map callAll(String msgTag, 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(String recipientId, 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(String msgId, 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