Using HeFQUIN as a Java library

Once you have added HeFQUIN as a dependency for your Maven project, you can use any of the Java interfaces and classes of the HeFQUIN source code in the Java code of your project. You find information about these interfaces and classes in our Javadoc documentation.

Most likely, you'll want to use an instance of the HeFQUINEngine class to execute queries. There are two ways in which you can use it: one is to have it execute a given query with the result written directly to stdout or any other output stream and the other way is to have it return the query result as a Jena ResultSet object. The remainder of this page introduces the Java code that you have to write for both cases, step by step.

If you are simply looking for a complete snippet of code that you can copy to get started, look at ExternalIntegrationDemo.java in our GitHub repo. In particular, lines 71-99 present the first of the aforementioned two ways of using HeFQUINEngine and lines 109-146 present the second one.

Create a HeFQUINEngine Instance

In both cases, you first need to create an instance of the HeFQUINEngine class, for which you can use the HeFQUINEngineBuilder as follows.

final String fedDescrFile = "..."; // filename of RDF description of your federation
final HeFQUINEngine hefquin = new HeFQUINEngineBuilder()
				.withFederationCatalog(fedDescrFile)
				.build();

As you can see, you need to provide the name of an RDF file that contains a description of your federation. This file may be in Turtle format or in any other typical RDF serialization format.

As an alternative to providing such a file, you may construct a FederationCatalog object in your program and pass that object to the withFederationCatalog(...) method.

In addition to the withFederationCatalog(...) method, HeFQUINEngineBuilder provides several other methods to set specific components for the HeFQUINEngine to be created. While withFederationCatalog(...) is mandatory, these other methods are optional and HeFQUINEngineBuilder uses default components if they are not provided.

Query Execution With Result Writing

Once you have a HeFQUINEngine object, you can use it to execute any supported SPARQL query with the result being printed directly to stdout. The query needs to be provided in the form of a Jena Query object, which may be created using the QueryFactory , as illustrated at the beginning of the following example.

final Query query = QueryFactory.create("..."); // a Jena Query object

QueryProcessingStatsAndExceptions statsAndExcs = null;
try {
	statsAndExcs = hefquin.executeQueryAndPrintResult(query);
}
catch ( final IllegalQueryException ex ) {
	System.err.println( "The given query is invalid: " + ex.getMessage() );
}
catch ( final UnsupportedQueryException ex ) {
	System.err.println( "The given query is not supported by HeFQUIN: " + ex.getMessage() );
}

While the executeQueryAndPrintResult(...) method used in the example is given only the query to be executed, HeFQUINEngine also provides variations of this method with which you can specify a particular output stream to which the query result shall be written, and a particular format.

If you want to execute multiple queries, simply reuse the HeFQUINEngine object and call executeQueryAndPrintResult(...) multiple times. Once the HeFQUINEngine object is not needed anymore, do not forget to shut it down.

The QueryProcessingStatsAndExceptions object returned by these methods can be used to check whether exceptions have occurred during the execution of the query.

if ( statsAndExcs != null && statsAndExcs.containsExceptions() ) {
	final int numbOfExcs = statsAndExcs.getExceptions().size();
	System.err.println( numbOfExcs + " exceptions occurred during query execution" );
}

Accessing the Result

If you do not simply want the query result printed but want to access it directly for further use in your Java program, you can use the executeSelectQuery(...) method of HeFQUINEngine, which returns an object from which you can obtain the query result in the form of a Jena ResultSet.

final Query query = QueryFactory.create("..."); // a Jena Query object

QueryProcessingOutput qProcOutput = null;
try {
	qProcOutput = hefquin.executeSelectQuery(query);
}
catch ( final IllegalQueryException ex ) {
	System.err.println( "The given query is invalid: " + ex.getMessage() );
	System.exit(-1);
}
catch ( final UnsupportedQueryException ex ) {
	System.err.println( "The given query is not supported by HeFQUIN: " + ex.getMessage() );
	System.exit(-1);
}

final ResultSet rs = qProcOutput.getResultSet();

The returned ResultSet can then be used to iterate over the individual solution mappings that are part of the query result (and that are represented as Jena QuerySolution objects).

If you want to execute multiple queries, you can use the executeSelectQuery(...) method multiple times. Once the HeFQUINEngine object is not needed anymore, do not forget to shut it down.

The QueryProcessingOutput object returned by this method also provides access to a QueryProcessingStatsAndExceptions object which can be used to check whether exceptions have occurred during the execution of the query.

final QueryProcessingStatsAndExceptions statsAndExcs = qProcOutput.getStatsAndExceptions();
if ( statsAndExcs != null && statsAndExcs.containsExceptions() ) {
	final int numbOfExcs = statsAndExcs.getExceptions().size();
	System.err.println( numbOfExcs + " exceptions occurred during query execution" );
}

Shut Down the HeFQUINEngine Instance

Once the HeFQUINEngine object is not needed anymore, you should shut it down in order to have it release resources and stop the thread pools that it is using.

hefquin.shutdown();