Network Weather Service
| NWS site |
|
| NWS Sponsors |
|
|
| Collaborators |
| Edit... |
NOTE: This page describes the ALPHA QBETS interface release. All interfaces/information presented here is subject to change (notifications of changes are always made to the mailing list, linked to below).
These are instructions for querying our batch queue prediction Web service programmatically, using SOAP. (To make manual queries, you may want to try our QBETS C API/UNIX command line tools or the QBETS Web interface instead.)
Quick links
- Web service mailing list
- Web service WSDL
- Web service return string 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)
- String qbetsPredictMultiBounds (long timeStamp[], String machine[], String queue[], int nodes[], long wallTime[], float confidence[], float confidence[])
- String qbetsPredictMultiDeadlines (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 linked schema. The routines with 'Multi' in their names are for making aggragate QBETS calls. All parameters to these routines are arrays f the same types as their single prediction counterparts. The input arrays are evaluated in linear order (the first result you get back would be for all array values at index 0, then 1, then 2, etc). Here are some examples; 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, setting 'machine' and 'queue' input parameters to 'ncsateragrid' and 'dque' respectively may result in XML documents of the following form as output from qbetsPredictBound()
<qbetsPredictions>
<boundPrediction>
<status>SUCCESS</status>
<statusLong>Success</statusLong>
<prediction>21783</prediction>
<ts>1192807056</ts>
<machine>ncsateragrid</machine>
<queue>dque</queue>
<nodes>4</nodes>
<walltime>3600</walltime>
<quantile>0.95</quantile>
<confidence>0.05</confidence>
</boundPrediction>
</qbetsPredictions>
and qbetsPredictDeadline()
<qbetsPredictions>
<deadlinePrediction>
<status>SUCCESS</status>
<statusLong>Success</statusLong>
<prediction>0.950738462382</prediction>
<ts>1192807056</ts>
<machine>ncsateragrid</machine>
<queue>dque</queue>
<nodes>4</nodes>
<walltime>3600</walltime>
<startdeadline>43200</startdeadline>
</deadlinePrediction>
</qbetsPredictions>
and qbetsPredictMultiDeadlines(), like so:
qbetsPredictMultiDeadlines([0, 0],["ucteragrid", "ncsateragrid"], ["dque", "dque"], [4, 1], [3600, 14400], [0.0, 0.0], [43200, 43200]);
<qbetsPredictions>
<deadlinePrediction>
<status>SUCCESS</status>
<statusLong>Success</statusLong>
<prediction>0.97</prediction>
<ts>1192807785</ts>
<machine>ucteragrid</machine>
<queue>dque</queue>
<nodes>4</nodes>
<walltime>3600</walltime>
<startdeadline>43200</startdeadline>
</deadlinePrediction>
<deadlinePrediction>
<status>SUCCESS</status>
<statusLong>Success</statusLong>
<prediction>0.950738462382</prediction>
<ts>1192807785</ts>
<machine>ncsateragrid</machine>
<queue>dque</queue>
<nodes>1</nodes>
<walltime>14400</walltime>
<startdeadline>43200</startdeadline>
</deadlinePrediction>
</qbetsPredictions>
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), perform the following procedure:
java org.apache.axis.wsdl.WSDL2Java -o . -dSession -s -Strue -N"urn:edu.ucsb.cs.mayhem.qbets"="edu.ucsb.cs.mayhem.qbets" Qbets.wsdl
This generates the stubs in edu/ucsb/cs/ which you then need to compile:
cd edu/ucsb/cs/mayhem/qbets; javac *.java; cd ../../..
Next, compile the java client (make sure '.' is in your classpath) and move it into the package directory:
javac QbetsClient.java; mv QbetsClient.class edu/ucsb/cs/mayhem/qbets
Finally, run the program:
java edu/ucsb/cs/mayhem/qbets/QbetsClient
The following sample Java client NwsClient.java will query the service.
package edu.ucsb.cs.mayhem.qbets;
public class QbetsClient {
public static void main(String[] args) throws Exception {
QbetsServiceLocator l = new QbetsServiceLocator();
QbetsSoapBindingStub stub = (QbetsSoapBindingStub) l.getQbets();
long[] timeStamps = {0};
String[] machines = {"ucteragrid","ncsateragrid","datastar"};
String[] queues = {"dque","dque","normal"};
int[] nodess = {4};
long[] wallTimes = {3600};
float[] quantiles = {0.0f};
float[] confidences = {0.0f};
long[] startDeadlines = {43200};
System.out.println(stub.qbetsGetMachines());
System.out.println(stub.qbetsPredictBound(0, "datastar", "normal", 4, 34l, 0, 0));
System.out.println(stub.qbetsPredictMultiBounds(timeStamps, machines, queues, nodess, wallTimes, quantiles, confidences));
System.out.println(stub.qbetsPredictDeadline(0, "datastar", "normal", 4, 34l, 0, 56l));
System.out.println(stub.qbetsPredictMultiDeadlines(timeStamps, machines, queues, nodess, wallTimes, confidences, startDeadlines));
}
}
Alternatively, you can query the service with solutions based on the Perl SOAP::Lite library. Following is an example QbetsClient.pl which queries the service:
#!/usr/bin/perl
#
# 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/Qbets");
$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
";