uk.ac.starlink.plastic

Class MinimalHub

java.lang.Object

uk.ac.starlink.plastic.MinimalHub

All Implemented Interfaces:

org.apache.xmlrpc.XmlRpcHandler, PlasticHubListener

Direct Known Subclasses:

PlasticHub

public class MinimalHub
extends Object
implements PlasticHubListener, org.apache.xmlrpc.XmlRpcHandler

Minimal PLASTIC hub implementation. No fancy add-ons such as logging are provided. See PlasticHub for a more user-friendly implementation. This class is provided mainly to make it as clear as possible what the implementation of a hub involves.

Since:

18 Jul 2006

Author:

Mark Taylor

Field Summary

Fields inherited from interface org.votech.plastic.PlasticHubListener

PLASTIC_CONFIG_FILENAME, PLASTIC_RMI_PORT_KEY, PLASTIC_VERSION_KEY, PLASTIC_XMLRPC_URL_KEY

Constructor Summary

Constructors

Constructor and Description
MinimalHub(ServerSet servers) Constructs a new hub, given running server objects.

Method Summary

Modifier and Type	Method and Description
Object	execute(String method, Vector params) This method implements all the XML-RPC services offered by the hub.
void	finalize()
URI	getHubId() Get this hub's ID.
List	getMessageRegisteredIds(URI message) Get all the applications that support a particular message
String	getName(URI id) Get the name of this application, as used at registration.
List	getRegisteredIds() Get all the IDs of the currently registered applications.
List	getUnderstoodMessages(URI id) Get the messages understood by this application.
static void	main(String[] args) Main method.
List	pollForMessages(URI id) Not supported.
URI	registerNoCallBack(String name) Register this application with the hub, but don't send it any messages in return.
URI	registerPolling(String name, List supportedMessages) Not supported.
URI	registerRMI(String name, List supportedMessages, PlasticListener caller) A java-rmi version of registerXMLRPC
URI	registerXMLRPC(String name, List supportedMessages, URL callbackURL) Register an application with the hub.
Map	request(URI sender, URI message, List args) Send a message to all registered Plastic applications.
void	requestAsynch(URI sender, URI message, List args) Send a request to all registered Plastic apps, but don't wait for a response.
Map	requestToSubset(URI sender, URI message, List args, List recipientIds) Send a request to listed registered Plastic apps.
void	requestToSubsetAsynch(URI sender, URI message, List args, List recipientIds) Send a request to listed registered Plastic apps, but don't wait for a response.
void	stop() Shuts down this hub and tidies up.
void	unregister(URI id) Unregister the application from the hub.

Methods inherited from class java.lang.Object

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

Constructor Detail

MinimalHub

public MinimalHub(ServerSet servers)
           throws RemoteException

Constructs a new hub, given running server objects.

Parameters:

servers - object encapsulating listening servers

Throws:

RemoteException

Method Detail

getHubId

public URI getHubId()

Description copied from interface: PlasticHubListener

Get this hub's ID. The hub "registers with itself", and this method will give you its own Id.

Specified by:

getHubId in interface PlasticHubListener

Returns:

see above

registerRMI

public URI registerRMI(String name,
                       List supportedMessages,
                       PlasticListener caller)

Description copied from interface: PlasticHubListener

A java-rmi version of registerXMLRPC

Specified by:

registerRMI in interface PlasticHubListener

Parameters:

name - see registerRMI

caller - the PlasticListener that wishes to register

See Also:

for other parameters

registerXMLRPC

public URI registerXMLRPC(String name,
                          List supportedMessages,
                          URL callbackURL)

Description copied from interface: PlasticHubListener

Register an application with the hub. Each application that wishes to use the hub should register with it - the hub may not forward messages from applications whose ID it doesn't recognise. There are different register methods dependening on how (and whether) the application wishes to receive messages back from the hub.

Specified by:

registerXMLRPC in interface PlasticHubListener

Parameters:

name - An optional string with a short name describing the application. This may be added to the hub assigned ID, making it more human friendly.

supportedMessages - an array of messages (as URIs) the application is interested in. An empty List signifies "all".

callbackURL - the application's internal xmlrpc server URL. Used by the hub to send messages to the application.

Returns:

a hub-assigned ID

See Also:

http://plastic.sourceforge.net, PlasticHubListener.registerRMI(String, List, PlasticListener), PlasticHubListener.registerNoCallBack(String)

registerNoCallBack

public URI registerNoCallBack(String name)

Description copied from interface: PlasticHubListener

Register this application with the hub, but don't send it any messages in return. This is to allow uncallable applications like scripting environments to register. spec.

Specified by:

registerNoCallBack in interface PlasticHubListener

See Also:

for parameters

unregister

public void unregister(URI id)

Description copied from interface: PlasticHubListener

Unregister the application from the hub.

Specified by:

unregister in interface PlasticHubListener

Parameters:

id - the application to unregister

getRegisteredIds

public List getRegisteredIds()

Description copied from interface: PlasticHubListener

Get all the IDs of the currently registered applications.

Specified by:

getRegisteredIds in interface PlasticHubListener

Returns:

see above

getName

public String getName(URI id)

Description copied from interface: PlasticHubListener

Get the name of this application, as used at registration.

Specified by:

getName in interface PlasticHubListener

Parameters:

id - the plastic ID returned at registration

Returns:

The user friendly name

getUnderstoodMessages

public List getUnderstoodMessages(URI id)

Description copied from interface: PlasticHubListener

Get the messages understood by this application. As usual, an empty list means it will listen to all messages. Note that just because an application declares itself to be interested in a message, it's no guarantee it will act on it.

Specified by:

getUnderstoodMessages in interface PlasticHubListener

Parameters:

id - the plastic ID returned at registration

Returns:

A list of message URIs

getMessageRegisteredIds

public List getMessageRegisteredIds(URI message)

Description copied from interface: PlasticHubListener

Get all the applications that support a particular message

Specified by:

getMessageRegisteredIds in interface PlasticHubListener

Parameters:

message - the messageId you're interested in

Returns:

a list of plastic ids.

execute

public Object execute(String method,
                      Vector params)
               throws IOException,
                      URISyntaxException

This method implements all the XML-RPC services offered by the hub. It works out which hub method is intended and forwards the arguments to the relevant java method of this object. A certain amount of fiddling around is required to get the types right.

Specified by:

execute in interface org.apache.xmlrpc.XmlRpcHandler

Parameters:

method - XML-RPC method name, including the "plastic.hub" prefix

params - list of method arguments

Throws:

IOException

URISyntaxException

request

public Map request(URI sender,
                   URI message,
                   List args)

Description copied from interface: PlasticHubListener

Send a message to all registered Plastic applications.

Specified by:

request in interface PlasticHubListener

Parameters:

sender - the id of the originating tool - provided by the hub on registration. Note that the hub is at liberty to refused to forward requests that don't come from an ID that it has registered.

message - the message to send.

args - any arguments to pass with the message

Returns:

a Map of application ids to responses

requestToSubset

public Map requestToSubset(URI sender,
                           URI message,
                           List args,
                           List recipientIds)

Description copied from interface: PlasticHubListener

Send a request to listed registered Plastic apps. See request for details of the other parameters.

Specified by:

requestToSubset in interface PlasticHubListener

recipientIds - a list of target application ids (as URIs)

requestAsynch

public void requestAsynch(URI sender,
                          URI message,
                          List args)

Description copied from interface: PlasticHubListener

Send a request to all registered Plastic apps, but don't wait for a response. See request for details of parameters.

Specified by:

requestAsynch in interface PlasticHubListener

requestToSubsetAsynch

public void requestToSubsetAsynch(URI sender,
                                  URI message,
                                  List args,
                                  List recipientIds)

Description copied from interface: PlasticHubListener

Send a request to listed registered Plastic apps, but don't wait for a response.

Specified by:

requestToSubsetAsynch in interface PlasticHubListener

recipientIds - a List of target application ids (as URIs). See request for details of the other parameters.

registerPolling

public URI registerPolling(String name,
                           List supportedMessages)

Not supported.

Throws:

UnsupportedOperationException - always

pollForMessages

public List pollForMessages(URI id)

Not supported.

Throws:

UnsupportedOperationException - always

stop

public void stop()

Shuts down this hub and tidies up. Its main job is to send HUB_STOPPING messages to all registered listeners. May safely be called multiple times. It is good practice to call this method if the hub is no longer required to run. However, it will be called automatically if the hub is finalised or the JVM shuts down normally.

finalize

public void finalize()
              throws Throwable

Overrides:

finalize in class Object

Throws:

Throwable

main

public static void main(String[] args)
                 throws IOException,
                        RemoteException

Main method. Starts the hub. Nothing fancy. For more configurability and usability features, see PlasticHub.main(java.lang.String[]).

Throws:

IOException

RemoteException