Science With the Virtual Observatory 2006 Summer School

Building Registry Querying Capabilities into Clients Applications

Now, even before the establishment of the standard Registry Interface, we have a variety of libraries for querying the NVO registry inside a client application:

• Java: java/src/nvoregistry
• Python: VORegistry python module (python)
• C, Fortran, ...: VOClient (voclient, see PPT)
  • adds richer capabilities on top of the service interface for greater useability.
• IRAF

Note:

All of these implementations access the full NVO Registry at Space Telescope using a proprietary interface. Names of searchable fields will be different from the standard interface, and results will be limited in the metadata returned.

In this part, we will explore the capabilities of the python VORegistry.py module. If you haven't loaded the Summer School Python environment already, you should do that now. (Note: Windows users will have to set their environement explicitly).

on Linux/MacOS: cd $NVOSS_HOME/python source setup.csh		on Windows: see the Python setup instructions for Windows on setting PYTHONPATH via the control panel if you haven't set this already.

This sets your PYTHONPATH environment variable so that python will find the NVOSS python modules.

In this exercise, we will use one of example programs in the python samples directory.

1. Run a simple keyword search by typing:

   python VORegistryEx.py keywordSearch active galactic nuclei | more

   Try different keywords.

See more information by typing:

python VORegistryEx.py keywordSearch active galactic nuclei | more

Note that this only prints the first record.

2. Run a constraint based search to find Cone Search Services

   python VORegistryEx.py queryRegistry "ResourceType like '%CONE%' and Description like '%galaxy%'"

   Try adding more complicated constraints, drawing on searchable terms listed in the field list

3. Extra Credit: modify printFields() to loop through all returned results. (Start by making a copy of VORegistryEx.py before editing it.)

4. Extra Credit: modify queryRegistry() to print more information contained in the results.

   Here it would be useful to bring up the volib documentation. To do this, fire up the pydoc tool:

   on Linux/MacOS: pydoc -p 5000 &		on Windows: open up a new Command Prompt window and type: pydoc -p 5000

   Now point your browser to http://localhost:5000/, and click on the "volib" link and then the "VORegistry" link.

For this part, we will use the nvoregistry Java library. To prepare the exercises, change into the nvoregistry directory and type "ant prep".

on Linux/MacOS: cd $NVOSS_HOME/java/src/nvoregistry ant prep		on Windows: cd %NVOSS_HOME%\java\src\nvoregistry ant prep

3 seconds or so later, you should see ant print "BUILD SUCCESSFUL" to the screen.

Attention:

The NVOSS software package includes an out of date version of the registry WSDL file. Before proceeding, you will need to download the current version and replace the original

registry.wsdl

file in the nvoregistry directory.

The following exercises use a simple Cone Search client called ConeCaller. These exercises build onto each other, so you need to do them in order.

We start by building our client-side interface to the Registry's Web Service using Axis tool, wsdl2java.

1. Type: "wsdl2java registry.wsdl"

   registry.wsdl is the WSDL file for the NVO Registry at STScI. Running wsdl2java creates interface classes along with classes representing the XML types that are sent in the soap messages.

   For example, briefly examine org/us_vo/www/RegistrySoap.java. You will see a method for each of the Web Service methods supported by the STScI Registry.

2. Compile the client code: "ant compileWSDLcode"

   This compiles all the generated code along with our application code within the coneclient directory.

We will now create a class that will look specifically for Cone Search services in the Registry.

1. Open up coneclient/FindConeSearch.java.

   Notice the function called search(). This is a front end to the Web Service's queryRegistry() function. It takes an SQL "WHERE" clause and combines it with a constraint that matches only Cone Search services:

   // Combine our query with a constraint to return only Cone Searches.
   // The resulting query will look something like this:
   // 
   //    ServiceType like '%CONE%' and (Title like '%parallax%')
   // 
   query = "ServiceType like '%CONE%' and (" + query + ")";

   Our method sends this modified query to the Web Service method, queryRegistry(). From the result, we extract an array of resource descriptions. Note that the descriptions are not VOResource records; rather they use a custom schema, SimpleResource (primarily for historical reasons).

2. Test the finder class (from the directory containing the build.xml file):

   java coneclient.FindConeSearch "Description like '%parallax%'"

3. Feed one of the returned service URLs into the ConeCaller application:

   java coneclient.ConeCaller 180.0 60.0 1.0 "http://chart.stsci.edu/GSCVO/HIPVO.jsp?"

   Now try the second service returned by FindConeSearch:

   java coneclient.ConeCaller 180.0 60.0 1.0 "http://vizier.u-strasbg.fr/viz-bin/votable/-dtd/-A?-out.add=_RAJ2000,_DEJ2000&-source=I/280"

   This produces an exception. Why?

   Look at coneclient/ConeCaller.java within callConeService() to see how the URL is formed:

   URL cone = new URL(coneUrl + "RA="+ra+"&DEC="+dec+"&SR="+sr);

   This is compliant with the Cone Search specification. Unfortunately, this particular base URL from the registry needs a trailing &. Despite the standard, many of the URLs in the registry are incorrectly entered in this manner.

   Fortunately, this is not hard to fix in our client application. FindConeSearch.java includes a correctBaseURL() function. We can incorporate this into our FindConeSearch application. Within its main() function, find this line:

   System.out.println("Address: " + cs[i].getServiceURL());

   and change it to:

   System.out.println("Address: " + FindConeSearch.correctBaseURL(cs[i].getServiceURL()));

   Recompile this class by typing "ant", and the try our registry query again.

A keywordSearch() method is provided already by the STScI Registry. It simply compares all the input words to selected text fields in the resource description. Unfortunately, this implementation returns VOResource (v0.9) records, not SimpleResource. More importantly for our purposes, there is no way to combine a keyword search with a specific constraint to select Cone Search services (see Exercise 5 below).

Nevertheless, it would not be difficult to implement our own keyword search that does return SimpleResource records in addition to restricting the match to Cone Search services.

FindConeSearch.java contains a stubbed version of a keywordSearch() method (the last method in the source file); that is, you need to complete the implementation to make it work. If you need to cheat a little, just look at the FindConeSearch.java in the solutions subdirectory or review the answer here.

In our version of ConeCaller, if the fourth command-line argument is a base URL, it will use it to call the specific Cone Search service. If it is not a URL, any arguments after the third one are interpreted as keywords for a registry search, and a keyword query string is formed. In this exercise, pass this query to our FindConeSearch class to retrieve Cone Search base URLs. Then call one or more of the matched services.

For extra credit, call each cone search service and print the number of records it returns. Again, you can peek at ConeCaller.java in the solutions directory, or look here for an explanation.

The NVO Summer School is made possible through the support of the National Science Foundation and the National Aeronautics and Space Administration.