Class HeFQUINEngine

java.lang.Object

se.liu.ida.hefquin.engine.HeFQUINEngine

public class HeFQUINEngine
extends Object

An object of this class can be used in two ways to process queries over the federation for which the engine has been set up:

1. On the other hand, it can be used to process arbitrary queries and have the result written directly to stdout or to any other PrintStream, in a format that can be specified. This functionality is provided via the following functions.
   • executeQueryAndPrintResult(Query, ResultsFormat, PrintStream)
   • executeQueryAndPrintResult(Query, ResultsFormat, PrintStream, QueryProcContext)
2. On the one hand, it can be used to process SELECT queries and obtain the query result as a ResultSet object, which can then be consumed in whatever way you like. This functionality is provided by via the following functions.
   • executeSelectQuery(Query).
   • executeSelectQuery(Query, QueryProcContext)

To create a HeFQUINEngine object used HeFQUINEngineBuilder. When you do not need it anymore, make sure to call shutdown().

Technically, this is a wrapper around the Jena/ARQ query processing machinery into which the query processor of this engine is integrated.

Field Summary

Fields

Modifier and Type	Field	Description
protected final ExecutorService	execServiceForPlanTasks
protected final FederationAccessManager	fedAccessMgr
protected final FederationCatalog	fedCatalog
protected final QueryProcessor	qProc
protected boolean	wasShutDown

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	HeFQUINEngine(FederationCatalog fedCatalog, FederationAccessManager fedAccessMgr, QueryProcessor qProc, ExecutorService execServiceForPlanTasks)

Method Summary

Modifier and Type	Method	Description
protected QueryProcessingStatsAndExceptions	_execAndPrint(org.apache.jena.query.Query query, org.apache.jena.sparql.resultset.ResultsFormat outputFormat, PrintStream output, QueryProcContext ctx)
protected void	_execNonSelectQuery(org.apache.jena.query.QueryExecution qe, org.apache.jena.sparql.resultset.ResultsFormat outputFormat, PrintStream output)
protected void	_execSelectQuery(org.apache.jena.query.QueryExecution qe, org.apache.jena.sparql.resultset.ResultsFormat outputFormat, PrintStream output)
protected org.apache.jena.query.QueryExecution	_prepareExecution(org.apache.jena.query.Query query)
QueryProcessingStatsAndExceptions	executeQueryAndPrintResult(org.apache.jena.query.Query query, org.apache.jena.sparql.resultset.ResultsFormat outputFormat, PrintStream output)	Executes the given query and prints the result to the given output, in the given format.
QueryProcessingStatsAndExceptions	executeQueryAndPrintResult(org.apache.jena.query.Query query, org.apache.jena.sparql.resultset.ResultsFormat outputFormat, PrintStream output, QueryProcContext ctx)	Executes the given query and prints the result to the given output, in the given format.
QueryProcessingOutput	executeSelectQuery(org.apache.jena.query.Query query)	Assuming the given query is a SELECT query, this function executes that query and returns an output object from which the query result can be obtained as a ResultSet.
QueryProcessingOutput	executeSelectQuery(org.apache.jena.query.Query query, QueryProcContext ctx)	Assuming the given query is a SELECT query, this function executes that query and returns an output object from which the query result can be obtained as a ResultSet.
FederationAccessStats	getFederationAccessStats()	Returns a current version of the statistics collected by the FederationAccessManager that this engine uses.
QueryProcContextBuilder	getQueryProcContextBuilder()	Returns a newly-created QueryProcContextBuilder that can be used to create customizable QueryProcContext objects to be used when calling any of the following functions of this HeFQUINEngine.
void	shutdown()	Shuts down the relevant components used by this engine, such as the federation access manager and the query processor component.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

fedCatalog

protected final FederationCatalog fedCatalog

fedAccessMgr

protected final FederationAccessManager fedAccessMgr

qProc

protected final QueryProcessor qProc

execServiceForPlanTasks

protected final ExecutorService execServiceForPlanTasks

wasShutDown

protected boolean wasShutDown

Constructor Details

HeFQUINEngine

protected HeFQUINEngine(FederationCatalog fedCatalog,
 FederationAccessManager fedAccessMgr,
 QueryProcessor qProc,
 ExecutorService execServiceForPlanTasks)

Method Details

getQueryProcContextBuilder

public QueryProcContextBuilder getQueryProcContextBuilder()

Returns a newly-created QueryProcContextBuilder that can be used to create customizable QueryProcContext objects to be used when calling any of the following functions of this HeFQUINEngine.

• executeQueryAndPrintResult(Query, ResultsFormat, PrintStream, QueryProcContext)
• executeSelectQuery(Query, QueryProcContext)

The returned QueryProcContextBuilder can be used multiple times (i.e., to created multiple QueryProcContext objects), but notice that a QueryProcContext object can also be used multiple times.

Returns:

a newly-created QueryProcContextBuilder

executeQueryAndPrintResult

public QueryProcessingStatsAndExceptions executeQueryAndPrintResult(org.apache.jena.query.Query query,
 org.apache.jena.sparql.resultset.ResultsFormat outputFormat,
 PrintStream output)
                                                             throws UnsupportedQueryException,
IllegalQueryException

Executes the given query and prints the result to the given output, in the given format.

Parameters:

query - - the query to be executed

outputFormat - - the format to be used for writing the result (

invalid reference

ResultsFormat.FMT_TEXT

may be used as a default)

output - - the output stream to which the result shall written

Throws:

UnsupportedQueryException - thrown if the given query uses features that are not supported by HeFQUIN; the message of the exception describes the specific limitation and can be passed directly to the user.

IllegalQueryException - thrown if the given query is invalid; the message of the exception describes the issue and can be passed directly to the user.

executeQueryAndPrintResult

public QueryProcessingStatsAndExceptions executeQueryAndPrintResult(org.apache.jena.query.Query query,
 org.apache.jena.sparql.resultset.ResultsFormat outputFormat,
 PrintStream output,
 QueryProcContext ctx)
                                                             throws UnsupportedQueryException,
IllegalQueryException

Executes the given query and prints the result to the given output, in the given format.

Parameters:

query - - the query to be executed

outputFormat - - the format to be used for writing the result (

invalid reference

ResultsFormat.FMT_TEXT

may be used as a default)

output - - the output stream to which the result shall written

ctx - - object that contains options to be considered during query processing; to create such an object, use the QueryProcContextBuilder that can be obtained via getQueryProcContextBuilder()

Throws:

UnsupportedQueryException - thrown if the given query uses features that are not supported by HeFQUIN; the message of the exception describes the specific limitation and can be passed directly to the user.

IllegalQueryException - thrown if the given query is invalid; the message of the exception describes the issue and can be passed directly to the user.

executeSelectQuery

public QueryProcessingOutput executeSelectQuery(org.apache.jena.query.Query query)
                                         throws UnsupportedQueryException,
IllegalQueryException

Assuming the given query is a SELECT query, this function executes that query and returns an output object from which the query result can be obtained as a ResultSet.

Parameters:

query - - the query to be executed; it needs to be a SELECT query

Throws:

UnsupportedQueryException - thrown if the given query uses features that are not supported by HeFQUIN; the message of the exception describes the specific limitation and can be passed directly to the user.

IllegalQueryException - thrown if the given query is invalid; the message of the exception describes the issue and can be passed directly to the user.

executeSelectQuery

public QueryProcessingOutput executeSelectQuery(org.apache.jena.query.Query query,
 QueryProcContext ctx)
                                         throws UnsupportedQueryException,
IllegalQueryException

Assuming the given query is a SELECT query, this function executes that query and returns an output object from which the query result can be obtained as a ResultSet.

Parameters:

query - - the query to be executed; it needs to be a SELECT query

ctx - - object that contains options to be considered during query processing; to create such an object, use the QueryProcContextBuilder that can be obtained via getQueryProcContextBuilder()

Throws:

UnsupportedQueryException - thrown if the given query uses features that are not supported by HeFQUIN; the message of the exception describes the specific limitation and can be passed directly to the user.

IllegalQueryException - thrown if the given query is invalid; the message of the exception describes the issue and can be passed directly to the user.

getFederationAccessStats

public FederationAccessStats getFederationAccessStats()

Returns a current version of the statistics collected by the FederationAccessManager that this engine uses.

This function simply calls FederationAccessManager.getStats() and forwards the returns stats.

shutdown

public void shutdown()

Shuts down the relevant components used by this engine, such as the federation access manager and the query processor component.

_execAndPrint

protected QueryProcessingStatsAndExceptions _execAndPrint(org.apache.jena.query.Query query,
 org.apache.jena.sparql.resultset.ResultsFormat outputFormat,
 PrintStream output,
 QueryProcContext ctx)
                                                   throws UnsupportedQueryException,
IllegalQueryException

Throws:

UnsupportedQueryException

IllegalQueryException

_prepareExecution

protected org.apache.jena.query.QueryExecution _prepareExecution(org.apache.jena.query.Query query)
                                                          throws UnsupportedQueryException,
IllegalQueryException

Throws:

UnsupportedQueryException

IllegalQueryException

_execSelectQuery

protected void _execSelectQuery(org.apache.jena.query.QueryExecution qe,
 org.apache.jena.sparql.resultset.ResultsFormat outputFormat,
 PrintStream output)
                         throws Exception

Throws:

Exception

_execNonSelectQuery

protected void _execNonSelectQuery(org.apache.jena.query.QueryExecution qe,
 org.apache.jena.sparql.resultset.ResultsFormat outputFormat,
 PrintStream output)
                            throws Exception

Throws:

Exception