QueryResults

The QueryResults class allows to decode the XML results of a SPARQL request.

Overview

The result of a SPARQL request can be either:

• A result formatted in JSON (see SPARQL 1.1 Query Results JSON Format)
• A result formatted in XML (see SSPARQL Query Results XML Format (Second Edition))
• A result formatted in CSV

The QueryResultsUtilities class allows to parse the XML and create an associated data structure which can be processed by your program.


The various static methods QueryResults instance create a QueryResults instance.

QueryResults class

The QueryResults class has the following methods:

• The QueryResults.countResults() method return the number of results of the query
• The QueryResults.hasResults() method return true if there is at least one result for the query
• The QueryResults.getFirstResult() method return the first result for the query
• The QueryResults.getResults() method return all the results for the query. Note that it will return null if there are no results
• The QueryResults.getOrderedResultsList() method return the ordered result list. It will return an empty list if there are no results
• The QueryResults.getOrderedResult(int index) method return the result for a specified index

Results map

The QueryResults.getResults() return the map of results. The QueryResults.getFirstResult() method return the firt element in the map according to the Map order.

The key of the result Map will be the SELECT variable used to order the result (by the orderedBy argument)). If this variable was not part of the SELECT variables, then it will be the first encountered variable in the columns.

For example:

   String resultsAsXML = <the XML results returned by the SPARQL engine>);
   QueryResults results = QueryResultsUtilities.getOrderedResults(resultsAsXML, true, "name");
   Map<String, QueryResults.Result> map = results.getResults(); // the map will be ordered by the values of the "?name" variable

Results list

The QueryResults.getOrderedResultsList() and QueryResults.getOrderedResult(int index) methods return the results in the order it had been returned by the SPARQL engine.

For example:

   String resultsAsXML = <the XML results returned by the SPARQL engine>);
   QueryResults results = QueryResultsUtilities.getOrderedResults(resultsAsXML, true, "name");
   List<QueryResults.Result> list = results.getResultsList(); // the map will be ordered in the order it had been returned by the SPARQL engine

QueryResults.Result class

The QueryResults.Result represent one result (returned by the results map or the results list). It contains the Map of attributes for one result.

This class has the following methods:

• The QueryResults.Result.getKey() method return the key of the result, corresponding to the variable returned in the result Map
• The QueryResults.Result.countValues() method return the number of values, which correspond to the number of variables declared in the SELECT construct
• The QueryResults.Result.getValues() method return the values for the result, corresponding to the list of variables declared in the SELECT construct. The key of the Map is the variable name
• The QueryResults.Result.getValue(String key) method return the value for a specified key (ie variable name)

QueryResults.Value class

The QueryResults.Value class represent one value in a result.

This class has the following methods:

• The QueryResults.Value.getValue() method return the associated value Object, which tyype depends on the type of the value (String, int, long, Boolean, etc...)
• The QueryResults.Value.getValueAsString() method return the value as a String
• The QueryResults.Value.getValueAsInt() method return the value as an int
• The QueryResults.Value.getValueAsLong() method return the value as a long
• The QueryResults.Value.getValueAsShort() method return the value as a short
• The QueryResults.Value.getValueAsFloat() method return the value as a float
• The QueryResults.Value.getValueAsDouble() method return the value as a double
• The QueryResults.Value.getValueAsBoolean() method return the value as a boolean

Examples

Basic example

Suppose the following query:

   SELECT ?number ?type
   WHERE { 
      ?alarm rdf:type inav:Alarm .
      ?alarm inav:AlarmNumber ?number .
      ?alarm inav:hasAlarmType ?type .
   }    

The following code will print the ?number and ?type of each result:

   public void subscribe(ServiceInstance service) {
      QueryResults results = (QueryResults) service.getData("response").getValue();
      Iterator<QueryResults.Result> it = results.getOrderedResultsList().iterator();
      while (it.hasNext()) {
       QueryResults.Result result = it.next();
        int number = result.getValue("number").getValueAsInt();
        String type = result.getValue("type").getValueAsString();
        System.out.println("Alarm " + number + ": " + type);
      }
   }

Second example

Suppose the following SPARQL XML result:

   <sparql xmlns="http://www.w3.org/2005/sparql-results#">
      <head>
         <variable name="name"/>
         <variable name="age"/>
      </head>
      <results>
         <result> 
            <binding name="name">
               <literal xml:lang="en">Bob</literal>
            </binding>
            <binding name="age">
               <literal datatype="http://www.w3.org/2001/XMLSchema#integer">30</literal>
            </binding>
         </result>
         <result> 
            <binding name="name">
               <literal xml:lang="en">Bobby</literal>
            </binding>
            <binding name="age">
               <literal datatype="http://www.w3.org/2001/XMLSchema#integer">40</literal>
            </binding>
         </result>      
      </results>
   </sparql>

If we call:

   QueryResults results = QueryResultsUtilities.getOrderedResults(<XML String>, true, "name");

Wr will have two results:

• The first result is the element with the name "Bob"
• The second result is the element with the name "Bobby"