|
|||||||
| PREV NEXT | FRAMES NO FRAMES | ||||||
See:
Description
| Connecting to the Astro Runtime | |
|---|---|
| org.astrogrid.acr | Connect to the Astro Runtime |
| org.astrogrid.acr.builtin | Access components of the Astro Runtime |
| Access to Virtual Observatory services | |
|---|---|
| org.astrogrid.acr.astrogrid | Astrogrid Webservices |
| org.astrogrid.acr.cds | CDS Webservices |
| org.astrogrid.acr.file | Access to remote filesystems |
| org.astrogrid.acr.ivoa | IVOA Webservices |
| org.astrogrid.acr.ivoa.resource | Datastructures for IVOA Registry Resources |
| User Interface and Desktop Integration | |
|---|---|
| org.astrogrid.acr.dialogs | Prompt the user for input |
| org.astrogrid.acr.ui | Open GUI windows |
| org.votech.plastic | Exchange data with other desktop applications |
| Utilities | |
|---|---|
| org.astrogrid.acr.system | Miscellaneous system components |
| org.astrogrid.acr.util | Table manipulation utilities |
The Astro Runtime is middleware that makes it simple to use Virtual Observatory services. This document describes the Astro Runtime, and how to use it's API.
Info:
It is possible to start VODesktop in 'windowless' mode - where no user interface is displayed - by passing it the -headless
commandline option. This makes it suitable for deploying on a headless server, or for running in the background on the user's desktop if only the
AstroRuntime functionality is required.
The left
of the figure lists the different categories of client that might use the AR
(there's some overlap between the categories).
The AR (yellow box) runs as a separate process, typically on the user's desktop, and can
accept connections from many clients.
Clients connect to the AR using one of four possible access methods
(green circles).
Once connected, clients can call functions of the AR.
Related functions are gathered into components. Related
components are in turn gathered into modules. The modules available
in the AR are shown in the figure as blue boxes, and are summarized below:
ivoaastrogridcdsorg.astrogrid.acr.filedialogs & uiutilsystemplastic| Language | Access method |
|---|---|
| Python | XML-RPC |
| Perl | XML-RPC |
| Java | XML-RPC, RMI or Direct |
| C/C++ | XML-RPC or C Binding |
| Other Languages | XML-RPC, C Binding, or HTTP |
.astrogrid-desktop in the user's home directory.
The file contains a single line, something like
http://localhost:8001/a6d4c15eaaefe3c/
.astrogrid-desktop file, and append xmlrpc
to it. This gives the URL of the AR's XMLRPC server - something like
http://localhost:8001/a6d4c15eaaefe3c/xmlrpc
module-name.component-name.function-name. The documentation for each
component states the module-name and component-name to use under (in the 'Service Name' subsection). Function names are case-sensitive.
When calling an AR function using XML-RPC, the parameter and return types will be simpler than what is documented. Most
parameters can be passed as plain strings. Results are either strings, or, where the result is an object, an XML-RPC structure.
The documentation contains many examples of calling functions via XML-RPC, and notes when something different will be returned.
Warning:
Make sure the AR is running before you execute your program, otherwise
the .astrogrid-desktop file won't exist, and your program will fail.
Info:
There's a library called AstroGrid Python that wraps some of the most commonly-used AR functionality in a higher-level, more 'pythonic' style of library. Python-using science scripters might wish to investigate this alternative.
.astrogrid-desktop file, append xmlrpc, and then
create an XML-RPC client (confusingly by calling the function Server). The result is an XML-RPC client, called ar
from xmlrpclib import Server
from os.path import expanduser
ar = Server(file(expanduser('~/.astrogrid-desktop')).next().strip() +'xmlrpc')
module-name, component-name and function-name to the ar object. For example, to call
Sesame.resolve() do this:
pos = ar.cds.sesame.resolve('m32')
Sesame.resolve() is documented to return a object of type SesamePositionBean. However, as this function
has been called over XML-RPC, an XML-RPC struct is returned instead, which appears as a Python dict. This dict contains
a key-value entry for each field of the SesamePositionBean. These can be accessed as follows:
#project some items from the dictionary print pos['ra'],pos['dec'] #list all keys in the dictionary print pos.keys()
.astrogrid-desktop
file, append xmlrpc and then use the resulting URL to create a new XML-RPC client (called ar).
use File::Spec;
use RPC::XML::Client;
open(F, File::Spec->catfile( "$ENV{HOME}", ".astrogrid-desktop" ));
my $prefix = <F>;
close( F );
chomp( $prefix );
my $ar = RPC::XML::Client->new($prefix . "xmlrpc");
$ar->simple_request() method.
The first parameter is the full name of the AR function, in the form module-name.component-name.function-name.
Further parameters are the parameters to pass to the AR function. For example, to call
Sesame.resolve() do this:
my $pos = $ar->simple_request('cds.sesame.resolve','m32');
Sesame.resolve() is documented to return a object of type SesamePositionBean. However, as this function
has been called over XML-RPC, an XML-RPC struct is returned instead, which appears as a Perl hash. This hash contains
a key-value entry for each field of the SesamePositionBean. These can be accessed as follows:
print "$pos->{ra}, $pos->{dec}\n";
rmi-lib
directory must be added to your application's classpath. These are:
import org.astrogrid.acr.builtin.ACR; import org.astrogrid.acr.Finder; Finder f = new Finder(); ACR ar = f.find();
Finder takes care of connecting to the AstroRuntime. If it can't find a running
service, it'll attempt to create one - either in-process (if the AstroRuntime
implementation libraries are on the classpath) or externally (by prompting the user).
Finder returns an instance of ACR (which really should be called AR).
From this class you
can retrieve components of the AstroRuntime, which can then be treated as conventional objects, and
their methods called as needed.
Note:
Components can be retrieved from ACR either by giving their interface class, or by giving the component name in the form
modulename.componentname. The first alternative is more strongly typed, while the second method is
more convenient when programming in alternative JVM languages such as Jython.
Sesame component by it's interface class,
and then uses this component to resolve an object name to a position.
import org.astrogrid.acr.cds.Sesame;
import org.astrogrid.acr.cds.SesamePositionBean;
//retrieve a component from AR
Sesame sesame = (Sesame)ar.getService(Sesame.class);
// use that component
SesamePositionBean pos = sesame.resolve("m32");
System.out.println(pos.getRa() + ", " + pos.getDec());
Finder is used, but it will return a direct reference to the runtime,
rather than a RMI proxy. This difference is not observable from the client program.
A client program that connects to the AstroRuntime in direct mode may access
additional APIs, and implement various extension points for AstroRuntime and VODesktop.
This is covered in separate documentation (in progress).
~/.astrogrid-desktop (and deletes this file when it halts).
The file contains a URL, something like
http://localhost:8001/a6d4c15eaaefe3c/
Cone.constructQuery()
displays:
base-url/ivoa/cone/constructQuery/[ html|plain ]?service=val&ra=val&dec=val&sr=val
base-url by the URL read from ~/.astrogrid-desktop, selecting either html or plain,
and then filling in the parameter values (val) gives a URL which can then be GET to call this AstroRuntime function.
Note:
It is also possible to perform a POST of the parameters - this is better suited when the parameters are large or need escaping.
sh) and curl (a standard utility
for retrieving URLs). The script first reads the base URL from the ~/.astrogrid-desktop file. The Cone.constructQuery()
function is then called using curl. Each parameter is provided by a separate -d flag, while
the -s flag suppresses output to the console.
The result of a call to constructQuery() is a query URL that can be used to perform a cone search on the specified service.
The final line uses curl to execute the query URL (there is an AstroRuntime function that will do this, but curl does just as
well here).
#find how to connect to AR
BASEURL=`cat ~/.astrogrid-desktop`
#Perform Cone search on
QUERY=`curl -s -d "service=ivo://nasa.heasarc/rc3" \
-d "ra=25.429167" \
-d "dec=-89.334444" \
-d "sr=1.0" \
${BASEURL}ivoa/cone/constructQuery/plain `
curl -s $QUERY
|
|||||||
| PREV NEXT | FRAMES NO FRAMES | ||||||