Package org.astrogrid.samp.hub

# Class BasicHubService

java.lang.Object
org.astrogrid.samp.hub.BasicHubService

All Implemented Interfaces:
  `HubService`

Direct Known Subclasses:
  `GuiHubService`

public class BasicHubService extends Object implements HubService
HubService implementation.

Since:
  15 Jul 2008
Author:
  Mark Taylor

## Field Summary

Fields
Modifier and Type
Field
Description
`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.

## Constructor Summary

Constructors
Constructor
Description
`BasicHubService(Random random)`
Constructor.

## Method Summary

Modifier and Type
Method
Description
`protected String`
`call(HubClient caller, String recipientId, String msgTag, Map message)`
Does the work for the `call` method of connections registered with this service.
`protected Map`
`callAll(HubClient caller, String msgTag, Map message)`
Does the work for the `call` method of connections registered with this service.
`protected Response`
`callAndWait(HubClient caller, String recipientId, Map message, int timeout)`
Does the work for the `callAndWait` method of connections registered with this service.
`protected HubClient`
`createClient(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, Map meta)`
Does the work for the `declareMetadata` method of connections registered with this service.
`protected void`
`declareSubscriptions(HubClient caller, Map subscriptions)`
Does the work for the `declareSubscriptions` method of connections registered with this service.
`void`
`disconnect(String clientId, 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`.
`ClientSet`
`getClientSet()`
Returns the structure which keeps track of registered clients.
`Comparator`
`getIdComparator()`
Returns a comparator which will order client IDs.
`protected Metadata`
`getMetadata(HubClient caller, String clientId)`
Does the work for the `getMetadata` method of connections registered with this service.
`protected String[]`
`getRegisteredClients(HubClient caller)`
Does the work for the `getRegisteredClients` method of connections registered with this service.
`HubConnection`
`getServiceConnection()`
Returns the HubConnection object used by the hub itself to send and receive messages.
`protected Map`
`getSubscribedClients(HubClient caller, String mtype)`
Does the work for the `getSubscribedClients` method of connections registered with this service.
`protected Subscriptions`
`getSubscriptions(HubClient caller, String clientId)`
Does the work for the `getSubscriptions` method of connections registered with this service.
`boolean`
`isHubRunning()`
Indicates whether this hub service is currently open for operations.
`protected void`
`notify(HubClient caller, String recipientId, Map message)`
Does the work for the `notify` method of connections registered with this service.
`protected List`
`notifyAll(HubClient caller, 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, String msgIdStr, 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 Details

### 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 Details

### BasicHubService

public BasicHubService(Random random)
Constructor.

Parameters:
  `random` - random number generator used for message tags etc

## Method Details

### 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(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 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, 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, 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, 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, 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 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 Map getSubscribedClients(HubClient caller, 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, String recipientId, 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 String call(HubClient caller, String recipientId, String msgTag, 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 List notifyAll(HubClient caller, 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 Map callAll(HubClient caller, String msgTag, 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, String msgIdStr, 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, String recipientId, 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(String clientId, 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

### 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`