Package org.astrogrid.samp.hub

Class BasicHubService

  • All Implemented Interfaces:
    HubService
    Direct Known Subclasses:
    GuiHubService
    public class BasicHubService
extends java.lang.Object
implements HubService
    HubService implementation.
    Since:
    15 Jul 2008
    Author:
    Mark Taylor

    • Constructor Summary

      Constructors 
      Constructor Description
      BasicHubService​(java.util.Random random)
      Constructor.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      protected java.lang.String call​(HubClient caller, java.lang.String recipientId, java.lang.String msgTag, java.util.Map message)
      Does the work for the call method of connections registered with this service.
      protected java.util.Map callAll​(HubClient caller, java.lang.String msgTag, java.util.Map message)
      Does the work for the call method of connections registered with this service.
      protected Response callAndWait​(HubClient caller, java.lang.String recipientId, java.util.Map message, int timeout)
      Does the work for the callAndWait method of connections registered with this service.
      private boolean canSend​(HubClient sender, HubClient recipient, java.lang.String mtype)
      Indicates whether a given send is permitted.
      private void checkSend​(HubClient sender, HubClient recipient, java.lang.String mtype)
      Checks if a given send is permitted.
      protected HubClient createClient​(java.lang.String publicId, ProfileToken ptoken)
      Factory method used to create all the client objects which will be used by this hub service.
      protected ClientSet createClientSet()
      Factory method used to create the client set used by this hub service.
      protected HubConnection createConnection​(HubClient caller)
      Returns a new HubConnection for use by a given hub client.
      protected AbstractMessageHandler[] createHubMessageHandlers()
      Constructs a list of MessageHandlers to use for the client provided by the Hub.
      protected void declareMetadata​(HubClient caller, java.util.Map meta)
      Does the work for the declareMetadata method of connections registered with this service.
      protected void declareSubscriptions​(HubClient caller, java.util.Map subscriptions)
      Does the work for the declareSubscriptions method of connections registered with this service.
      private void disconnect​(java.lang.String[] clientIds, Message discoMsg)
      Forcibly disconnects a number of clients for the same reason.
      void disconnect​(java.lang.String clientId, java.lang.String reason)
      Forcibly disconnects a given client.
      void disconnectAll​(ProfileToken profileToken)
      Forcibly terminates any connections created by a previous call of HubService.register(org.astrogrid.samp.hub.ProfileToken) with a particular profileToken.
      private HubClient getClient​(java.lang.String id)
      Returns the client object corresponding to a public client ID.
      ClientSet getClientSet()
      Returns the structure which keeps track of registered clients.
      java.util.Comparator getIdComparator()
      Returns a comparator which will order client IDs.
      protected Metadata getMetadata​(HubClient caller, java.lang.String clientId)
      Does the work for the getMetadata method of connections registered with this service.
      protected java.lang.String[] getRegisteredClients​(HubClient caller)
      Does the work for the getRegisteredClients method of connections registered with this service.
      private java.lang.String getSendError​(HubClient sender, HubClient recipient, java.lang.String mtype)
      Does the work to determine whether a given sending client is permitted to send a message with a given MType to a given recipient.
      HubConnection getServiceConnection()
      Returns the HubConnection object used by the hub itself to send and receive messages.
      protected java.util.Map getSubscribedClients​(HubClient caller, java.lang.String mtype)
      Does the work for the getSubscribedClients method of connections registered with this service.
      protected Subscriptions getSubscriptions​(HubClient caller, java.lang.String clientId)
      Does the work for the getSubscriptions method of connections registered with this service.
      private Subscriptions getSubscriptionsFor​(HubClient client, Subscriptions subs)
      Returns the view of a given subscriptions map to be presented to a sending client.
      private void hubEvent​(Message msg)
      Broadcast an event message to all subscribed clients.
      boolean isHubRunning()
      Indicates whether this hub service is currently open for operations.
      protected void notify​(HubClient caller, java.lang.String recipientId, java.util.Map message)
      Does the work for the notify method of connections registered with this service.
      protected java.util.List notifyAll​(HubClient caller, java.util.Map message)
      Does the work for the notifyAll method of connections registered with this service.
      HubConnection register​(ProfileToken ptoken)
      Creates a new connection to this hub service, thereby initiating a new registered client.
      protected void reply​(HubClient caller, java.lang.String msgIdStr, java.util.Map resp)
      Does the work for the reply method of connections registered with this service.
      protected void setCallable​(HubClient caller, CallableClient callable)
      Does the work for the setCallable method of connections registered with this service.
      void shutdown()
      Tidies up any resources owned by this object.
      void start()
      Begin operation.
      protected void unregister​(HubClient caller)
      Does the work for the unregister method of conections registered with this service.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Field Detail

      • waiterMap_

        private final java.util.Map waiterMap_

      • serviceClient_

        private HubClient serviceClient_

      • serviceClientConnection_

        private HubConnection serviceClientConnection_

      • started_

        private volatile boolean started_

      • shutdown_

        private volatile boolean shutdown_

      • logger_

        private final java.util.logging.Logger logger_

      • INTERNAL_PROFILE

        private static final ProfileToken INTERNAL_PROFILE

      • MAX_TIMEOUT

        public static int MAX_TIMEOUT
        The maximum timeout for a synchronous call permitted in seconds. Default is 43200 = 12 hours.

      • MAX_WAITERS

        public static int MAX_WAITERS
        The maximum number of concurrently pending synchronous calls. Default is 100.

    • Constructor Detail

      • BasicHubService

        public BasicHubService​(java.util.Random random)
        Constructor.
        Parameters:
        random - random number generator used for message tags etc

    • Method Detail

      • createClientSet

        protected ClientSet createClientSet()
        Factory method used to create the client set used by this hub service.
        Returns:
        client set

      • createClient

        protected HubClient createClient​(java.lang.String publicId,
                                 ProfileToken ptoken)
        Factory method used to create all the client objects which will be used by this hub service.
        Parameters:
        publicId - client public ID
        ptoken - connection source
        Returns:
        hub client

      • createHubMessageHandlers

        protected AbstractMessageHandler[] createHubMessageHandlers()
        Constructs a list of MessageHandlers to use for the client provided by the Hub.
        Returns:
        hub message handler list

      • getIdComparator

        public java.util.Comparator getIdComparator()
        Returns a comparator which will order client IDs. The ordering is in creation sequence.
        Returns:
        public ID comparator

      • getClientSet

        public ClientSet getClientSet()
        Returns the structure which keeps track of registered clients.
        Returns:
        client set

      • register

        public HubConnection register​(ProfileToken ptoken)
                       throws SampException
        Description copied from interface: HubService
        Creates a new connection to this hub service, thereby initiating a new registered client.

        It is the responsibility of the returned connection, not the user of that connection, to broadcast the various samp.hub.event.* notifications at the appropriate times.

        Most of the HubConnection methods are declared to throw SampException, however, implementations may throw unchecked exceptions if that is more convenient; users of the connection should be prepared to catch these if they occur.

        Specified by:
        register in interface HubService
        Parameters:
        ptoken - identifier for the profile acting as gatekeeper for this connection
        Returns:
        new hub connection representing registration of a new client
        Throws:
        SampException

      • createConnection

        protected HubConnection createConnection​(HubClient caller)
        Returns a new HubConnection for use by a given hub client. The instance methods of the returned object delegate to similarly named protected methods of this BasicHubService object. These BasicHubService methods may therefore be overridden to modify the behaviour of such returned connections.
        Parameters:
        caller - client requiring a connection
        Returns:
        connection whose methods may be called by or on behalf of caller

      • getRegisteredClients

        protected java.lang.String[] getRegisteredClients​(HubClient caller)
                                           throws SampException
        Does the work for the getRegisteredClients method of connections registered with this service.
        Parameters:
        caller - calling client
        Returns:
        array of registered client IDs excluding caller's
        Throws:
        SampException
        See Also:
        HubConnection.getRegisteredClients()

      • getSubscribedClients

        protected java.util.Map getSubscribedClients​(HubClient caller,
                                             java.lang.String mtype)
                                      throws SampException
        Does the work for the getSubscribedClients method of connections registered with this service.
        Parameters:
        caller - calling client
        mtype - message type
        Returns:
        map in which the keys are the public IDs of clients subscribed to mtype
        Throws:
        SampException
        See Also:
        HubConnection.getSubscribedClients(java.lang.String)

      • notifyAll

        protected java.util.List notifyAll​(HubClient caller,
                                   java.util.Map message)
                            throws SampException
        Does the work for the notifyAll method of connections registered with this service.
        Parameters:
        caller - calling client
        message - message
        Returns:
        list of public IDs for clients to which the notify will be sent
        Throws:
        SampException
        See Also:
        HubConnection.notifyAll(java.util.Map)

      • callAll

        protected java.util.Map callAll​(HubClient caller,
                                java.lang.String msgTag,
                                java.util.Map message)
                         throws SampException
        Does the work for the call method of connections registered with this service.
        Parameters:
        caller - calling client
        msgTag - message tag
        message - message
        Returns:
        publicId->msgId map for clients to which an attempt to send the call will be made
        Throws:
        SampException
        See Also:
        HubConnection.callAll(java.lang.String, java.util.Map)

      • getServiceConnection

        public HubConnection getServiceConnection()
        Returns the HubConnection object used by the hub itself to send and receive messages. This is the one which apparently sends samp.hub.event.shutdown messages etc.
        Returns:
        hub service's own hub connection

      • disconnect

        public void disconnect​(java.lang.String clientId,
                       java.lang.String reason)
        Forcibly disconnects a given client. This call does three things:
        1. sends a samp.hub.disconnect message to the client which is about to be ejected, if the client is subscribed to that MType
        2. removes that client from this hub's client set so that any further communication attempts to or from it will fail
        3. broadcasts a samp.hub.unregister message to all remaining clients indicating that the client has disappeared
        Parameters:
        clientId - public-id of client to eject
        reason - short text string indicating reason for ejection

      • disconnect

        private void disconnect​(java.lang.String[] clientIds,
                        Message discoMsg)
        Forcibly disconnects a number of clients for the same reason.
        Parameters:
        clientIds - public-ids of clients to disconnect
        discoMsg - message to send to clients which will effect disconnection (samp.hub.disconnect or samp.hub.event.shutdown)

      • shutdown

        public void shutdown()
        Description copied from interface: HubService
        Tidies up any resources owned by this object. Should be called when no longer required.
        Specified by:
        shutdown in interface HubService

      • hubEvent

        private void hubEvent​(Message msg)
        Broadcast an event message to all subscribed clients. The sender of this message is the hub application itself.
        Parameters:
        msg - message to broadcast

      • getClient

        private HubClient getClient​(java.lang.String id)
                     throws SampException
        Returns the client object corresponding to a public client ID. If no such client is registered, throw an exception.
        Parameters:
        id - client public id
        Returns:
        HubClient object
        Throws:
        SampException

      • checkSend

        private void checkSend​(HubClient sender,
                       HubClient recipient,
                       java.lang.String mtype)
                throws SampException
        Checks if a given send is permitted. Throws an exception if not.
        Parameters:
        sender - sending client
        recipient - receiving client
        mtype - MType
        Throws:
        SampException - if the send is not permitted

      • canSend

        private boolean canSend​(HubClient sender,
                        HubClient recipient,
                        java.lang.String mtype)
        Indicates whether a given send is permitted.
        Parameters:
        sender - sending client
        recipient - receiving client
        mtype - MType
        Returns:
        true iff send OK

      • getSubscriptionsFor

        private Subscriptions getSubscriptionsFor​(HubClient client,
                                          Subscriptions subs)
        Returns the view of a given subscriptions map to be presented to a sending client. The result may be affected by any message restrictions in force for the client.
        Parameters:
        client - client to view subscriptions
        subs - basic subscription map
        Returns:
        view of subscription map for client