Extending SPARQLMotion (for Programmers)

One of the strengths of SPARQLMotion is that it is based on a highly extensible framework. This means that SPARQLMotion scripts can be enriched with new functionality that is not built into the default environment. The SPARQLMotion execution engine embedded in the TopBraid Suite can be extended in numerous ways:

1. SPARQLMotion is a model-driven language: the language and the module libraries are themselves defined in OWL ontologies. This, for example, makes it possible to define your own module types by just subclassing the existing library classes. This works well in those cases where behavior can be derived from variations of existing implementations as shown in this example.
2. SPARQLMotion's execution engine API has a plug-in mechanism that enables Java programmers to add custom implementations.
3. SPARQLMotion is using the Jena SPARQL engine (ARQ) to execute SPARQL queries. Many SPARQLMotion modules are actually driven by SPARQL queries. Extensions to the SPARQL engine will be available to SPARQLMotion modules at run time. TopBraid includes various such extensions, such as the "tops" property functions (aka magic properties) and the LET/FILTER functions from the SPARQLMotion Functions Library. Java programmers can add other functions using the Jena API.
4. SPARQLMotion can be used to define new SPARQL LET/FILTER functions without any programming. This is illustrated in the UserDefinedFunction example.

Declaring new SPARQLMotion modules

Let's assume you want to add a completely new feature to SPARQLMotion such as an importer that takes a Word document and extracts RDF triples. In order to do that, create an empty OWL file that imports sparqlmotionlib. Then create a subclass of sm:Module. Ideally select at least one level down from sm:Module to specify whether we have an import, processing or export module. This will enable the visual TopBraid editor to present the new module in a meaningful category. Once you have defined your subclass, say, my:WordImportModule, it will show up in the pallette of the graphical editor and you can instantiate it in your scripts. In almost all cases, you will need to add properties to the class definition in a similar fashion to the standard module declarations. For example you may want to add an owl:cardinality = 1 restriction on the property sml:sourceFilePath to make sure that users have to enter a path to the Word document.

Creating SPARQLMotion module implementations

After you have declared the new module type in the ontology as described above, you need to implement a TopBraid plug-in. General information on how to implement plug-ins is available from the TopBraid Composer Plug-in Development Guide. If you don't have a thorough understanding of the Eclipse extension point mechanism yet, you should go through the exercises in that guide. The extension point you will use to create a new SPARQLMotion module type is org.topbraid.sparqlmotion.moduleTypes. Make sure that your plugin declares a dependency on org.topbraid.sparqlmotion to see this extension point. Instances of this extension point need to specify the URI of the module in the module ontology, e.g. http://my.com/sml#WordImportModule. Furthermore, they have to point to an implementation of org.topbraid.sparqlmotion.modules.IModule. Typically you should subclass org.topbraid.sparqlmotion.modules.impl.AbstractModule where you only need to overload the createGraph method: protected Graph createGraph(IProgressMonitor monitor) throws Throwable. (Disclaimer: This API is overall not 100% stable yet and the online JavaDoc may be not up-to-date.) The createGraph method can return any new Jena Graph instance, e.g. an empty graph that has been populated with RDF triples from the Word document. In addition to that, the method may query or modify the variable bindings starting with IModule.getContext(). More details on this API will follow once the API is stable enough. In the meantime don't hesitate to ask your questions on the TopBraid user forum.

Creating SPARQL (ARQ) extensions

Implementing approach 3. from the list above, programmers can add their own ARQ property functions to the execution engine. This is the most generic approach to reusable functionality because the SPARQL functions can be used in many places (including for example TopBraid Composer's SPARQL View). However they are platform-specific extensions that will not be available to other SPARQL engines such as those implemented by native Oracle etc. The Jena ARQ documentation is a good place to start. The main thing to keep in mind is that you need to tell TopBraid about these additional functions. Since TopBraid lives in the Eclipse ecosystem, it relies on the Eclipse class loading mechanism. In order to make sure that TopBraid/Eclipse will have access to the property functions from your plug-in, use the extension point org.topbraid.sparql.propertyFunctions. This must link the predicate's URI with the Java class (must be an implementation of com.hp.hpl.jena.sparql.pfunction.PropertyFunction).