Client API LSQuery

From GEANT2-JRA1 Wiki

Contents

[edit]

LS Client API

This document describes how to create requests for querying LS.

[edit]

Create XQuery expression

First we need to create XQuery expression for the Lookup Service. You may develop your own XQuery expression, or you may use one of XQueryExpression generators. There is generic XQueryExpression generator, called GenericXQueryExpression. It may take various parameters and you should be able to create most of useful queries using this class. Let's start from examples:

  • ask for all MA services 
GenericXQueryExpression g = new GenericXQueryExpression();
g.addMetadataCondition_Is(g.SERVICE_TYPE, "MA");
String xquery = g.generateExpression();
  • ask for all MA services which names contain "PSNC" 
GenericXQueryExpression g = new GenericXQueryExpression();
g.addMetadataCondition_Is(g.SERVICE_TYPE, "MA");
g.addMetadataCondition_Contains(g.SERVICE_NAME, "PSNC");
String xquery = g.generateExpression();
GenericXQueryExpression g = new GenericXQueryExpression();
g.addMetadataCondition_Prefix(g.ACCESS_POINT, "http://man.poznan.pl");
String xquery = g.generateExpression();

As you can see, you create query by adding conditions. There are 4 metadata-block-related conditions:

  • addMetadataCondition_Is(field,value)
  • addMetadataCondition_Prefix(field,value)
  • addMetadataCondition_Suffix(field,value)
  • addMetadataCondition_Contains(field,value)

Possible "fields" are:

  • SERVICE_TYPE (which means "psservice:serviceType")
  • SERVICE_NAME (which means "psservice:serviceName")
  • ACCESS_POINT (which means "psservice:accessPoint")
  • SERVICE_DESCRIPTION (which means "psservice:serviceDescription")
  • ORGANIZATION_NAME (which means "psservice:organization_name")
  • SERVICE_VERSION (which means "psservice:serviceVersion")
  • CONTACT_EMAIL (which means "psservice:contact_email")

By default only URLs of services are returned. If you want to get other format of data you should use 

g.setResultType(g.RETURN_xxx)

Possible values of "RETURN_xxx" are defined in GenericXQueryExpression class and are for instance:

  • RETURN_FULL_LOOKUP_INFO - returns whole Metadata and all data blocks related to service; you should avoid using this option if requesting for more than one service, because a lot of data will be transferred.
  • RETURN_FULL_METADATA - whole Metadata block
  • RETURN_SERVICE_NAME - service name
  • RETURN_SERVICE_URL or RETURN_ACCESS_POINT - set by default; just service URL

You may also add conditions to data elements, however you should take in mind that data elements of Lookup Information are not mandatory. By analogy to metadata conditions there are 4 methods:

  • addDataCondition_Is(field,value)
  • addDataCondition_Prefix(field,value)
  • addDataCondition_Suffix(field,value)
  • addDataCondition_Contains(field,value)

For instance, you may request for all MA services storing data of utilization and having ifAddress starting from 150.254. 

GenericXQueryExpression g = new GenericXQueryExpression();
g.addDataCondition_Contains(g.EVENT_TYPE,"utilization");
g.addDataCondition_Prefix("nmwgt:ifAddress","150.254.");
String xquery = g.generateExpression();

Please note that now only EVENT_TYPE is hard-coded as constant, other values must be given as NMWG tag name (with namespace). That's because there may be too many possibilities for various services.

At the end you will need to use generateExpression(); method to generate XQuery as String.

So, the last example of GenericXQueryExpression is:

  • give metadata block
  • of MA service
  • in PSNC (URL is man.poznan.pl)
  • having utilization data
  • from addresses starting with 150.254. 
GenericXQueryExpression g = new GenericXQueryExpression();
g.setResultType(g.RETURN_FULL_METADATA);
g.addMetadataCondition_Is(g.SERVICE_TYPE, "MA");
g.addMetadataCondition_Prefix(g.ACCESS_POINT, "http://man.poznan.pl");
g.addDataCondition_Contains(g.EVENT_TYPE,"utilization");
g.addDataCondition_Prefix("nmwgt:ifAddress","150.254.");
String xquery = g.generateExpression();
[edit]

Generate XQueryRequest

Having XQuery in xquery variable we may create request to LS. 

LSQueryRequestGenerator requestGenerator = 
     new LSQueryRequestGenerator( xquery );
Message request = requestGenerator.generateRequestMessage();
[edit]

Send request to LS

Having request as Message object in request we need to know URL of LS (endPoint) and location of NMWG parser objects.config file. This file usually comes with NMWG classes. 

AxisClient cl = new AxisClient();
String endPoint = "http://localhost:8080/perfsonar/services/LookupService";
String parserFile = "/home/user/projects/perfsonar/perfsonar-trunk/src/objects.config";
Message response = cl.sendRequest(endPoint, request, parserFile);

The effect will be sending query request to local instance of LS (host: localhost, port: 8080). Response from LS will be in response Message variable.

[edit]

Understanding the response

Response is Message object. We may print it out by: 

String resMsgTxt = XMLUtils.serializeXML(response);

or just get result values. 

Iterator i = response.getDataMap().values().iterator();
while (i.hasNext()) {
    Data d = (Data)i.next();
    for (int j=0; j < d.getDatumLength(); j++) {
        String value = d.getDatum(j).getValue();
        System.out.println( value );
    }
}

Please remember that if you requested FULL_METADATA or FULL_LOOKUP_INFO, the XML will be encoded:

  • &lt; instead of <
  • &gt; instead of >
  • &quot; instead of "
  • &amp; instead of &
[edit]

How to make it easier

  • convert results...

TO BE DONE

Retrieved from "http://wiki.perfsonar.net/jra1-wiki/index.php/Client_API_LSQuery"
Personal tools