Apache Jena is a Java framework for building Semantic Web applications. The D2RQ Engine can be used as a component in such applications to access a virtual RDF view on data in relatonal databases.
ModelD2RQ
Since D2RQ plugs into the internals of Jena and its SPARQL query
engine,
ARQ,
it is sensitive to the version of Jena
and ARQ that is being used. D2RQ will usually not work with other
Jena versions than the one it is shipped with. Check the
/lib/arq-X.Y
directory in the D2RQ distribution
for the version used.
d2rq-X.Y.jar
file from D2RQ's
/lib
directory to your classpath./lib/arq-X.Y
directory
to your application's classpath.commons-logging-X.Y.jar
and
slf4j-api-X.Y.jar
from D2RQ's
/lib/logging
directory to your application's classpath.
If your application doesn't configure its own logging system, add
the other jars from that directory as well./lib/db-drivers
directory.The D2RQ download omits some Jena/ARQ jar files
that are not required to run D2RQ, but may be required to use
other Jena/ARQ features. To get all jars, you can download the
correct version of ARQ (as indicated by the name of D2RQ's
/lib/arq-X.Y
directory) from the
Jena download site.
D2RQ logs to the Apache Commons Logging API. D2RQ ships with Apache log4j, but you can use a different logging front-end.
To enable D2RQ debug messages, set the log level for logger
de.fuberlin.wiwiss.d2rq
to ALL
.
An easy way to do this is to add the log4j jars from
D2RQ's /lib/logging
directory to your application's
classpath, and create a file log4j.properties
somewhere
in the classpath (e.g., in your source folder) with these contents:
log4j.rootLogger=INFO, stdout log4j.appender.stdout=org.apache.log4j.ConsoleAppender log4j.appender.stdout.layout=org.apache.log4j.PatternLayout log4j.appender.stdout.layout.ConversionPattern=%d{HH:mm:ss} %-5p %-20c{1} :: %m%n log4j.logger.de.fuberlin.wiwiss.d2rq=ALL
The ModelD2RQ
class provides a Jena
Model
view on the data
in a D2RQ-mapped database.
The following example shows how a ModelD2RQ
is set up
using a previously created mapping file, and how Jena API calls
are used to extract
information about papers and their authors from the model.
// Set up the ModelD2RQ using a mapping file Model m = new ModelD2RQ("file:doc/example/mapping-iswc.ttl"); // Find anything with an rdf:type of iswc:InProceedings StmtIterator paperIt = m.listStatements(null, RDF.type, ISWC.InProceedings); // List found papers and print their titles while (paperIt.hasNext()) { Resource paper = paperIt.nextStatement().getSubject(); System.out.println("Paper: " + paper.getProperty(DC.title).getString()); // List authors of the paper and print their names StmtIterator authorIt = paper.listProperties(DC.creator); while (authorIt.hasNext()) { Resource author = authorIt.nextStatement().getResource(); System.out.println("Author: " + author.getProperty(FOAF.name).getString()); } System.out.println(); } m.close();
The ISWC and FOAF classes have been created with Jena's schemagen tool. The DC and RDF classes are part of Jena.
In some situations, it is better to use Jena's low-level
Graph
API instead of the Model API. D2RQ provides an implementation
of the Graph interface, the GraphD2RQ
.
The following example shows how the Graph API is used to find all papers that have been published in 2003.
// Load mapping file Model mapModel = FileManager.get().loadModel("doc/example/mapping-iswc.ttl"); // Parse mapping file MapParser parser = new MapParser(mapModel, "http://localhost:2020/"); Mapping mapping = parser.parse(); // Set up the GraphD2RQ GraphD2RQ g = new GraphD2RQ(mapping); // Create a find(spo) pattern Node subject = Node.ANY; Node predicate = DC.date.asNode(); Node object = Node.createLiteral("2003", null, XSDDatatype.XSDgYear); Triple pattern = new Triple(subject, predicate, object); // Query the graph Iterator<Triple> it = g.find(pattern); // Output query results while (it.hasNext()) { Triple t = (Triple) it.next(); System.out.println("Published in 2003: " + t.getSubject()); }; g.close();
CachingGraphD2RQ
In addition to the GraphD2RQ
, there is a
CachingGraphD2RQ
which supports
the same API and uses a LRU cache to remember a number of recent query
results. This will improve performance for repeated queries, but will
report inconsistent results if the database is updated during the lifetime
of the CachingGraphD2RQ
.
ModelD2RQ
D2RQ can answer SPARQL queries against a D2RQ model. The example shows how a D2RQ model is set up, how a SPARQL query is executed, and how the results are written to the console.
ModelD2RQ m = new ModelD2RQ("file:doc/example/mapping-iswc.ttl"); String sparql = "PREFIX dc: <http://purl.org/dc/elements/1.1/>" + "PREFIX foaf: <http://xmlns.com/foaf/0.1/>" + "SELECT ?paperTitle ?authorName WHERE {" + " ?paper dc:title ?paperTitle . " + " ?paper dc:creator ?author ." + " ?author foaf:name ?authorName ." + "}"; Query q = QueryFactory.create(sparql); ResultSet rs = QueryExecutionFactory.create(q, m).execSelect(); while (rs.hasNext()) { QuerySolution row = rs.nextSolution(); System.out.println("Title: " + row.getLiteral("paperTitle").getString()); System.out.println("Author: " + row.getLiteral("authorName").getString()); }; m.close();
D2RQ comes with a Jena assembler. Jena assembler specifications are RDF configuration files that describe how to construct a Jena model. For more information on Jena assemblers, see the Jena Assembler quickstart page.
The following example shows an assembler specification for a D2RQ model:
@prefix : <#> . @prefix ja: <http://jena.hpl.hp.com/2005/11/Assembler#> . @prefix d2rq: <http://www.wiwiss.fu-berlin.de/suhl/bizer/D2RQ/0.1#> . <> ja:imports <http://d2rq.org/terms/d2rq> . :myModel a d2rq:D2RQModel; d2rq:mappingFile <mapping-iswc.ttl>; d2rq:resourceBaseURI <http://localhost:2020/>; .
D2RQ model specifications support these two properties:
d2rq:mappingFile | Required. The URI of a D2RQ mapping file to use for setting up the model. |
---|---|
d2rq:resourceBaseURI | The base URI for turning relative URI patterns into full URIs. If not specified, D2RQ will pick an appropriate base URI. |
This usage example will create a D2RQ model from a model specification, and write it to the console:
// Load assembler specification from file Model assemblerSpec = FileManager.get().loadModel("doc/example/assembler.ttl"); // Get the model resource Resource modelSpec = assemblerSpec.createResource(assemblerSpec.expandPrefix(":myModel")); // Assemble a model Model m = Assembler.general.openModel(modelSpec); // Write it to System.out m.write(System.out); m.close();
Javadoc API documentation for the latest release is available.