|
Science With the Virtual Observatory |
This exercise is a companion to the general presentation on the VOClient facility.
In this exercise we look at how to build a simple cone search client application with the VOClient package. VOClient implements the client side of the core VO services, e.g., registry and data access layer (DAL), providing a high level, easy to use API for for implementing data analysis applications which use remote VO resources. The same functionality is made available in multiple languages and application environments. In this exercise we will illustrate the use of VOClient to build a simple cone search client in Java and C.
Before beginning the exercise the NVOSS summer school environment should first be initialized. If you have not done so already, source the setup script appropriate for the shell you are using. No software other than the Ant build tool and a valid Java runtime environment is required for the Java version of the exercise. The C version additionally requires a C compiler and a Unix-style development environment including Make. On Windows an environment such as Cygwin is currently required (VOClient does not yet support native Windows).
In this exercise we will build a simple cone search client application in Java, using the dalclient Java library. Start by going to the dalclient source directory, which is part of the voclient package:
% cd $NVOSS_HOME/voclient/dalclient % ls build.xml ConeQuery.java QRAttribute.java siap3.java chart.java CVS QueryRecord.java siap4.java cone1.java DALConnection.java QueryResponse.java SiapConnection.java cone2.java DALQuery.java README SiapQuery.java cone3.java doc siap1.java ConeConnection.java package.html siap2.java
We start by building the dalclient package using Ant. The default action is to build the package, so no build target is required:
% ant
Buildfile: build.xml
init:
[mkdir] Created dir: /u1/nvoss/voclient/dalclient/classes
compile:
[echo] building
[javac] Compiling 17 source files to /u1/nvoss/voclient/dalclient/classes
[javac] Note: Some input files use unchecked or unsafe operations.
[javac] Note: Recompile with -Xlint:unchecked for details.
BUILD SUCCESSFUL
Total time: 5 seconds
This will build both the dalclient package and the sample applications, including several versions of cone search as well as some SIAP clients. These sample applications are also used for unit tests of dalclient. Arguments may be given on the command line to tell the application which service to run, the search region on the sky, and so forth. If run without any arguments, the sample programs use some built-in defaults to provide a simple unit test. Lets start by running the cone1 application, using the built-in defaults:
% java dalclient.cone1 # Query: http://chart.stsci.edu/GSCVO/GSC22VO.jsp?RA=12.0&DEC=12.0&SR=0.1 # returns 36 records containing 14 attributes each # --- Summary output --- id=N3233000:4280 ra=12.06964142 dec=11.93743758 class=Star id=N3233000:4440 ra=12.00563246 dec=11.98930768 class=Star id=N3233000:4396 ra=12.04016664 dec=11.97401059 class=Star id=N3233000:4174 ra=11.97466466 dec=11.90447683 class=Star id=N3233000:4182 ra=11.98926385 dec=11.90476293 class=Star id=N3233000:4321 ra=12.0236914 dec=11.95191743 class=Star
This performs a cone search query to a STScI guide star catalog service using the highest level "data model" interface provided by dalclient. If we look at the source code for cone1 we will see that the application accesses the returned data directly by UCD, without having to explicitly parse the returned VOTable:
// Summarize and print selected query results.
for (int i=0; i < qr.getRecordCount(); i++) {
QueryRecord r = qr.getRecord(i);
String s_id, s_ra, s_dec, s_class;
QRAttribute v;
s_id = ((v = r.getAttribute("ID_MAIN")) != null) ?
v.stringValue() : "";
s_ra = ((v = r.getAttribute("POS_EQ_RA_MAIN")) != null) ?
v.stringValue() : "";
s_dec = ((v = r.getAttribute("POS_EQ_DEC_MAIN")) != null) ?
v.stringValue() : "";
s_class = ((v = r.getAttribute("CLASS_OBJECT")) != null) ?
v.stringValue() : "";
System.out.println("id=" + s_id + "\tra=" + s_ra +
"\tdec=" + s_dec + "\tclass=" + s_class);
}
A variation on this is provided by the cone2 application, which is the same as cone1 except that the output is returned as CSV formatted text:
% java dalclient.cone2 # Query: http://chart.stsci.edu/GSCVO/GSC22VO.jsp?RA=12.0&DEC=12.0&SR=0.1 ID_MAIN,POS_EQ_RA_MAIN,POS_EQ_DEC_MAIN,ERROR,ERROR,TIME_EPOCH,PHOT_PHG_R,ERROR,PHOT_PHG_B,ERROR,PHOT_PHG_V,ERROR,PHOT_PHG_N,ERROR,CLASS_OBJECT,EXTENSION_RAD,PHYS_ECCENTRICITY,POS_POS-ANG,CODE_QUALITY N3233000:4280,12.06964142,11.93743758,0.430478,0.539791,1990.784302,16.29,0.43,17.74,0.42,99.9,99.9,99.9,99.0,Star,2.9,0.11,6.08,1011202 N3233000:4440,12.00563246,11.98930768,0.430478,0.539791,1990.784302,17.41,0.43,99.9,99.9,99.9,99.9,99.9,99.0,Star,2.63,0.17,155.63,1010202 N3233000:4396,12.04016664,11.97401059,0.430478,0.539791,1990.784302,16.5,0.43,18.69,0.42,99.9,99.9,99.9,99.0,Star,2.79,0.07,175.67,1011202 N3233000:4174,11.97466466,11.90447683,0.430478,0.539791,1990.784302,18.17,0.44,99.9,99.9,99.9,99.9,99.9,99.0,Star,2.31,0.17,121.79,1010202
Additional sample programs are provided in the dalclient source directory. Cone3 demonstrates how to get the cone search query response back from dalclient in VOTable format. A parallel set of applications demonstrate how to perform similar operations for SIAP.
Finally, we should clean up the dalclient directory, deleting the compiled Java classes and applications built earlier:
% ant clean Buildfile: build.xml clean: [delete] Deleting directory /u1/nvoss/voclient/dalclient/classes BUILD SUCCESSFUL Total time: 1 second
After this, we are back to where we started.
In this second exercise we will build C versions of the sample cone search client applications which we built using Java in exercise 1. Let's start by going to the root directory of VOClient:
% cd $NVOSS_HOME/voclient % ls acinclude.m4 build.xml configure.ac dalclient Makefile.am TODO aclocal.m4 clientapi console include Makefile.in VERSION autom4te.cache config COPYING INSTALL Makefile.man voclientd bootstrap configure CVS lib README wsdl
VOClient differs from the dalclient Java library in that it provides a daemon which runs locally on the client system, with a client-server API provided for each target language or environment. All client environments share the same VOClient daemon process, voclientd. Hence, to build and run a VOClient application we first need to ensure that we have built and installed the VOClient daemon. This is done with the Ant tool as follows:
% ant nvoss-install
Buildfile: build.xml
init:
[mkdir] Created dir: /u1/nvoss/voclient/classes
[mkdir] Created dir: /u1/nvoss/voclient/bin
[mkdir] Created dir: /u1/nvoss/voclient/doc
[mkdir] Created dir: /u1/nvoss/voclient/dist
compile:
[echo] Building Java code ....
[echo] Building dalclient classes ....
<...>
nvoss-install:
[echo] Install voclientd to /u1/nvoss/bin
[echo] Install voclient.jar to /u1/nvoss/java/lib
BUILD SUCCESSFUL
Total time: 7 seconds
As we can see from the build output above, this builds the VOClient daemon voclientd and installs in the NVOSS bin directory, and builds and installs the voclient.jar in the NVOSS java/lib directory. After this the VOclient daemon should be runnable. Building voclientd also has the side effect of building the VOClient client API library, which we will need later for our C version of the cone search client.
The next step is to go to the clientapi/examples subdirectory, where will find the C versions of the VOClient sample/unit test programs:
% cd clientapi/examples % ls cone1.c f77registry.f Makefile.in registry3.c siap4.c skybot.c cone2.c f77sesame.f Makefile.man resolver.c simple.c spptest.x cone3.c f77siap.f messier.cl resolver.java simple.java CVS f77skybot.f README siap1.c simple.pl datascope.cl Makefile registry1.c siap2.c simple.py f77cone.f Makefile.am registry2.c siap3.c simple.tcl
To build the sample cone1 application we can use the Make tool as follows (depending upon the platform and where things are installed, the output of the Make build may of course differ from that shown below):
% make cone1 gcc -g -Wall -DLinux -I/u1/nvoss/voclient/clientapi/examples -I../ -o cone1 cone1.c -L../ -lvoclient -lm -lc
Now we area ready to try out the new C version of the cone search application, but before we do so it is best to start up the VOclient daemon. In a second terminal window, source the NVOSS setup file if necessary, and start up voclientd as follows:
% voclientd starting on port: 6200
If voclientd is not explicitly started up, one will be started up automatically when the first VOClient-based application is run, but we prefer to start it up manually as shown in order to see the messages output by voclientd as it runs.
Now we ready to run the cone1 application we built earlier:
% cone1 Executing Query: http://chart.stsci.edu/GSCVO/GSC22VO.jsp?RA=12&DEC=12&SR=0.1 # returns 36 records containing 14 attributes each # # --- Summary output --- # # Attribute List: # ID_MAIN # POS_EQ_RA_MAIN # POS_EQ_DEC_MAIN <...> # id=N3233000:4280 ra=12.06964142 dec=11.93743758 class=Star id=N3233000:4440 ra=12.00563246 dec=11.98930768 class=Star id=N3233000:4396 ra=12.04016664 dec=11.97401059 class=Star id=N3233000:4174 ra=11.97466466 dec=11.90447683 class=Star id=N3233000:4182 ra=11.98926385 dec=11.90476293 class=Star
The output is slightly different than for the Java version, but functionally the two versions of the tasks are the same. Similar versions of the cone1 VOClient demo task could be built in FORTRAN, IRAF, Python, and so forth.
Now lets look at the source code for the C version of cone1, to see how it compares to the Java code we examined earlier:
/* Summarize and print selected query results.
*/
for (i = 0; i < nrec; i++) {
char *s_id, *s_ra, *s_dec, *s_class;
rec = voc_getRecord (qr, i); /* get a row in the table */
/* The getStringAttr method returns an allocated pointer to a string
* we'll need to free below, however we can use a NULL pointer to
* know when no data were found.
*/
s_id = voc_getStringAttr (rec, "ID_MAIN");
s_ra = voc_getStringAttr (rec, "POS_EQ_RA_MAIN");
s_dec = voc_getStringAttr (rec, "POS_EQ_DEC_MAIN");
s_class = voc_getStringAttr (rec, "CLASS_OBJECT");
printf ("id=%-16s ra=%s\tdec=%s\tclass=%s\n",
(s_id ? s_id : ""),
(s_ra ? s_ra : ""),
(s_dec ? s_dec : ""),
(s_class ? s_class : ""));
if (s_id) free ((void *) s_id); /* clean up temp pointers */
if (s_ra) free ((void *) s_ra);
if (s_dec) free ((void *) s_dec);
if (s_class) free ((void *) s_class);
}
As one would expect, the C code is very similar to the Java code shown earlier, except for minor differences in the two languages. In the C version however, the C program is talking to voclientd via interprocess communication, whereas the Java version was using the dalclient library directly.
Finally, we should clean up the VOClient source tree to return it to its original state:
% cd $NVOSS_HOME/voclient % ant distclean
Various other sample applications will be found in the VOClient examples directory which we won't show here, including the corresponding SIAP versions of the cone search client programs. In addition, test programs are available for querying the VO registry, and for various VO utilities such as the Sesame name resolver.
The NVO Summer School is made possible through the support of the National Science Foundation and the National Aeronautics and Space Administration.
 |
 |