BasicHubService

java.lang.Object
- org.astrogrid.samp.hub.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

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`private static class`	`BasicHubService.ClientIdGenerator` Generates client public IDs.
`private static class`	`BasicHubService.MessageId` Encapsulates information about a MessageId.

Field Summary

Fields
Modifier and Type	Field and Description
`private ClientSet`	`clientSet_`
`private static char`	`ID_DELIMITER`
`private BasicHubService.ClientIdGenerator`	`idGen_`
`private static ProfileToken`	`INTERNAL_PROFILE`
`private KeyGenerator`	`keyGen_`
`private java.util.logging.Logger`	`logger_`
`static int`	`MAX_TIMEOUT` The maximum timeout for a synchronous call permitted in seconds.
`static int`	`MAX_WAITERS` The maximum number of concurrently pending synchronous calls.
`private HubClient`	`serviceClient_`
`private HubConnection`	`serviceClientConnection_`
`private boolean`	`shutdown_`
`private boolean`	`started_`
`private java.util.Map`	`waiterMap_`

Constructor Summary

Constructors
Constructor and Description

BasicHubService(java.util.Random random)
Constructor.

Constructors
Constructor and Description
`BasicHubService(java.util.Random random)` Constructor.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and 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
  - keyGen_
```
private final KeyGenerator keyGen_
```
  - idGen_
```
private final BasicHubService.ClientIdGenerator idGen_
```
  - waiterMap_
```
private final java.util.Map waiterMap_
```
  - clientSet_
```
private ClientSet clientSet_
```
  - serviceClient_
```
private HubClient serviceClient_
```
  - serviceClientConnection_
```
private HubConnection serviceClientConnection_
```
  - started_
```
private volatile boolean started_
```
  - shutdown_
```
private volatile boolean shutdown_
```
  - ID_DELIMITER
```
private static final char ID_DELIMITER
```
    See Also:
    
    Constant Field Values
  - 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
  - start
```
public void start()
```
    Description copied from interface: HubService
    
    Begin operation. The HubService.register(org.astrogrid.samp.hub.ProfileToken) method should not be called until the hub has been started.
    
    Specified by:
    
    start in interface HubService
  - 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
  - disconnectAll
```
public void disconnectAll(ProfileToken profileToken)
```
    Description copied from interface: HubService
    
    Forcibly terminates any connections created by a previous call of HubService.register(org.astrogrid.samp.hub.ProfileToken) with a particular profileToken. Any necessary hub events will be sent.
    
    Specified by:
    
    disconnectAll in interface HubService
    
    Parameters:
    
    profileToken - previous argument to register
  - 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
  - unregister
```
protected void unregister(HubClient caller)
                   throws SampException
```
    Does the work for the unregister method of conections registered with this service.
    
    Parameters:
    
    caller - client to unregister
    
    Throws:
    
    SampException
    
    See Also:
    
    HubConnection.unregister()
  - setCallable
```
protected void setCallable(HubClient caller,
                           CallableClient callable)
                    throws SampException
```
    Does the work for the setCallable method of connections registered with this service.
    
    Parameters:
    
    caller - client
    
    callable - callable object
    
    Throws:
    
    SampException
    
    See Also:
    
    HubConnection.setCallable(org.astrogrid.samp.client.CallableClient)
  - declareMetadata
```
protected void declareMetadata(HubClient caller,
                               java.util.Map meta)
                        throws SampException
```
    Does the work for the declareMetadata method of connections registered with this service.
    
    Parameters:
    
    caller - client
    
    meta - new metadata for client
    
    Throws:
    
    SampException
    
    See Also:
    
    HubConnection.declareMetadata(java.util.Map)
  - getMetadata
```
protected Metadata getMetadata(HubClient caller,
                               java.lang.String clientId)
                        throws SampException
```
    Does the work for the getMetadata method of connections registered with this service.
    
    Parameters:
    
    caller - calling client
    
    clientId - id of client being queried
    
    Returns:
    
    metadata for client
    
    Throws:
    
    SampException
    
    See Also:
    
    HubConnection.getMetadata(java.lang.String)
  - declareSubscriptions
```
protected void declareSubscriptions(HubClient caller,
                                    java.util.Map subscriptions)
                             throws SampException
```
    Does the work for the declareSubscriptions method of connections registered with this service.
    
    Parameters:
    
    caller - client
    
    subscriptions - new subscriptions for client
    
    Throws:
    
    SampException
    
    See Also:
    
    HubConnection.declareSubscriptions(java.util.Map)
  - getSubscriptions
```
protected Subscriptions getSubscriptions(HubClient caller,
                                         java.lang.String clientId)
                                  throws SampException
```
    Does the work for the getSubscriptions method of connections registered with this service.
    
    Parameters:
    
    caller - calling client
    
    clientId - id of client being queried
    
    Returns:
    
    subscriptions for client
    
    Throws:
    
    SampException
    
    See Also:
    
    HubConnection.getSubscriptions(java.lang.String)
  - 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)
  - notify
```
protected void notify(HubClient caller,
                      java.lang.String recipientId,
                      java.util.Map message)
               throws SampException
```
    Does the work for the notify method of connections registered with this service.
    
    Parameters:
    
    caller - calling client
    
    recipientId - public ID of client to receive message
    
    message - message
    
    Throws:
    
    SampException
    
    See Also:
    
    HubConnection.notify(java.lang.String, java.util.Map)
  - call
```
protected java.lang.String call(HubClient caller,
                                java.lang.String recipientId,
                                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
    
    recipientId - client ID of recipient
    
    msgTag - message tag
    
    message - message
    
    Returns:
    
    message ID
    
    Throws:
    
    SampException
    
    See Also:
    
    HubConnection.call(java.lang.String, java.lang.String, java.util.Map)
  - 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)
  - reply
```
protected void reply(HubClient caller,
                     java.lang.String msgIdStr,
                     java.util.Map resp)
              throws SampException
```
    Does the work for the reply method of connections registered with this service.
    
    Parameters:
    
    caller - calling client
    
    msgIdStr - message ID
    
    resp - response to forward
    
    Throws:
    
    SampException
    
    See Also:
    
    HubConnection.reply(java.lang.String, java.util.Map)
  - callAndWait
```
protected Response callAndWait(HubClient caller,
                               java.lang.String recipientId,
                               java.util.Map message,
                               int timeout)
                        throws SampException
```
    Does the work for the callAndWait method of connections registered with this service.
    
    Parameters:
    
    caller - calling client
    
    recipientId - client ID of recipient
    
    message - message
    
    timeout - timeout in seconds
    
    Returns:
    
    response response
    
    Throws:
    
    SampException
    
    See Also:
    
    HubConnection.callAndWait(java.lang.String, java.util.Map, int)
  - 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)
  - isHubRunning
```
public boolean isHubRunning()
```
    Description copied from interface: HubService
    
    Indicates whether this hub service is currently open for operations.
    
    Specified by:
    
    isHubRunning in interface HubService
    
    Returns:
    
    true iff called between HubService.start() and HubService.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
  - getSendError
```
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. Returns null if allowed, a useful message if not. Not intended for direct use, see canSend(org.astrogrid.samp.hub.HubClient, org.astrogrid.samp.hub.HubClient, java.lang.String) and checkSend(org.astrogrid.samp.hub.HubClient, org.astrogrid.samp.hub.HubClient, java.lang.String).
    
    Parameters:
    
    sender - sending client
    
    recipient - receiving client
    
    mtype - MType
    
    Returns:
    
    null if send OK, otherwise explanation message
  - 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

Class BasicHubService

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

keyGen_

idGen_

waiterMap_

clientSet_

serviceClient_

serviceClientConnection_

started_

shutdown_

ID_DELIMITER

logger_

INTERNAL_PROFILE

MAX_TIMEOUT

MAX_WAITERS

Constructor Detail

BasicHubService

Method Detail

start

createClientSet

createClient

createHubMessageHandlers

getIdComparator

getClientSet

register

disconnectAll

createConnection

unregister

setCallable

declareMetadata

getMetadata

declareSubscriptions

getSubscriptions

getRegisteredClients

getSubscribedClients

notify

call

notifyAll

callAll

reply

callAndWait

getServiceConnection

disconnect

disconnect

isHubRunning

shutdown

hubEvent

getClient

checkSend

canSend

getSendError

getSubscriptionsFor