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 and 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 and Description
BasicHubService(Random random) Constructor.

Method Summary

Modifier and Type	Method and 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 Detail

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