Network Weather Service

These are instructions for querying our batch queue prediction Web service programmatically, using SOAP. (To make manual queries, you may want to try our C API/UNIX command line tools or the QBETS Web interface instead.)

Quick links

• Web service mailing list
• Web service WSDL
• Web service routine return schema
• Example java client (more complete documentation below)
• Example perl client

Web service API

The QBETS Web service is fully specified by WSDL. The following routines are supported (shown here in Java syntax):

• String qbetsGetMachines ()
• String qbetsPredictBound (long timeStamp, String machine, String queue, int nodes, long wallTime, float quantile, float confidence)
• String qbetsPredictDeadline (long timeStamp, String machine, String queue, int nodes, long wallTime, float confidence, long startDeadline)

Input to each prediction routine is detailed here:

• timeStamp UNIX timestamp setting time of prediction (default '0' means 'current prediction' or 'now')
• machine Internal tag indicating machine/site name (see qbetsGetMachines() to get a list of machines/queues)
• queue Queue of interest on specified machine
• nodes How many nodes the job will request
• wallTime Max walltime the job will request
• quantile Quantile of interest (default '0' sets quantile to 0.95)
• confidence Confidence interval around quantile prediction (default '0' sets confidence to 0.95)
• startDeadline number of seconds from 'now' of job's desired start time

The methods return results in the form of a string, which contains an XML document formatted according to the following schema. For example, a result from qbetsGetMachines call may contain:

<machines>
<machine>
        <tag>ncsateragrid</tag>
        <queues>
                <queue default="true">dque</queue>
                <queue default="false">big</queue>
                <queue default="false">long</queue>
        </queues>
        <loginHosts>
                <host>tg-login.ncsa.teragrid.org</host>
                <host>tg-login1.ncsa.teragrid.org</host>
        </loginHosts>
        <label>NCSA TeraGrid Cluster</label>
</machine>
</machines>

Contained in this XML document is the 'tag' and a list of 'queue' strings that are used as input to the prediction routines qbetsPredictBound and qbetsPredictDeadline. For instance, following from the above example, we would use 'ncsateragrid' and 'dque' as input to the prediction routines which would return XML documents of the following form for qbetsPredictBound and qbetsPredictDeadline respectively.

<boundPrediction>
        <status>SUCCESS</status>
        <statusLong>Success</statusLong>
        <prediction>79</prediction>
</boundPrediction>

and

<deadlinePrediction>
        <status>SUCCESS</status>
        <statusLong>Success</statusLong>
        <prediction>0.940435820946</prediction>
</deadlinePrediction>

Sample web service clients

We recommend that you use the WSDL to generate client stubs for your environment (although that is not strictly necessary). For example, on a properly configured Axis installation (i.e. your classpath contains Tomcat), the following command

java org.apache.axis.wsdl.WSDL2Java -o . -dSession -s -Strue -N"urn:edu.ucsb.cs"="edu.ucsb.cs"  Nws.wsdl

generates the stubs in edu/ucsb/cs which you then need to compile:

cd edu/ucsb/cs; javac *.java; cs ../../..

Next, compile the java client and move it into the package directory:

javac NwsClient.java; mv NwsClient.class edu/ucsb/cs

Finally, run the program:

java edu/ucsb/cs/NwsClient

The following sample Java client NwsClient.java will query the service.

package edu.ucsb.cs;
public class NwsClient {
        public static void main(String[] args) throws Exception {
            NwsServiceLocator l = new NwsServiceLocator();
            NwsSoapBindingStub stub = (NwsSoapBindingStub) l.getNws();
            
            System.out.println(stub.qbetsGetMachines());
            System.out.println(stub.qbetsPredictBound(0, "datastar", "normal", 4, 34l, 0, 0));
            System.out.println(stub.qbetsPredictDeadline(0, "datastar", "normal", 4, 34l, 0, 56l));
        }
}

Alternatively, you can query the service with solutions based on the Perl SOAP::Lite library. Following is an example NwsClient.pl which queries the service:

#!/usr/bin/perl -w
#
# client for testing NWS QBETS web service
#

use SOAP::Lite;

my $hostname = "nws.cs.ucsb.edu";
my $port = 8180;

if (@ARGV == 0) {
    $machine = "ucteragrid";
    $queue = "dque";
    $nodes = 1;
    $walltime = SOAP::Data->type(long => 3600);
    $startdeadline = SOAP::Data->type(long => 14400);
    $prob = SOAP::Data->type(float => 0.95);
} else {
    $machine = shift @ARGV;
    $queue = shift @ARGV;
    $nodes = shift @ARGV;
    $walltime = SOAP::Data->type(long => shift @ARGV);
    $startdeadline = SOAP::Data->type(long => shift @ARGV);
    $prob = SOAP::Data->type(float => shift @ARGV);
}
my $zero = SOAP::Data->type(long => 0);
my $fzero = SOAP::Data->type(float => 0);

$stub = SOAP::Lite                                            
    -> uri('irrelevant')
    -> proxy("http://$hostname:$port/axis/services/Nws");


$result = $stub -> qbetsGetMachines() -> result;
print "qbetsGetMachines:$result";

$result = $stub -> qbetsPredictBound($zero, $machine, $queue, 
                   $nodes, $walltime, $prob, $fzero) -> result;
print "qbetsPredictBound:$result";

$result = $stub -> qbetsPredictDeadline($zero, $machine, $queue,
                   $nodes, $walltime, $fzero, $startdeadline) -> result;
print "qbetsPredictDeadline:$result";