User's guide for GADS version 0.1.0

Introduction

This is a brief user guide to GADS (Grid Access Data Service). A more detailed guide will follow, but this should be viewed as a quick "getting started" guide. Please report any questions to JonBlower.

GADS is a Web Service. It is hosted under a Tomcat server using Apache Axis. You can create your own client program to interface with GADS by downloading the WSDL from http://lovejoy.nerc-essc.ac.uk:8080/axis/services/GADS?wsdl and using WSDL2Java to create stub code. This can then be used to build the client. Or, of course, you can just use the sample client described in the next section.

Note: By default, clients built with the Axis 1.1 libraries have a 60-second Socket timeout. This means that GADS requests that take longer than 60 seconds will fail with a java.net.SocketTimeoutException. You can set a different timeout with the following code:

import org.apache.axis.client.Stub;
...
GADSService locator = new GADSServiceLocator();
GADS gads = locator.getGADS();
// Set the timeout on the connection
Stub s = (Stub) gads;
s.setTimeout(600000);  // 10 minutes, in milliseconds

Sample GADS client

A simple client program created in this way is available from here. I recommend that you use this client program as it simplifies the interface to GADS somewhat, and is known to work. Simply extract the tarball to any directory on your machine. You'll need a Java run-time environment to run the code. (Version 1.4.2 has been tested successfully. Older versions should be OK, but get version 1.4.2 if you experience any problems.)

The package includes the Apache Axis libraries necessary for running the client. Alternatively, you can download the libraries from http://ws.apache.org/axis.

To get you started, the file runGADSClient.sh includes some example calls to GADS. Run it like this:

./runGADSClient <username> <password>

If you don't have a username and password, just leave these fields blank. (Usernames and passwords are required to access some datasets: if you need a password to access such a dataset, please contact JonBlower).

For a list of arguments, just type java uk.ac.nercessc.gads.client.GADSClient <method name> (where <method name> is "getInfo", "dataQuery", "dataRequest" or "dataRequestNatural") and the argument list will be printed out. The text below contains some example queries to try out using this client.

GADS methods

GADS implements four methods. The getInfo() method returns information about the installation of GADS itself: the version number, release date and the output file formats. The dataQuery() method provides access to metadata and allows the user to ascertain what datasets are being served by GADS, what variables they contain and so forth. Blocks of data are downloaded using dataRequest() or the more intuitive dataRequestNatural().

getInfo()

This method takes no arguments, and returns an object of type GADSInfo (if you used the Axis tool WSDL2Java to create the Java stub code, a file called GADSInfo.java should have been created automatically for you). The GADSInfo complex type is described in the WSDL and contains three elements:

• a String containing version information (e.g. "0.1")
• a String containing the release date in YYYY-MM-DD format (e.g. "2003-10-23")
• an array of Strings containing the file formats that GADS can output (e.g. {"CDF", "GRIB", "RAW"})

Knowledge of the possible output formats is necessary to construct calls to dataRequest().

Example to try using sample client: java uk.ac.nercessc.gads.client.GADSClient getInfo

dataQuery()

This method takes four arguments: (1) the name of a dataset (2) the name of a variable (3) the name of an axis (4) username and password. By leaving certain of these fields blank, different types of query may be constructed. Here is the list of possible queries:

• dataQuery("", "", "", "username password"): Returns a list of all the datasets visible to the user
• dataQuery("OCCAM", "", "", "username password"): Returns a list of the variables in the OCCAM dataset
• dataQuery("", "sea_water_potential_temperature", "", "username password"): Returns a list of all datasets that contain the variable sea_water_potential_temperature.
• dataQuery("OCCAM", "sea_water_salinity", "", "username password"): Returns a list of the coordinate axes describing the grid on which the sea_water_salinity variable sits
• dataQuery("OCCAM", "sea_water_salinity", "z", "username password"): Returns a list of all the possible values that the z axis can take for this variable. WARNING: for some axes (e.g. longitude (x) in a high-resolution dataset) this can return a very large amount of information!

In each case the username and password are required to check that you are authorised to see a particular dataset. The administrator of a GADS server will provide you with this information.

Remember to leave a space between the username and password. Alternatively, leaving this field blank will log you in as an anonymous user.

dataQuery() always returns a two-dimensional array of Strings (String[][]), i.e. a table. Thinking of this as an array of String arrays, the result is structured as follows. result[0] is an array of Strings giving the titles of the table columns. result[1] to result[n] are the contents of the table. So in Java the result may be parsed using the following code fragment, which outputs the data in tab-delimited format:

String[][] result = gads.dataQuery("", "", "", ""); // Gets details of all datasets visible to the anonymous user

for (int i = 0; i < result.length; i++)
{
  // Cycle through each row in the table
  for (int j = 0; j < result[i].length; j++)
  {
    // Cycle through each column in the table
    System.out.println(result[i][j] + "\t"); // Prints field to standard out, with tab delimiter
  }
}

Typical output from this might be:

Dataset name  Last modified 
OCCAM         ...
FOAM          ...

The result of a query such as number 4 above (gets details of all coordinate axes) might be:

Axis name        units               regular axis? min value  max value  no. of points
 t   time        days since 1984-1-1   irregular    2941.0     4749.0       1808 
 y   latitude_t  degrees_north          regular    -78.125     65.875        577 
 x   longitude_t degrees_east           regular     0.125     359.875       1440

(note that some of the columns have been missed from the above table for space reasons)

Example to try using sample client: java uk.ac.nercessc.gads.client.GADSClient dataQuery "OCCAM_TIMESERIES" "" "" "" ""

dataRequest()

This method allows the user to select a subset of a dataset for downloading. The easiest way to explain how this works is to show a snippet of Java code:

String[] result = gads.dataRequest
(
  "OCCAM",  // The name of the dataset from which to extract data
  
  // Array of Strings containing variable names
  new String[]{"sea_water_potential_temperature", "sea_water_salinity"},
  
  "CDF",   // the data will be prepared in this format
  
  // Array of AxisRequest objects, created by (name, start, stride, count)
  new AxisRequest[]
  {
    new AxisRequest("t", 0, 1, 1),     // Take the first point only along the t axis
    new AxisRequest("z", 5, 1, 1),     // Take the 6th z level only (array is zero-based so we want the level with index 5)
    new AxisRequest("y", 200, 3, 100), // Take 100 points along the y axis, 
                                       //  starting at point 200, extracting every 3rd point
    new AxisRequest("x", 0, 5, -1)     // Subsample the entire x axis, taking every 5th point
  }
  "username password"           // username and password, separated by a space
);

dataRequest() returns an array of Strings, each element being a URL to the extracted data. At present, only one String is returned, giving the URL for an HTTP transfer. In the future, more URLs (for FTP, gridFTP, for example) may be returned.

Example to try using sample client: java uk.ac.nercessc.gads.client.GADSClient dataRequest OCCAM_TIMESERIES sea_water_potential_temperature,sea_water_salinity CDF t 0 1 1 y 0 5 -1 x 0 5 -1 "" "" "" "" "" ""

dataRequestNatural()

The syntax of dataRequest() is a little awkward and requires the user to know too much about the internal structure of the data files. The dataRequestNatural() method addresses this by allowing the user to specify the required subset of data in natural units of time, latitude, longitude and depth (i.e. degrees, metres etc). (to be continued - contact JonBlower for more details if required.)

-- JonBlower - 19 Feb 2004