SPARQL-Generate Java API

sparql-generate-jena is an implementation of SPARQL-Generate over Apache Jena. Its binaries, sources and documentation are available for download at Maven Central. To use it in your Maven project, add the following dependency declaration to your Maven project file ( *.pom file):


Latest version implements iterator and custom SPARQL functions to generate RDF from JSON, XML, HTML, CSV, CBOR, plain text. See the implemented SPARQL binding functions and SPARQL-Generate iterator functions.

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

Parsing a Query

 String queryString = "PREFIX ... GENERATE {...} FROM ... SOURCE ... ITERATOR ... WHERE {...}";
 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.

SPARQLGenerateQuery query;
RootPlan plan = PlanFactory.create(query);

Then the RootPlan can be executed several times on different SPARQL datasets, and with different initial bindings (i.e., on multiple messages). Call one of the exec methods to trigger the RDF generation. Here is the signature of three of these methods:

Model exec();
void exec(Model inputModel, QuerySolution initialBindings, Model initialModel);
void exec(Dataset inputDataset, QuerySolution initialBindings, Model initialModel);

Retrieving the generated RDF

RDF generated by the execution plan is added to a Model, which is the Jena class for a RDF Graph.

  • some exec methods create a new model from scratch at execution time, fill it with the generated triples, and return it to the caller;
  • other method use parameter initialModel, and add triples.

To instantiate a Model, which is the Jena model for a RDF Graph, one may use:


Evaluating a query over a SPARQL 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 Dataset, which is the Jena class for a SPARQL Dataset, one may use:

DatasetFactory.create(Model model);


  • If initialModel == null, then an IllegalArgumentException exception will be thrown;
  • The behaviour when the same instance is passed as inputModel and initialModel is not specified. You should avoid this situation.

Generating RDF for streams of messages

Finally, one may execute the query with initial bindings. This is useful when one wants to apply the same plan to generate RDF from multiple messages regularly received from a lightweight sensor for instance.

Suppose one needs to execute a plan with a variable ?msg bound to a message with textual representation "mymessage" and internet media-type application/json. Then the RDF literal to bind to ?msg:

  • has lexical form "mymessage",
  • has datatype IRI <> (this is optional).

In SPARQL Generate over Apache Jena, one calls an exec method with parameter initialBindings. The following code shows how this can be done with the plan instantiated above:

String variable = "msg";
String message = "mymessage";
String uri = "";

RDFDatatype dt = TypeMapper.getInstance().getSafeTypeByName(uri);
Node arqLiteral = NodeFactory.createLiteral(message, dt);
RDFNode jenaLiteral = initialModel.asRDFNode(arqLiteral);

QuerySolutionMap initialBinding = new QuerySolutionMap();
initialBinding.add(variable, jenaLiteral);

Model initialModel = ModelFactory.createDefaultModel();

plan.exec(initialBinding, initialModel);

Using a StreamManager and a LocationMapper

The default behaviour of the implementation is to use the Jena StreamManager to fetch the queriesor 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:

// read location-mapping
URI confUri = exampleDir.toURI().resolve("configuration.ttl");
Model conf = RDFDataMgr.loadModel(confUri.toString());

// initialize file manager
StreamManager sm = SPARQLGenerate.getStreamManager(conf);
sm.addLocator(new LocatorFile(exampleDir.toURI().getPath()));