This document is part of the D2RQ documentation.

Using the D2RQ Engine with Jena

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.

1. Jena Versions

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.

2. Installation

  1. Download D2RQ
  2. Add the d2rq-X.Y.jar file from D2RQ's /lib directory to your classpath.
  3. Add all jar files from the /lib/arq-X.Y directory to your application's classpath.
  4. Add 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.
  5. Add a JDBC driver for your database to your application's classpath. Drivers for some popular databases are found in D2RQ's /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.

3. Logging

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

4. Using D2RQ with Jena's Model API

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.

5. Using D2RQ with Jena's Graph API

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();

5.1 The 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.

6. Executing SPARQL queries against a 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();

7. The D2RQ Assembler

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();

8. Javadoc API documentation

Javadoc API documentation for the latest release is available.