org.votech.plastic
Interface PlasticHubListener

All Known Implementing Classes:

MinimalHub

public interface PlasticHubListener

The interface that a Plastic Hub should support. For information on what a Plastic Hub is, and why you'd want one, please see the URL below.

Since:

1.3

Version:

0.3

Author:

jdt@roe.ac.uk

See Also:

http://plastic.sourceforge.net

Field Summary

static String	PLASTIC_CONFIG_FILENAME The name of the file containing Plastic Hub config information (placed in ${user.home}).
static String	PLASTIC_RMI_PORT_KEY The key used to get the RMI port out of the Plastic Hub config file.
static String	PLASTIC_VERSION_KEY The key used to get the plastic.version out of the Plastic Hub config file.
static String	PLASTIC_XMLRPC_URL_KEY The key used to get the URL of the xml-rpc server out of the Plastic Hub config file.

Method Summary

URI	getHubId() Get this hub's ID.
List	getMessageRegisteredIds(URI message) Get all the applications that support a particular message
String	getName(URI plid) Get the name of this application, as used at registration.
List	getRegisteredIds() Get all the IDs of the currently registered applications.
List	getUnderstoodMessages(URI plid) Get the messages understood by this application.
URI	registerNoCallBack(String name) Register this application with the hub, but don't send it any messages in return.
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	unregister(URI id) Unregister the application from the hub.

Field Detail

PLASTIC_VERSION_KEY

public static final String PLASTIC_VERSION_KEY

The key used to get the plastic.version out of the Plastic Hub config file.

See Also:

PLASTIC_CONFIG_FILENAME, Constant Field Values

PLASTIC_XMLRPC_URL_KEY

public static final String PLASTIC_XMLRPC_URL_KEY

The key used to get the URL of the xml-rpc server out of the Plastic Hub config file.

See Also:

PLASTIC_CONFIG_FILENAME, Constant Field Values

PLASTIC_RMI_PORT_KEY

public static final String PLASTIC_RMI_PORT_KEY

The key used to get the RMI port out of the Plastic Hub config file.

See Also:

PLASTIC_CONFIG_FILENAME, Constant Field Values

PLASTIC_CONFIG_FILENAME

public static final String PLASTIC_CONFIG_FILENAME

The name of the file containing Plastic Hub config information (placed in ${user.home}). This file currently duplicates the information in the standard ACR config files, but is present to allow for future expansion and to be "organisation-neutral".

See Also:

Constant Field Values

Method Detail

getRegisteredIds

public List getRegisteredIds()

Get all the IDs of the currently registered applications.

Returns:

see above

getHubId

public URI getHubId()

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

Returns:

see above

getName

public String getName(URI plid)

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

Parameters:

plid - the plastic ID returned at registration

Returns:

The user friendly name

getUnderstoodMessages

public List getUnderstoodMessages(URI plid)

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.

Parameters:

plid - the plastic ID returned at registration

Returns:

A list of message URIs

getMessageRegisteredIds

public List getMessageRegisteredIds(URI message)

Get all the applications that support a particular message

Parameters:

message - the messageId you're interested in

Returns:

a list of plastic ids.

registerXMLRPC

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

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.

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, registerRMI(String, List, PlasticListener), registerNoCallBack(String)

registerRMI

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

A java-rmi version of registerXMLRPC

Parameters:

name - see registerRMI

caller - the PlasticListener that wishes to register

See Also:

for other parameters

Example

Suppose your application implements PlasticListener. Then you register with the hub to receive ALL messages using URI id = hub.registerRMI("MyApp", new ArrayList(),this);

registerNoCallBack

public URI registerNoCallBack(String name)

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.

See Also:

for parameters

unregister

public void unregister(URI id)

Unregister the application from the hub.

Parameters:

id - the application to unregister

request

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

Send a message to all registered Plastic applications.

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)

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

Parameters:

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

requestToSubsetAsynch

public 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.

Parameters:

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

requestAsynch

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

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