uk.ac.starlink.plastic
Class HubManager

java.lang.Object
  extended byuk.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:

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
HubManager(String appName, URI[] supportedMessages)
          Constructs a new manager.
 
Method Summary
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 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.


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.

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


Copyright © 2006 \\ CLRC: Central Laboratory of the Research Councils. All Rights Reserved.