uk.ac.starlink.plastic

Class PlasticUtils

java.lang.Object

uk.ac.starlink.plastic.PlasticUtils

public class PlasticUtils
extends Object

Utility methods for use with the PLASTIC tool interop protocol.

Since:

8 Feb 2006

Author:

Mark Taylor

See Also:

PLASTIC

Field Summary

Fields

Modifier and Type	Field and Description
static String	PLASTIC_FILE Location in the user's home directory of the PLASTIC rendezvous file.
static String	PLASTIC_VERSION Version of PLASTIC interface implemented.
static boolean	WARN_ABOUT_NOSUCHELEMENTEXCEPTIONS True if spurious java.util.NoSuchElementExceptions should be flagged.
static String	XMLRPC_PREFIX Prefix for XML-RPC "perform" method.

Method Summary

Modifier and Type	Method and Description
static URI	createURI(String uri) Convenience method to turn a String into a URI without throwing any pesky checked exceptions.
static org.apache.xmlrpc.XmlRpcClient	createXmlRpcClient(URL url) Factory method for obtaining a new XmlRpcClient.
static Icon	getBroadcastIcon() Returns an icon which conveys the idea of one-to-many transmission.
static PlasticHubListener	getLocalHub() Returns the PLASTIC hub running on the local host.
static Properties	getPlasticProperties() Returns the properties set which is stored in PLASTIC_FILE.
static String	getPlasticProperty(String key) Returns the value of a given property defined in the PLASTIC_FILE file.
static ApplicationItem[]	getRegisteredApplications(PlasticHubListener hub) Returns an array of ApplicationItem objects representing the applications currently registered with a given hub.
static Icon	getSendIcon() Returns an icon which conveys the idea of point-to-point transmission.
static URL	getXmlRpcUrl() Returns the URL to use for the hub's XML-RPC server.
static boolean	isHubRunning() Attempts to determine if a plastic hub is currently running.
static PlasticConnection	registerRMI(PlasticApplication app) Registers a PlasticApplication with the current hub using RMI-type communication.
static PlasticConnection	registerXMLRPC(PlasticApplication app) Registers a PlasticApplication with the current hub using XML-RPC type communication.
static void	singleRequestAsynch(String name, URI message, List args) Sends a single asynchronous message to the hub without registering for callback.
static void	startExternalHub(boolean gui) Attempts to start a hub running in an external process.
static Object	targetRequest(String name, URI message, List args, URI target) Gets the result of a request to a single registered application without registering for callback.
static Object	targetRequest(URI sender, URI message, List args, URI target) Gets the result of a request to a single registered application using an existing connection to the hub.
static void	waitToRegister(HubManager hubMan, int interval) Blocks until a successful registration has been achieved.

Methods inherited from class java.lang.Object

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

Field Detail

PLASTIC_FILE

public static final String PLASTIC_FILE

Location in the user's home directory of the PLASTIC rendezvous file.

See Also:

Constant Field Values

PLASTIC_VERSION

public static final String PLASTIC_VERSION

Version of PLASTIC interface implemented.

See Also:

Constant Field Values

XMLRPC_PREFIX

public static final String XMLRPC_PREFIX

Prefix for XML-RPC "perform" method.

WARN_ABOUT_NOSUCHELEMENTEXCEPTIONS

public static boolean WARN_ABOUT_NOSUCHELEMENTEXCEPTIONS

True if spurious java.util.NoSuchElementExceptions should be flagged. If future JVMs fix this bug, this should be set false or the code removed.

Method Detail

getLocalHub

public static PlasticHubListener getLocalHub()
                                      throws IOException

Returns the PLASTIC hub running on the local host. If it can't be done (for instance because no hub is running) a more or less informative IOException will be thrown.

Returns:

local PLASTIC hub

Throws:

IOException

getXmlRpcUrl

public static URL getXmlRpcUrl()
                        throws IOException

Returns the URL to use for the hub's XML-RPC server.

Returns:

URL for communicating with the current hub via XML-RPC

Throws:

IOException

isHubRunning

public static boolean isHubRunning()

Attempts to determine if a plastic hub is currently running. The results are not completely guaranteed to be true.

Returns:

true if a hub appears to be running, false if it doesn't

getPlasticProperties

public static Properties getPlasticProperties()
                                       throws IOException

Returns the properties set which is stored in PLASTIC_FILE.

Returns:

plastic properties

Throws:

IOException

getPlasticProperty

public static String getPlasticProperty(String key)
                                 throws IOException

Returns the value of a given property defined in the PLASTIC_FILE file. If it does not exist or has no value an IOException is thrown. Null will not be returned.

Parameters:

key - property key

Returns:

value property value

Throws:

IOException

registerRMI

public static PlasticConnection registerRMI(PlasticApplication app)
                                     throws IOException

Registers a PlasticApplication with the current hub using RMI-type communication.

Parameters:

app - application to register

Returns:

connection corresponding to app registered with the hub

Throws:

IOException - if the application could not register

registerXMLRPC

public static PlasticConnection registerXMLRPC(PlasticApplication app)
                                        throws IOException

Registers a PlasticApplication with the current hub using XML-RPC type communication.

Parameters:

app - application to register

Returns:

registered ID

Throws:

IOException

targetRequest

public static Object targetRequest(String name,
                                   URI message,
                                   List args,
                                   URI target)
                            throws IOException

Gets the result of a request to a single registered application without registering for callback.

Parameters:

name - application name

message - message ID

args - message arguments

target - application ID of a registered application to which the request is to be made

Returns:

the response from the target application

Throws:

IOException

targetRequest

public static Object targetRequest(URI sender,
                                   URI message,
                                   List args,
                                   URI target)
                            throws IOException

Gets the result of a request to a single registered application using an existing connection to the hub.

Parameters:

sender - application ID of registered listener from which the request will be made

message - message ID

args - message arguments

target - application ID of a registered application to which the request is to be made

Returns:

the response from the target application

Throws:

IOException

singleRequestAsynch

public static void singleRequestAsynch(String name,
                                       URI message,
                                       List args)
                                throws IOException

Sends a single asynchronous message to the hub without registering for callback.

Parameters:

name - application name

message - message ID

args - message arguments

Throws:

IOException

startExternalHub

public static void startExternalHub(boolean gui)
                             throws IOException

Attempts to start a hub running in an external process. There's no guarantee that this will be successful.

Parameters:

gui - true iff a window representing the hub is to be posted

Throws:

IOException

waitToRegister

public static void waitToRegister(HubManager hubMan,
                                  int interval)
                           throws InterruptedException

Blocks until a successful registration has been achieved. The most common reason for registration to fail is that the hub is not running. This method is therefore suitable to run (probably on a background thread) while waiting for a hub to start up.

Parameters:

hubMan - hub manager object

interval - number of milliseconds between registration attempts

Throws:

InterruptedException - if the thread is interrupted

getRegisteredApplications

public static ApplicationItem[] getRegisteredApplications(PlasticHubListener hub)

Returns an array of ApplicationItem objects representing the applications currently registered with a given hub.

Parameters:

hub - the hub

Returns:

apps registered with hub

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

createXmlRpcClient

public static org.apache.xmlrpc.XmlRpcClient createXmlRpcClient(URL url)

Factory method for obtaining a new XmlRpcClient. Consistent use of this permits switching between client implementations.

Parameters:

url - XML-RPC server URL

Returns:

new client for communication with url

getSendIcon

public static Icon getSendIcon()

Returns an icon which conveys the idea of point-to-point transmission.

Returns:

send icon

getBroadcastIcon

public static Icon getBroadcastIcon()

Returns an icon which conveys the idea of one-to-many transmission.

Returns:

broadcast icon