ARQ - Application API

翻译页面http://jena.apache.org/documentation/query/app_api.html

ARQ——应用程序API

应用程序API位于package . apache.jena.query中。
其他包包含系统的各个部分(执行引擎、解析器、测试等)。大多数应用程序只需要使用主包。只有希望以编程方式构建查询或修改查询引擎的行为的应用程序需要直接使用其他程序包。

关键类

包org.apache.jena。查询是主要的应用程序包。
查询—表示应用程序查询的类。它是查询的所有细节的容器。类查询的对象通常是通过调用QueryFactory方法的一个方法来创建的，该方法提供对各种解析器的访问。
QueryExecution——表示查询的执行。
QueryExecutionFactory——一个获取QueryExecution实例的地方。
DatasetFactory——一个用来制作数据集的地方。
选择查询:
QuerySolution——查询的单一解决方案。
ResultSet——所有的QuerySolutions。一个迭代器。
ResultSetFormatter——将结果集转换成各种形式;输入json、文本或纯XML。

选择查询

下面的示例中概述了创建SELECT查询的基本步骤。查询是通过使用QueryFactory的字符串创建的。查询和模型或RDF数据集被查询，然后传递给QueryExecutionFactory，以生成查询执行的实例。. lang QueryExecution对象。可自动关闭，可在试用资源中使用。结果在循环中处理，最后执行查询执行。

import org.apache.jena.query.* ;
  Model model = ... ;
  String queryString = " .... " ;
  Query query = QueryFactory.create(queryString) ;
  try (QueryExecution qexec = QueryExecutionFactory.create(query, model)) {
    ResultSet results = qexec.execSelect() ;
    for ( ; results.hasNext() ; )
    {
      QuerySolution soln = results.nextSolution() ;
      // Get a result variable by name.
      RDFNode x = soln.get("varName") ;
      // Get a result variable - must be a resource       
      Resource r = soln.getResource("VarR") ; 
      // Get a result variable - must be a literal
      Literal l = soln.getLiteral("VarL") ;  
    }
  }

在完成查询执行时，清理查询执行是很重要的。连接到持久存储的系统资源可能需要释放。
一个ResultSet支持Java迭代器接口，因此，如果喜欢的话，下面也是一种处理结果的方法:

Iterator<QuerySolution> results = qexec.execSelect() ;
for ( ; results.hasNext() ; )
{
    QuerySolution soln = results.next() ;
    . . .
}

在一些常见的情况下，创建查询和查询执行的步骤可以减少为一个步骤:

import org.apache.jena.query.* ;
  Model model = ... ;
  String queryString = " .... " ;
  try (QueryExecution qexec = QueryExecutionFactory.create(queryString, model)) 
  {
    ResultSet results = qexec.execSelect() ;
    . . .
  }

从处理循环中传递一个结果集。

ResultSet是一个迭代器，只能遍历一次。更重要的是，许多查询执行和结果集处理都以流媒体方式在内部进行处理。在QueryExecution关闭之后，execSelect返回的ResultSet无效，无论是显式的还是通过try - resources执行的QueryExecution实现了AutoCloseable。
结果集可以实现——然后在外部使用

try (QueryExecution qexec = QueryExecutionFactory.create(queryString, model)) 
{
      ResultSet results = qexec.execSelect() ;
      results = ResultSetFactory.copyResults(results) ;
      return results ;    // Passes the result set out of the try-resources
}

结果集于ResultSetFactory。copyResults是一个ResultSetRewindable，它有一个reset()操作，它在结果的开始处定位迭代器。
当结果将被用于修改数据的循环时，也可以使用此方法。在对SELECT查询的结果进行循环时，不可能更新模型或数据集。
exec构造和exec描述返回的模型在QueryExecution关闭后是有效的。

示例:格式化结果集

应用程序可以调用ResultSetFormatter的操作，而不是一个循环来处理结果集中的每一行。这就是命令行应用程序所做的。
示例:处理结果生成一个简单的文本表示:

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

或者仅仅是:

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

例如:处理结果

结果是来自Jena RDF API和API调用的对象，它们不修改模型，可以与查询结果处理混合:

 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.isLiteral() )
          ((Literal)n).getLexicalForm() ;
      if ( n.isResource() )
      {
         Resource r = (Resource)n ;
          if ( ! r.isAnon() )
          {
            ... r.getURI() ...
          }
      }
  }

在查询执行完成后，必须对模型进行更新。通常，这涉及到收集本地数据结构的兴趣结果，并在查询执行结束并关闭后对该结构进行循环。

构造查询

Query query = QueryFactory.create(queryString) ;
QueryExecution qexec = QueryExecutionFactory.create(query, model) ;
Model resultModel = qexec.execConstruct() ;qexec.close() ;

描述查询

描述查询返回一个RDF图。描述操作的不同处理程序可以由应用程序添加。

Query query = QueryFactory.create(queryString) ;
QueryExecution qexec = QueryExecutionFactory.create(query, model) ;
Model resultModel = qexec.execDescribe() ;qexec.close() ;

请查询

操作Query.execAsk()返回一个布尔值，指示查询模式是否与图或数据集匹配。

Query query = QueryFactory.create(queryString) ;
QueryExecution qexec = QueryExecutionFactory.create(query, model) ;
boolean result = qexec.execAsk() ;qexec.close() ;

格式化的XML结果

ResultSetFormatter类有方法写出SPARQL查询结果XML格式。看到还。ResultSetFormatteroutputAsXML方法。

数据集

上面的示例都是针对单个模型的所有查询。SPARQL查询是在数据集上进行的，该数据集是一个默认的图和零个或多个命名图。可以使用DatasetFactory构造数据集:

String dftGraphURI = "file:default-graph.ttl" ;
List namedGraphURIs = new ArrayList() ;
namedGraphURIs.add("file:named-1.ttl") ;
namedGraphURIs.add("file:named-2.ttl") ;
Query query = QueryFactory.create(queryString) ;
Dataset dataset = DatasetFactory.create(dftGraphURI, namedGraphURIs) ;
try(
    QueryExecution qExec = QueryExecutionFactory.create(query, dataset)) 
    {...}

已经存在的模型也可以使用:

Dataset dataset = DatasetFactory.create() ;
dataset.setDefaultModel(model) ;
dataset.addNamedModel("http://example/named-1", modelX) ;
dataset.addNamedModel("http://example/named-2", modelY) ;
 try(
 QueryExecution qExec = QueryExecutionFactory.create(query, dataset)) 
 {...}

ARQ文档索引http://jena.apache.org/documentation/query/index.html