AstroGrid

Document Actions

Ten Minute Tutorial

It's quite straightforward to connect to the Astro Runtime and start calling functions. This tutorial covers that first step.
Astro Runtime Schematic Astro Runtime Schematic
 

Architecture

The architecture of a system that uses AR to access VO services is shown in the figure above.  The left of the figure lists the different kinds of client that might use the AR (there's some overlap between application and scripting).

Clients call the AR using one of four possible access methods (green circles). The feature set provided by each access method is identical between access methods, wherever possible. (Some technical limitations apply to XMLRPC, and in particular to REST)

No matter what the access method, the same implemementation of the function is called.

Related functions are gathered into components. Related components are in turn gathered into modules. The modules present in the AR are shown in the figure as blue boxes. They are

ivoa
Access DAL services and query resource registries.
astrogrid
Access AstroGrid services: Myspace file storage, CEA task servers, DSA asynchronous catalog query, JES Workflow engine.
cds
Access CDS services: e.g. Vizier, Simbad name resolver
plastic
Exchange messages with other client-side applications.
util
Helper components for working with datatypes. Provides basic access to the STIL table library.
dialogs
Gui dialogs that can be used to prompt for input, and larger UI components (e.g. myspace browser)
system
configuration and internal services

Installation

As can be seen from the figure, you need to have a running AR service before applications can connect to it. AR is available as as stand-alone application, and is also bundled with the AstroGrid Workbench. Either can be downloaded from www.astrogrid.org/desktop

Choosing an Access Method

The access method you choose to call the AR depends on a few factors:

  • If you're coding in Java, you've the most choice. Choose RMI if you want all the features and type safety of the API; XMLRPC if you prefer something more lightweight, but less typed; Choose Direct if you plan to compile and link directly to AR
  • If you're coding in another language, XMLRPC is the best choice. Most popular languages provide an XMLRPC client library - if your chosen language lacks once, fall back to REST (or consider writing the xmlrpc client yourself)

We'll now describe each access method in turn - feel free to skip the appropriate section.

RMI

You need to add the jars in the rmi directory to your application's classpath. These are:

Use the following code to access the ACR: 

import org.astrogrid.acr.builtin.ACR; 
import org.astrogrid.acr.Finder; 

Finder f = new Finder();
ACR acr = f.find();

Finder takes care of connecting to the AR service. If it can't find a running service, it'll attempt to create one - either in-process (if the AR implementation libraries are on the classpath) or externally (via webstart, or prompting the user).

Finder returns an instance of ACR . From this you can retreive components (services) from the AR, which you can then call functions on. The components of the AR are arranged into modules, which correspond to packages in the javadoc. For example, to write some data to myspace, first retreive the org.astrogrid.acr.astrogrid.Myspace component, and then call the methods on it. e.g. 

import org.astrogrid.acr.astrogrid.Myspace; 
import java.net.URI;
 ... 
Myspace ms = (Myspace)acr.getService(Myspace.class); 
URI file =	new URI("#votable/results.txt"); 
String data= "some data"; 
if (!ms.exists(file)) { 
 	ms.createFile(file);
} 
ms.write(file, data);
See the javadoc of individual components for examples of their use. Extensive examples of calling AR from Java over RMI are present in the examples/java directory.

The RMI access method can also be used from other JVM-based programming languages, provided the jars are added to the classpath. See the examples/recipes/groovy directory for an example of calling the AR interface from Groovy ( http://groovy.codehaus.org/ ).

Direct

Very similar to RMI, but running in the same JVM as the AR. You need all the jars of the AR implementation on your classpath (available as a zip from the download site). Then access the AR in the same way as for RMI - create a Finder , and from this get an ACR object. If there's no ACR already running and the implementation classes are on the classpath, an in-process acr will be created. There's no difference to the programming api.

XMLRPC

There's XMLRPC libraries for a range of languages. See http://www.xmlrpc.com/ for a list. For convenience, the libraries required for XMLRPC in java are available in the xmlrpc directory.

The details of how to create and configure the xmlrpc client varies between language and library. The general method of connecting to the AR is the same however (and is similar to the procedure to connect to any PLASTIC hub):

  • a running AR will write a file in the user's home directory called .astrogrid-desktop . This contains a single line like 
    http://localhost:8001/a6d4c15eaaefe3c/
    This is the address of the ACR's internal webserver - the file changes each time the ACR is run, and is deleted when the ACR exits.
  • In your program, read the line from the file, and append xmlrpc to it. This gives the URL of the XMLRPC server
  • Pass this url to your xmlrpc client library to configure it
  • Functions of the api can be called using the form module-name.component-name.function-name . The Javadoc for each component states the module-name and component-name to use. Function names are the same as in the Javadoc.
  • If preferred, refer to the API docs for XMLRPC. This is generated automatically from the definitive Javadoc, but have the component and method names rewritten to conform to the format used in the XMLRPC access method.
  • Documentation for individual functions may contain further notes about how to call the function via xmlrpc. The most significant change is that it's mostly strings that are passed as inputs and outputs - the javadoc should note when this is not the case.
Make sure the AR is running before you attempt to start your program -unlike RMI or Direct, this method does not automatically start an AR if not already present.

Use the standard xmlrpc methods system.listMethods , system.methodHelp , and system.methodSignature to get information on methods at runtime. This is the same information as is present in the documentation - however it isn't as nicely formatted.

Python Example

Here's am example that uses the XMLRPC access method, from Python. The code performs the same AR operations as the previous RMI example.

Python comes bundled with an xmlrpc library, so nothing additional needs to be installed. 

import xmlrpclib as x 
import os

#boilerplate - read	the info file and configure the xmlrpc server 
prefix = file(os.path.expanduser("~/.astrogrid-desktop")).next().rstrip()
acr = x.Server(prefix + "xmlrpc") 

#now create some parameters and call some AR methods
file ="#votable/results.txt" 
data = "some data" 
if not acr.astrogrid.myspace.exists(file) :
	acr.astrogrid.myspace.createFile(file)
acr.astrogrid.myspace.write(file, data)
There are plenty more examples of using python and XMLRPC to work with AR in the examples/commandline and examples/python-worflows directories.

Other languages

See the examples/recipes directory for examples of connecting to AR using XMLRPC in Perl, C++ and other languages.

REST

If your language of choice lacks an XMLRPC library, but has a way to fetch a HTTP url, the REST-like access method can be used as a fallback. Starting from the URL given in the .astrogrid-desktop file (or by pressing the 'Advanced > AR Web interface Interface' button in the user interface), there's a series of web pages that can be explored in a web browser, or called programatically.

The pages are arranged into a hierarchy of module : component : function : result-type . Modules, components and function were introduced previously. The result-type is a choice between

  • html - which will return an html-formatted result (possibly styling xml into html)
  • plain - which will return a plain-text result

When exploring in a web browser, on function pages there are forms to enter parameters and execute the function. The equivalent URL to use to call the function programattically is given at the foot of these pages. The same can be done programatically by constructing URLs of the form 

server-context/module/component/function/result-type?parameters
For example, the following URL retreives information about the job jes:galahad.star.le.ac.uk/143.210.36.238/noelwinstanley@uk.ac.le.star/1441 , displaying the result as plain text. 
http://localhost:8001/a6d4c15eaaefe3c/astrogrid/jobs/getJobInformation/plain?jobURN=jes:galahad.star.le.ac.uk/143.210.36.238/noelwinstanley@uk.ac.le.star/1441
The parameter names to use are documented on the function pages. It is also possible to perform a HTTP-POST of the parameters - this is better suited when the parameters are large (e.g documents)

See the examples/recipes/sh directory for examples of using the REST interface from bash scripts - using the curl commandline tool to fetch the URL.

The Next Step

This tutorial showed how to connect to the Astro Runtime and call some functions.

The next step is to explore the functions of the different parts of the AR API (and the VO services behind them), and begin to understand how they interrelate and what can be done with each of them. Download the AR Development Kit, and examine some examples to understand how different components can cooperate together, while referring to the API documentation. Where possible, the documentation for each component contains references to the relevant standards, plus simple examples of how to use the functions.