Skip to content

Java API

The engine is a Java library on Apache Jena 5. Add sparql-generate-all, or sparql-generate-jena and the format modules you need, to your project (see Getting started). The Javadoc is at https://ci.mines-stetienne.fr/sparql-generate/apidocs/, and the module sparql-generate-example of the repository is a complete program.

Parsing a query and making a plan

import fr.mines_stetienne.ci.sparql_generate.SPARQLExt;
import fr.mines_stetienne.ci.sparql_generate.engine.PlanFactory;
import fr.mines_stetienne.ci.sparql_generate.engine.RootPlan;
import fr.mines_stetienne.ci.sparql_generate.query.SPARQLExtQuery;
import org.apache.jena.query.QueryFactory;

SPARQLExt.init();
SPARQLExtQuery query = (SPARQLExtQuery) QueryFactory.create(queryString, SPARQLExt.SYNTAX);
RootPlan plan = PlanFactory.create(query);

PlanFactory.create(String) parses and plans in one call. A RootPlan can be executed several times, with different contexts and initial bindings.

Executing a plan

The execution context gives the input dataset, the stream manager that resolves the IRIs of documents and named queries, and the output when the result is streamed. ContextUtils.build() creates it:

import fr.mines_stetienne.ci.sparql_generate.utils.ContextUtils;
import org.apache.jena.sparql.util.Context;

Context context = ContextUtils.build()
        .setInputDataset(dataset)       // or setInputModel(model); optional
        .setStreamManager(streamManager) // optional, see below
        .setPrefixMapping(query)        // prefixes of the output
        .build();

Then call the method that matches the query form:

Model graph = plan.execGenerate(context);    // GENERATE
ResultSet results = plan.execSelect(context); // SELECT
String text = plan.execTemplate(context);    // TEMPLATE

Each method also takes a List<Binding> as first argument: the initial bindings of the parameters of the query, one execution per binding. For example, to bind ?country to "GB":

import org.apache.jena.graph.NodeFactory;
import org.apache.jena.sparql.core.Var;
import org.apache.jena.sparql.engine.binding.Binding;

Binding binding = Binding.builder()
        .add(Var.alloc("country"), NodeFactory.createLiteralString("GB"))
        .build();
Model graph = plan.execGenerate(List.of(binding), context);

Streaming

The ...Stream methods write the output to the context as it is produced, and return nothing. Set the output in the context:

// GENERATE: any Jena StreamRDF, here N-Triples on the standard output
Context context = ContextUtils.build()
        .setGenerateOutput(StreamRDFWriter.getWriterStream(System.out, Lang.NTRIPLES))
        .build();
plan.execGenerateStream(context);

// SELECT: a consumer of result sets, one per batch of solutions
plan.execSelectStream(ContextUtils.build().setSelectOutput(rs -> ResultSetFormatter.out(rs)).build());

// TEMPLATE: an IndentedWriter
plan.execTemplateStream(ContextUtils.build().setTemplateOutput(IndentedWriter.stdout).build());

Resolving documents and named queries

By default the engine looks documents and named queries up on the file system, on the class path, and on the Web. A SPARQLExtStreamManager maps IRIs to other locations.

import fr.mines_stetienne.ci.sparql_generate.stream.*;

// look relative paths up in the directory "resources"
LocatorFileAccept locator = new LocatorFileAccept(new File("resources").toURI().getPath());

// read documentset/people.csv instead of looking up http://example.org/people.csv
LocationMapperAccept mapper = new LocationMapperAccept();
mapper.addAltEntry("http://example.org/people.csv", "documentset/people.csv");

SPARQLExtStreamManager streamManager = SPARQLExtStreamManager.makeStreamManager(locator, mapper);

LocatorStringMap serves documents held in memory, with their media type; the playground uses it:

LocatorStringMap strings = new LocatorStringMap();
strings.put("http://example.org/people.csv", csvContent, "text/csv");
strings.put("http://example.org/query/person", namedQuery, SPARQLExt.MEDIA_TYPE);
SPARQLExtStreamManager streamManager = SPARQLExtStreamManager.makeStreamManager(strings);

Adding functions and iterators

A function is a Jena Function, registered with its IRI in the Jena FunctionRegistry. An iterator extends IteratorFunctionBase (all rows at once) or IteratorStreamFunctionBase (rows in batches), and is registered in the IteratorFunctionRegistry:

public class ITER_Repeat extends IteratorFunctionBase {
    public static final String URI = "http://example.org/iter/repeat";

    @Override
    public List<List<NodeValue>> exec(List<NodeValue> args) {
        int n = args.get(1).getInteger().intValue();
        List<List<NodeValue>> rows = new ArrayList<>();
        for (int i = 0; i < n; i++) {
            rows.add(List.of(args.get(0)));
        }
        return rows;
    }

    @Override
    public void checkBuild(ExprList args) {
        if (args.size() != 2) {
            throw new QueryBuildException("iter:repeat takes two arguments");
        }
    }
}

IteratorFunctionRegistry.get().put(ITER_Repeat.URI, ITER_Repeat.class);

The modules of the library register theirs at start-up through the Java ServiceLoader: a class that implements FunctionLoader and IteratorFunctionLoader, named in META-INF/services/fr.mines_stetienne.ci.sparql_generate.function.FunctionLoader and META-INF/services/fr.mines_stetienne.ci.sparql_generate.iterator.IteratorFunctionLoader.

Migrating from 2.1

Version 2.2 requires Java 17 and Apache Jena 5.6. Applications that use Jena directly must move to Jena 5 (see the Jena release notes). The API of SPARQL-Generate itself is unchanged; see the changelog.