3. Using the API

Query Answering

Creating QueryEngine

The ApplicationFactory takes a configuration file to prepare the system and create the application manager. Alternatively, you can apply programmatic configuration to embed the setup parameters in the code.

ApplicationManager appManager = 
  new ApplicationFactory().configure(CONFIG_FILE).createApplicationManager();

With the instance of ApplicationManager, we can construct the query engine that will serve query answering.

IQueryEngine queryEngine = appManager.createQueryEngine();

Starting QueryEngine

Before the query engine can serve its query answering service, you need to start the engine to open the connection resource.

queryEngine.start();

Query Answering Service

Once the engine is started, you can give a SPARQL query and the engine will evaluate it.

IQueryResult result = queryEngine.evaluate(INPUT_SPARQL);

Iterate QueryResult

The internal QueryResult is composed of a list of select names and a list of value-array. Use the next() method to check if the query result has more value-array and iterate over.

while (result.next()) {
  IValueList values = result.getValueList();
  // ...
  // processing values
}

Note that each value-array consists of IValue instances that can be either a Literal or URI. The difference between these two types is in the RDF resource concept, i.e., Literal is a typed-value and URI is an object-value.

IValue value = values.get(SELECT_NAME); // e.g., firstName
switch (value.getType()) {
  case IValue.LITERAL: // do something
  case IValue.URI: // do something else
  default: // error handling
}

QueryResult Handler

The API provides a query result handler interface IQueryResultHandler to hide the data processing details. The code below presents a simple handler that aggregates word frequency in the query result.

public class WordFrequencyHandler implements IQueryResultHandler
{
  private Map<String, Integer> mDictionary = new HashMap<String, Integer>();

  public Map<String, Integer> getWordFrequency()
  {
    return mDictionary;
  }

  @Override
  public void start(List<String> selectNames)
  {
    // NO-OP: Ignore this
  }

  @Override
  public void handleResultFragment(IValueList valueList)
  {
    String word = valueList.get("word").stringValue();
    int frequency = Integer.parseInt(valueList.get("counter").stringValue());
    if (mDictionary.containsKey(word)) {
      frequency = frequency + mDictionary.get(word);
    }
    mDictionary.put(word, frequency);     
  }

  @Override
  public void stop()
  {
    // NO-OP: Ignore this
  }
}

In the client code, use this handler when evaluating the input SPARQL query.

WordFrequencyHandler handler = new WordFrequencyHandler();
queryEngine.createQuery(INPUT_SPARQL).evaluate(handler);
Map<String, Integer> wordFrequency = handler.getWordFrequency();

Stopping QueryEngine

Use the stop() method to stop the engine and release the connection resources. You can call this method when closing the service or destroying the application.

queryEngine.stop();

RDB2RDF

Creating MaterializerEngine

By using the same ApplicationManager instance, you can create a materializer engine to supply data export service from database to RDF.

IMaterializerEngine materializer = 
  appManager.createMaterializerEngine().useNTriples();

You can parameterize the engine using methods useNTriples(), useTurtle(), useRdfXml() or useRdfJson() to choose export format into .n3, .ttl, .xml, .json, respectively.

Starting MaterializerEngine

Similar to the query engine, you need to start the engine first before using.

materializer.start();

Data Exporting Service

Supply the engine with the output file and it will materialize the data in the mapping files.

materializer.materialize(FILE_OUTPUT); // e.g. new File("output.n3");

Stopping MaterializerEnginer

Again, similar to the query engine, you need to stop the engine to release the resources and prevent memory leaking.

materializer.stop();