PLASTIC - PLatform for AStronomy Tool Inter Communication: Architecture and Protocol Spec Version 0.2

Other Versions - latest is 0.4

Under (re)construction.

Architecture Overview

PLASTIC consists of a �hub� application running on the user's machine that routes messages between applications. It is a simple messaging system based on the Publish-Subscribe pattern.

PLASTIC�compatible tools should implement the PlasticListener interface and support one or more of the protocols described below.

As shown in the above diagram, PLASTIC-aware tools implement the method in the PlasticListener interface in their protocol of choice (see below). To communicate with other PLASTIC-aware tools they register with a local server application which implements the PlasticHub interface.

Many of the aspects of how tools implement PLASTIC are deliberately left unspecified since they are considered to be the responsibility of the tool writers. For example, PLASTIC does not specify how a tool should connect to the PLASTIC Hub, whether it should be automatic on startup, or whether it should be user initiated. Similarly, it is up to the tool whether or not to transmit messages to the hub, or act on them in return. The interface is also minimalist, in that rather than fixing the methods a tool has to implement, it simply specifies an �perform� method which asks the tool to act on a message, leaving it up to tool writers to agree on messages of mutual interest. This will allow the benefits of PLASTIC to grow over time as tool writers find new ways of interoperating. However, it could also lead to fragmentation as each tool defines its own unique set of messages. Therefore we provide at the outset a small number of basic messages that we expect all tools will support (if appropriate), and ask that the definition of new messages will take place through the PLASTIC forum.

Choice of communication protocol

Tools communicate with a Plastic Hub by one of two protocols: java-rmi for Java clients, and xml-rpc for everyone else (cf the Astro Client Runtime). Other protocols such as CORBA may be added in the future if there is demand.

The following sections describe the Plastic interface in a generic UML-like format. For translations into your language of choice please see the appendix.

Registering an application with a Plastic hub

All applications that wish to interact with other PLASTIC-compliant applications need to register with a Plastic Hub. The method to register depends on the protocol that the client wishes the Hub to use. For xml-rpc clients the method is:

registerXMLRPC(in name : String, in supportedMessages : URI[], in callBack : URL) : URI

This method returns a unique hub-assigned id for the application which is used for subsequent operations. The form of the id is dependent on the implementation of the hub, but should be globally unique and in the form of a URI.

The name parameter is a human-readable string containing the tool's name. It need not be unique (that is, several instances of the same tool may register with the same name).

The supportedMessages parameter is an array of URIs, each being the identifier of a message that the application wishes to register for (see below). If this array is of zero length, then the application is registering to be informed of all messages, although it is under no obligation to act on them.

The callBack parameter is the URL of the PLASTIC-compliant application's xml-rpc server on which it will listen for messages.

Java applications also have the option of using Java-RMI for communication, and there is a version of the register method specifically for them:

public URI registerRMI(String name, URI[] supportedMessages, org.votech.plastic.PlasticListener caller);

Certain applications such as scripting environments may wish to use Plastic, but are unable of receiving messages themselves. These applications should register with:

registerNoCallBack(in name : String) : URI

A well behaved application will unregister from the hub before it closes:

unregister(in id : URI) : void

where id is the hub-supplied unique Id of the application.

Supported Messages

Not all applications will understand all messages. For example, it doesn't make sense for Topcat to act on a message requiring it to load an image. Therefore, an application may declare at registration which messages it is interested in. A message is described by a unique URI. This should have the format of an IVORN/IVOID to allow the message to be registered in an IVOA registry. Although at the moment this is not required for PLASTIC to work, it may be useful in the future, for example if the user wishes to search a registry for tools that understand a certain message. Some sample messages are given in part 2.

Sending a message to other tools via the PLASTIC hub

To send a message to a Plastic Hub for multiplexing to other registered tools, a tool executes

request(in sender : URI,in message : URI,in args : Object[]) : Map

on the hub. sender is the id of the tool sending the command, message the unique URI identifying the message (see part 2) and args an array of arguments. These argument types are restricted to the simple types supported by xml-rpc (see http://www.xmlrpc.com/spec). This method will multiplex the message to all tools that are registered as interested in it. To restrict the tools to which the message is sent use

requestToSubset(in sender : URI,in message : URI,in args : Object[],in recipientIds : URI[]) : Map

The methods return a Map (aka Dictionary, Struct), with one array element for each tool that replies. The Map is simply a collection of (String, Object) tuples associating a tool id to a returned object.

Good behaviour note:

Messages that return values should complete quickly, since the hub will not be able to return control to the sender until all recipients have completed processing the message. If a message requires a significant amount of processing time before it can return a result then the recipients of the message return a void and instead send a message back to the original sender with their results.

For many messages, there is no need for the sender to wait for a response. However, only the sender and recipients know this, since the meaning of the message is opaque to the hub and it has no way of knowing that it can return control to the sender immediately. For this reason senders can also send messages using the following equivalent methods which return without waiting for recipients to respond:

requestAsynch(in sender : URI,in message : URI, in args : Object[]) : void

requestToSubsetAsynch(in sender : URI,in message : URI,in args : Object[],in recipientIds : URI[]) : void

If any of the recipients does return a result, this is discarded by the hub when these methods are used.

Example

If a sender instructs receivers to load a VOTable it could take the receivers a significant time to load it - particularly if it's being loaded over the network. We don't want the sender blocked for the whole time so it should use executeAsynch to send this message. If the sender is interested in knowing when the tools have completed loading the table then it should listen for a tableLoadedEvent message which will be sent by the recipients in return.

Obtaining a list of tools currently registered with the hub

This could be useful for populating menus etc. Call the following method on the hub:

getRegisteredIds() : URI[]

Obtaining the hub's internal ID

A Plastic hub has two roles: as a transparent router of operations it does not understand, and as an application it its own right. Occasionally, a tool may wish to send a message to the hub itself, for example to query the PLASTIC version it supports. The id of the Plastic hub itself can be obtained with

getHubId() : URI

Receiving message from the Hub: Plasticizing your tools

PLASTIC-compatible tools need to implement

perform(in sender : URI ,in message : URI ,in args : Object[]) : Object

and support at least one of the PLASTIC protocols described above. The input and output args can be any xml-rpc type.

Error Handling

Both xml-rpc and Java RMI support Faults/Exceptions. These will be used soley for exceptions between a sender and a hub. Exceptions that arise in recipients or between the hub and a recipient can also be signalled to the hub using a Java Exception or xml-rpc Fault (as appropriate), but the hub will not pass them on to the sender. The hub will return to the sender the results from the applications that did execute normally (if any). If a sender must be notified of an exception, then the exception should be sent as a message (see #PartTwo).

Part 2

PlasticMessagesProposal

Appendix

Locating and connecting to a Plastic Hub

To make the initial connection to the Hub, the client must first obtain the port on the local machine on which the Plastic hub is listening. When and only when the Hub is running the following text file will exist:

~/.plastic

where ~ is the user's home directory. This text file will contain the following text:

#Some comments

plastic.rmi.port=1234

plastic.xmlrpc.url=http://localhost:8001/576514c3145e6e34/xmlrpc

Example PLASTIC methods in different languages

Consider the hub's request method and the client's perform method

request(in sender : URI, in message: URI, in args : Object[]) : Map

perform(in sender : URI ,in message : URI ,in args : Object[]) : Object

The equivalents in different languages are

Java-RMI

public java.util.Map org.votech.plastic.PlasticHubListener.request(java.net.URI sender, java.net.URI message, java.util.List args)

public Object org.votech.plastic.PlasticListener.perform(java.net.URI sender, java.net.URI message, java.util.List args)

The Map maps URI to Object

xml-rpc

In xml-rpc types such as URI and URL are represented as String s , arrays are xml-rpc arrays, and a Map is a Struct.

xml-rpc

<methodCall>
   <methodName>plastic.hub.request</methodName>
   <params>
      <param>
         <value>ivo://foo.bar/sender</value>
      </param>
      <param>
         <value>ivo://votech.org/message</value>
      </param>
      <param>
         <array><data>
           <value>arg1</value>
           <value><int>12</int></value>
         </data></array>
      </param>
   </params>
</methodCall>

which might return:

<methodResponse>
   <params>
      <param>
         <struct>
            <member>
               <name>ivo://votech.org/tool1</name>
               <value>tool1 result</value>
            </member>
            <member>
               <name>ivo://foo.bar/tool2</name>
               <value><i4>139</i4></value>
            </member>
         </struct>
      </param>
   </params>
</methodResponse>

(do same for perform)

Java & Apache xml-rpc

Some Java clients may prefer to use xml-rpc rather than rmi. If they are using the Apache xml-rpc libraries the equivalent methods are:

fix this...use correct method names

java.util.Hashtable org.votech.plastic.PlasticHubListener.request(String sender, String message, java.util.Vector args);

Object org.votech.plastic.PlasticListener.perform(String sender, String message, java.util.Vector args)

Python

server=xmlrpclib.Server(localurl);

results=server.plastic.hub.request("ivo://votech.org/sender", "ivo://votech.org/yourmessage, [arg1, arg2, ...])

where results will be a Python dict.

C++ - TBD

-- JohnTaylor - 6 Jan 2006

DsSixPlasticInterfaceTempHome