uk.ac.starlink.plastic

Class HubManager

java.lang.Object

uk.ac.starlink.plastic.HubManager

All Implemented Interfaces:

PlasticListener

public abstract class HubManager
extends Object
implements PlasticListener

Class which keeps track of registering and unregistering with the PLASTIC hub on behalf of a listening application. If you want to behave as a plastic listener, call register(). If you want to stop listening, call unregister(). Either of these may be called more than once harmlessly. It is a good idea to call register immediately before sending a plastic message to ensure that the hub is up to date (it may be a different hub server than last time you looked). This class implements PlasticListener and deals with generic messages as well as unregistering from the hub on JVM shutdown etc. Concrete subclasses must implement doPerform(java.net.URI, java.net.URI, java.util.List) to provide any application-specific services.

The generic messages which are handled by this object directly are currently:

• ivo://votech.org/info/getName
• ivo://votech.org/test/echo
• ivo://votech.org/hub/HubStopping
• ivo://votech.org/hub/event/ApplicationRegistered
• ivo://votech.org/hub/event/ApplicationUnregistered

Actions are also provided for registering/unregistering and starting a hub, ready for use in a GUI.

Since:

15 Feb 2006

Author:

Mark Taylor

Field Summary

Fields inherited from interface org.votech.plastic.PlasticListener

CURRENT_VERSION

Constructor Summary

Constructors

Constructor and Description
HubManager(String appName, URI[] supportedMessages) Constructs a new manager.

Method Summary

Modifier and Type	Method and Description
static boolean	checkArgs(List args, Class[] types) Utility method to check the types of a list of arguments.
static URI	createURI(String uri) Convenience method to turn a String into a URI without throwing any pesky checked exceptions.
abstract Object	doPerform(URI sender, URI message, List args) Does the work for processing an application-type hub message.
void	finalize() Finalizer makes an attempt to unregister from the hub, but won't wait around indefinitely for this to happen.
ListModel	getApplicationListModel() Returns a ListModel which keeps track of the currently registered applications.
PlasticHubListener	getHub() Returns the hub which this listener is registered with.
Action	getHubStartAction(boolean internal) Returns an action which will attempt to start up a PLASTIC hub.
Action	getHubWatchAction() Returns an action that can be used to post a window showing the state of the hub with which this object has a connection.
Action	getRegisterAction(boolean reg) Returns an action which will register/unregister with the PLASTIC hub.
URI	getRegisteredId() Returns the ID with which this listener is registered with the prevailing PLASTIC hub.
JToggleButton.ToggleButtonModel	getRegisterToggle() Returns a toggle button model which keeps track (as far as possible) of whether this listener is currently registered with a hub.
Object	perform(URI sender, URI message, List args) Implements the PlasticListener interface.
void	register() Attempts to ensure that this listener is registered with the prevailing PLASTIC hub.
void	setAutoRegister(int interval) Controls whether auto registration is used, and how often to attempt a connection if unregistered.
void	unregister() Makes an attempt to unregister from the hub if it's not already been done.

Methods inherited from class java.lang.Object

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

Constructor Detail

HubManager

public HubManager(String appName,
                  URI[] supportedMessages)

Constructs a new manager. The supportedMessages argument lists the additional messages for which support is provided. Some standard ones are supported by the HubManager itself. If this array is empty, then all messages will be delivered.

Parameters:

appName - the name of the application whose connections this object will manage

supportedMessages - URIs of PLASTIC messages supported directly by this implementation's doPerform(java.net.URI, java.net.URI, java.util.List) method

Method Detail

getRegisteredId

public URI getRegisteredId()

Returns the ID with which this listener is registered with the prevailing PLASTIC hub. If this listener is not currently registered, null will be returned. If you want to do your best to get a non-null ID, call register() first.

Returns:

plastic ID, or null

getHub

public PlasticHubListener getHub()

Returns the hub which this listener is registered with. If this listener is not currently registered, null will be returned. If you want to do your best to get a non-null hub, call register() first.

Returns:

hub, or null

register

public void register()
              throws IOException

Attempts to ensure that this listener is registered with the prevailing PLASTIC hub. If it's already registered, a check is made to see that the hub is alive, and if so nothing else is done. If it's not registered, an attempt is made to register. By the end of the call either this listener will be registered with a currently prevailing hub, or an exception will be thrown. It's therefore quite safe to call this method multiple times.

Throws:

IOException - if no registration can be achieved

unregister

public void unregister()

Makes an attempt to unregister from the hub if it's not already been done. If this method is called when the hub connection is already inactive, nothing happens. This method won't block indefinitely, even if the hub doesn't want to answer for some reason. This means that the unregister is not guaranteed to complete successfully - too bad, failing to unregister is not a serious crime.

setAutoRegister

public void setAutoRegister(int interval)

Controls whether auto registration is used, and how often to attempt a connection if unregistered. If interval>0, then a separate thread will remain active ensuring that this object is always registered with a hub, if a hub is present. It will check every interval milliseconds that there is a connection to the hub, and attempt to make one if there is not. If interval<=0 (the default), then no autoregistration is performed.

Parameters:

interval - autoregistration attempt interval in milliseconds, or <=0 to disable registration

getRegisterAction

public Action getRegisterAction(boolean reg)

Returns an action which will register/unregister with the PLASTIC hub. The enabled status of the returned action is kept up to date.

Parameters:

reg - true for register action, false for unregister action

Returns:

action

getHubStartAction

public Action getHubStartAction(boolean internal)

Returns an action which will attempt to start up a PLASTIC hub. Depending on the internal flag, the action may either start a hub in this JVM (in which case it will expire when the JVM does) or in a separate process. An attempt is made to keep the enabledness of this action up to date with current knowledge about whether the hub is running or not.

Parameters:

internal - true for an in-JVM hub, false for one in a new JVM

Returns:

hub start action

getHubWatchAction

public Action getHubWatchAction()

Returns an action that can be used to post a window showing the state of the hub with which this object has a connection.

Returns:

hub watcher window action

getRegisterToggle

public JToggleButton.ToggleButtonModel getRegisterToggle()

Returns a toggle button model which keeps track (as far as possible) of whether this listener is currently registered with a hub. Attempts to register/unregister can be performed by invoking its setSelected method.

getApplicationListModel

public ListModel getApplicationListModel()

Returns a ListModel which keeps track of the currently registered applications. Elements of the returned model are instances of ApplicationItem.

Returns:

list model of registered applications

perform

public Object perform(URI sender,
                      URI message,
                      List args)

Implements the PlasticListener interface.

Specified by:

perform in interface PlasticListener

Parameters:

sender - the ID of the originating application.

message - the URI representing the action.

args - any arguments to pass.

Returns:

any return value of the action.

See Also:

http://plastic.sourceforge.net

doPerform

public abstract Object doPerform(URI sender,
                                 URI message,
                                 List args)
                          throws IOException

Does the work for processing an application-type hub message. Concrete subclasses should implement this method to perform the application-specific listener behaviour for this listener. The sender argument may be any of the URIs which this object presented as the supported messages argument of the HubManager constructor.

Parameters:

sender - sender ID

message - message ID (determines the action required)

args - message argument list

Returns:

return value requested by message

Throws:

IOException

finalize

public void finalize()
              throws Throwable

Finalizer makes an attempt to unregister from the hub, but won't wait around indefinitely for this to happen.

Overrides:

finalize in class Object

Throws:

Throwable

createURI

public static URI createURI(String uri)

Convenience method to turn a String into a URI without throwing any pesky checked exceptions.

Parameters:

uri - URI text

Returns:

URI

Throws:

IllegalArgumentException - if uri doesn't look like a URI

checkArgs

public static boolean checkArgs(List args,
                                Class[] types)
                         throws IOException

Utility method to check the types of a list of arguments. If they look OK, true is returned, otherwise an IOException is thrown. The check is passed if there are the same number of actual arguments as required types or more (to permit future extension of message definitions), and each argument is either null or of the class in the correponding position in types, or a subclass of that.

Parameters:

args - actual argument list

types - classes you want to see represented in the initial elements of list

Throws:

IOException