ARQ - API Application

L'API de l'application est dans le paquet com.hp.hpl.jena.query.

D'autres paquets contiennent diverses parties du système (moteur d'exécution, analyseurs, tests, etc.). La plupart des applications n'ont besoin que du paquet principal. Seules les applications souhaitant par programmation, construire des requêtes, ou modifier le comportement du moteur de requête ont besoin d'utiliser les autres paquets directement.

Le paquet com.hp.hpl.jena.query est le paquet principal de l'application.

• Query - une classe qui représente la requête de l'application. C'est un conteneur pour tous les détails de la requête. Les objets de la classe Query sont normalement créés en appelant une des méthodes de QueryFactory qui fournissent un accès à des analyseurs différents.
• QueryExecution - représente l'exécution d'une requête.
• QueryExecutionFactory - un endroit pour obtenir des instances de QueryExecution.
• DatasetFactory - un endroit pour créer des jeux de données, y compris créer une DataSource (un Dataset que l'on peut mettre à jour).
• pour les requêtes SELECT : QuerySolution - une solution unique à la requête ; ResultSet - toutes les QuerySolutions. Un itérateur ; ResultSetFormatter - transformer un ResultSet en diverses formes ; en texte, en graphe RDF (un Model, dans la terminologie de Jena) ou dans du XML brut.

Les étapes de base pour faire une requête SELECT sont décrites dans l'exemple ci-dessous. Une requête est créée à partir d'une chaîne de caractères utilisant la QueryFactory. La requête et le modèle ou le jeu de données RDF pouvant être interrogés sont ensuite transmis à QueryExecutionFactory pour produire une instance de l'exécution de la requête. Les résultats sont traités dans une boucle et finalement l'exécution de la requête est fermée.

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

Il est important de fermer proprement l'exécution de la requête quand elle se termine. Les ressources du système sont connectées à un stockage persistant et ont besoin d'être libérées.

Un ResultSetARQ prend en charge l'interface itérateur de Java, donc ce qui suit est aussi une façon de traiter les résultats si vous préférez :

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

L'étape de la création d'une requête et aussi celle de l'exécution d'une requête peuvent être réduites en une seule dans certains cas les plus communs :

import com.hp.hpl.jena.query.* ;
  Model model = ... ;
  String queryString = " .... " ;
  QueryExecution qexec = QueryExecutionFactory.create(queryString, model) ;
  try {
   ResultSet results = qexec.execSelect() ;
    . . .
  } finally { qexec.close() ; }

III-A. Exemple : le formatage d'un ensemble de résultats▲

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

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

III-B. Exemple : les résultats du traitement▲

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() ...
          }
      }
  }

Les requêtes CONSTRUCT retournent un seul graphe RDF. Comme d'habitude, l'exécution de la requête doit être fermée après utilisation.

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

Les requêtes DESCRIBE retournent un seul graphe RDF. Différents gestionnaires de l'opération DESCRIBE peuvent être chargés et ajoutés par l'application.

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

L'opération Query.execAsk () retourne une valeur booléenne indiquant si le modèle de requête correspond au graphe ou au jeu de données, ou non.

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

La classe ResultSetFormatter possède des méthodes pour écrire les résultats d'interrogation SPARQL au format XML. Voir la méthode ResultSetFormatter.outputAsXML.

Les exemples ci-dessus sont tous des requêtes sur un modèle unique. Une requête SPARQL est faite sur un jeu de données, qui est un graphe par défaut et zéro ou plusieurs graphes nommés. Les jeux de données peuvent être construits en utilisant 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) ;
QueryExecution qExec = QueryExecutionFactory.create(query, dataset) ;
try { ... }
finally { qExec.close() ; }

Les modèles déjà existants peuvent également être utilisés : une DataSource est un jeu de données pouvant être mis à jour.

DataSource dataSource = DatsetFactory.create() ;
dataSource.setDefaultModel(model) ;
dataSource.addNamedModel("http://example/named-1", modelX) ;
dataSource.addNamedModel("http://example/named-2", modelY) ;
QueryExecution qExec = QueryExecutionFactory.create(query, dataSource) ;

Cet article est la traduction de ARQ - Application API.

Merci à Claude Leloup et jacques_jean pour leur relecture orthographique.