ARQ - Application API

INCOMPLETE DRAFT

The application API is in the package: com.hp.hpl.jena.query

Other packages contain various parts of the system (execution engine, parsers, testing etc). Most applications will only need to use the main package. Only applications wishing to programmatically build queries or odify the behaviour of the query engine need use the others packages directly.

Key Classes

• Query - a class that represents the application query. It is a container for all the details of the query. Objects of class Query are normally created by calling one of the class methods which provide access to the various parsers.
• QueryExecution - represents one execution of a query.
• QueryExecutionFactory - a place to get QueryExecuition instances
• For SELECT queries:
  • QuerySolution - A single solution to the query
  • ResultSet - All the QuerySolutions. An iterator.
  • ResultSetFormatter - turn a ResultSet into various forms; into text, into an RDF graph (Model, in Jena terminology) or as plain XML

Basic example: SELECT query

See example 1

  Model model = ... ;
  String queryString = " .... " ;
  Query query = QueryFactory.create(queryString) ;
  QueryExecution qexec = QueryExecutionFactory.create(query, model) ;
  ResultSet results = qe.execSelect() ;
  for ( ; results.hasNext() ; )
  {
      QuerySolution soln = results.nextSolution() ;
  }
  qexec.close() ;

The query execution should be closed after use, and especially if aborting a query (not handling all the results). System resources connected to persistent storage may need to be released.

Example: formatting a result set

Example: processing results to produce a simple text presentation:

    ResultSetFormatter fmt = new ResultSetFormatter(results, query) ;
    fmt.printAll(System.out) ;

    or simply:

 ResultSetFormatter.out(System.out, results, query) ;

    Example: Processing results

    The results are objects from the Jena RDF API and API calls, which do not 
	modify the model, can be mixed with query results processing: 




  for ( ; results.hasNext() ; )
  {
      // Access variables: soln.get("x") ;
      RDFNode n = soln.get("x") ; // "x" is a variable in the query
      // If you need to test the thing returned
      if ( n instanceof Literal )
          ((Literal)n).getLexicalForm() ;
      else
      {
          Resource r = (Resource)n ;
          if ( ! r.isAnon() )
          {
            ... r.getURI() ...
          }
      }
  }



Updates to the model must be carried out after the query execution. 
Typically, this involves collecting results of interest in a local datastructure 
and looping over that structure after the query execution has finished and been 
closed.  
Creating a Query

Parse errors
Expand example

Executing a Query

Execution errors
Expand example

Query Results : CONSTRUCT
Query query = QueryFactory.create(queryString) ;
QueryExecution qexec = QueryFactory.createQueryExecution(query) ;
Model model = query.execConstruct() ;
Query Results : DESCRIBE
Query query = QueryFactory.create(queryString) ;
QueryExecution qexec = QueryFactory.createQueryExecution(query) ;
Model model = query.execConstructDescribe() ;
Query Results : ASK
The operation Query.execAsk() returns a boolean value indicating whether the 
query pattern matched the graph or dataset or not.
Formatting Result Sets

Formatting XML results

ARQ Documentation Home Page






 
CVS: $Date: 2005-03-06 18:52:22 $