SPARQL-Generate Java API

The reference implementation of SPARQL-Generate is based on Apache Jena. Its binaries, sources and documentation are available for download at Maven Central.

The sources of sparql-generate-jena contains project sparql-generat-example which can be used as a starting point to use the SPARQL-Generate API.

The javadoc contains comprehensive documentations and examples, and the sources contains a set of unit tests to get more examples.

Maven dependency

To use it in your Maven project, add the following dependency declaration to your Maven project file ( *.pom file):

<dependency>
    <groupId>fr.emse.ci</groupId>
    <artifactId>sparql-generate</artifactId>
    <version>${sparql-generate.version}</version>
</dependency>

Parsing a Query

 SPARQLGenerateQuery query = (SPARQLGenerateQuery) QueryFactory.create(queryString, SPARQLGenerate.SYNTAX);

Classes PlanFactory and RootPlan

First use class PlanFactory to instantiate a RootPlan for a SPARQL-Generate query. Then the RootPlan can be executed several times on different SPARQL datasets, with different initial bindings, and using different execution contexts (e.g., where URLs may be mapped to local files)

Call one of the execGenerate, execSelect, or execTemplate methods to trigger the execution. Here is the signature of some of these methods:

RootPlan plan = PlanFactory.create(query);

// one of:

Model execGenerate(Dataset inputDataset, QuerySolution initialBindings, Context context);
String execTemplate(Dataset inputDataset, QuerySolution initialBindings, Context context);
ResultSet execSelect(Dataset inputDataset, QuerySolution initialBindings, Context context);

The input Dataset

Part of the SPARQL-Generate query execution consists in evaluating a SPARQL 1.1 SELECT * query over a RDF Graph, or a SPARQL Dataset. Exactly like in SPARQL 1.1. The corresponding parameters are inputModel or inputDataset. To instantiate a Model, which is the Jena class for a RDF Graph, one may use for example:

Model model = ModelFactory.createDefaultModel();
RDFDataMgr.read(model, inputStream, Lang.TURTLE);

The context

The default behaviour of the implementation is to use the Jena StreamManager to fetch the queries or sources from their URL. One may map URIs to local files using the Jena StreamManager and LocationMapper.

The following snippet illustrates how this is achieved:

// tell the engine to look into the `resources` directory 
LocatorFileAccept locator = new LocatorFileAccept(new File("resources").toURI().getPath());

// initialize the location mapper
LocationMapperAccept mapper = new LocationMapperAccept();

// tell the engine to read `document.csv` instead of looking up URI `https://example.com/document`
mapper.addAltEntry("https://example.com/document", "document.csv");

// tell the engine to read `query.rqg` instead of looking up URI `https://example.com/query`
mapper.addAltEntry("https://example.com/query", "query.rqg");

// initialize the StreamManager
SPARQLExtStreamManager sm = SPARQLExtStreamManager.makeStreamManager(locator, mapper);

// create the execution context from the StreamManager
Context context = SPARQLExt.createContext(sm);

The context contains other parameterizable execution configuration. For example by default the engine parallelizes the execution as much as possible using all processors to speed up the transformation. This behavior may be changed to one-processor synchronous execution using a different Java 7 ExecutorService, to consume less memory. For example:

// create an executor service with a single worker
ExecutorService executor = Executors.newSingleThreadExecutor();
Context context = SPARQLExt.createContext(sm, execuor);

The initial binding

One may execute the query with initial bindings. This is useful when one wants to pass initial parameters to a query.

The snippet below illustrates the creation of an initial binding with variable ?msg bound to the string "mymessage".

// create the RDF literal
RDFNode jenaLiteral = initialModel.createLiteral("mymessage");

// create the binding
QuerySolutionMap initialBinding = new QuerySolutionMap();
initialBinding.add("msg", jenaLiteral);

Using a SNAPSHOT version from the sources

Most recent SNAPSHOT of SPARQL-Generate version can be downloaded, built (using Maven), and installed automatically using JitPack.

Add repository:

<repository>
    <id>jitpack.io</id>
    <url>https://jitpack.io</url>
</repository>

And dependency

<dependency>
    <groupId>fr.emse.ci</groupId>
    <artifactId>sparql-generate</artifactId>
    <version>2.0-SNAPSHOT</version>
</dependency>

Is the documentation missing important information?

Don’t hesitate to create an issue on GitHub to ask for help or suggest improvement.

Back to top

Version: 2.0-SNAPSHOT. Last Published: 2019-07-04.