Web Services

The GPIR web services are made up of GPIRQuery which is used for reading information from GPIR, and GPIRIngester which is used for writing information to it. Both services rely on XML documents that follow the GPIR schemas.

GPIR Query

The GPIRQuery web service exposes the following two methods:

  1. getQueryByResource ? This queries a single GPIR resource. It accepts two parameters, the first is a string representing the name of the particular query being requested, the second being the name of the specific resource being queried strHostname parameter is the exact full hostname of the resource being queried (e.g. myhost.tacc.utexas.edu).
  2. getQueryByVo - This quwey also accepts the strQuery parameter, but its second parameter is a string representing the exact name, as registered in GPIR, of the VO whose resources you wish to retrieve.

The former returns data for a single resource while the later returns data for multiple resources that are in a VO. The query name parameter called strQuery is limited to the types listed below.

  • load - an xml document corresponding to the loads.xsd schema. This document includes all load types data that exists in GPIR.
  • jobs - returns an xml document corresponding to the jobs.xsd schema. This document includes data on jobs that exist on the resources queuing system.
  • motd - ?message of the day? data according to motd.xsd.
  • nodes - node status information for a resource or set of resources according to nodes.xsd.
  • nws - returns point to point Network Weather Service data for resources in a VO when used with the getQueryByVo method. It is only used with an overloaded form of the getQueryByResource method that accepts a third parameter corresponding to the VO that you wish to obtain NWS data from for the requested Resource. It follows nws.xsd.
  • downtime - downtime data according to downtime.xsd.
  • queues - queue data for a Resource or a VO, follows queues.xsd
  • status - a simple bit indicating resource status (i.e. "up" or "down") using status.xsd

These queries above were ?simple? queries returning a specific type of resource or VO data. The queries below are more complex compound queries that can be convenient when writing portals that display a broad range of data on a single page.

  1. static - returns all of the "human-centric" data for a resource or resources according to static.xsd.
  2. summary - a broad range of summary data for a resource or VO according to summary.xsd.
  3. stats - resource statistics (e.g. number of nodes) using the stats.xsd schema.

Here is a sample query client: 


import java.net.*;
import java.util.*;
import java.lang.*;
import org.apache.soap.*;
import org.apache.soap.rpc.*;

public class QueryClient {

    /* The Web service URL, NAME and METHOD */
    private final static String WSURL = "http://myhost:8080/gpir/webservices";
    private final static String WS_NAME = "GPIRQuery";
    private final static String WS_METHOD = "getQueryByVo";

    public static void runWS(String strQuery, String strVO) throws Exception {

        URL url = new URL(WSURL);
        Call call = new Call();
        String encodingStyleURI = Constants.NS_URI_SOAP_ENC;
        call.setEncodingStyleURI(encodingStyleURI);
        call.setTargetObjectURI(WS_NAME);
        call.setMethodName(WS_METHOD);
        Vector params = new Vector();
        params.addElement(new Parameter("strQuery", String.class, strQuery, null));
        params.addElement(new Parameter("strVO", String.class, strVO, null));
        call.setParams(params);

        Response resp = call.invoke(url, "");
        if (resp.generatedFault()) {
            Fault fault = resp.getFault();
            System.out.println("ERROR call failed: ");
            System.out.println("  Fault Code   = " + fault.getFaultCode());
            System.out.println("  Fault String = " + fault.getFaultString());
        } else {
            Parameter result = resp.getReturnValue();
            System.out.println(result.getValue());
        }
    }
}

GPIR Ingester

The GPIRIngester is in essence a mirror image of the GPIRQuery. A single ingest method accepts as it's one argument an XML document corresponding to one of the follows schemas:

  • status
  • load
  • nodes
  • jobs
  • nws
  • motd

The ingester method distinguishes between ingester types by examining the value of the root element of the XML document. If this value does not correspond to one of the root element values as specified in the schemas it will return an error.

Here is a sample Ingester Client: 


import java.net.*;
import java.util.*;
import java.lang.*;

import org.apache.soap.*;
import org.apache.soap.rpc.*;

public class IngesterClient {
    // The Web service URL, NAME and METHOD
    private final static String WSURL = "http://myhost:8080/gpir/webservices";
    private final static String WS_NAME = "GPIRIngester";
    private final static String WS_METHOD = "ingest";

    public static void runWS(String strXML) throws Exception {
        URL url = new URL(WSURL);
        //Build SOAP Call
        Call call = new Call();
        String encodingStyleURI = Constants.NS_URI_SOAP_ENC;
        call.setEncodingStyleURI(encodingStyleURI);
        call.setTargetObjectURI(WS_NAME);
        call.setMethodName(WS_METHOD);

        //Build Paramter list for method call
        Vector params = new Vector();
        params.addElement(new Parameter("strXMLSource", String.class, strXML, null));
        call.setParams(params);

        //Run method call, retrieve response
        Response resp = call.invoke(url, "");

        //Report error or result string
        if (resp.generatedFault()) {
            Fault fault = resp.getFault();
            System.out.println("ERROR call failed: ");
            System.out.println("  Fault Code   = " + fault.getFaultCode());
            System.out.println("  Fault String = " + fault.getFaultString());
        } else {
            Parameter result = resp.getReturnValue();
            System.out.println(result.getValue());
        }
    }
}