TopBraid SuiteTopBraid ComposerTopBraid LiveTopBraid Ensemble

TopBraid 3.0 has introduced SPARQLMotion 2.0 as well as SPIN. SPARQLMotion 2.0 is a greatly improved version that is now fully integrated with SPIN as its foundation.

Before you can use SPARQLMotion 2.0, you must make sure that you have the correct versions of the SPARQLMotion system ontologies such as sparqlmotion.owl. In order to do that, please re-run the RDF/OWL ontology library wizard on your TopBraid/TBC project. This will replace your local copies with those bundled with the TopBraid distribution.

We have made all reasonable efforts to make sure that the transition from 1.x to 2.x is as painless as possible. In fact, the vast majority of existing SPARQLMotion scripts will still work unmodified with the new engine. A few differences may require your attention though:

• Representation of SPARQL queries
• Visible internal changes to SPARQLMotion
• Function calls as SPARQLMotion modules
• User-defined functions and Web Services

Representation of SPARQL queries

SPARQLMotion 2.0 is based on SPIN in a number of ways. Most notably, it is now using the SPIN SPARQL Syntax to store SPARQL queries. SM 1.x was storing SPARQL queries in textual format. This was error prone when things got moved around or renamed. The use of the SPIN syntax makes sure that queries are stored in RDF, independent of things like namespace prefixes. It becomes also possible to query the structure of queries like any other RDF data structure. For example, you can now use the Find References feature of TBC to find all queries that mention a given resource.

This change will not have a huge impact on existing SPARQLMotion scripts - the engine will continue to be able to handle queries stored as strings. However, any newly entered SPARQL query will be stored in SPIN notation. You can migrate your existing scripts to the new format if you like by re-asserting them. For example, enter a space character somewhere in your query and hit OK to turn it into SPIN syntax. You should see a star icon to the left of SPIN queries. Note that SPIN currently only supports comments (# lines) at the beginning of a query - all other comments inside the query will be lost in the conversion.

Visible internal changes to SPARQLMotion

The SPARQLMotion module classes are now instances of sm:Module, and can be found as subclasses of sm:Modules which is a subclass of spin:Modules. In previous versions, sm:Module was the root class - now it's a metaclass.

The attributes of a SPARQLMotion module type are now represented as spin:constraints of type spl:Argument. In previous versions they were represented as owl:Restrictions. The cardinalities and value types (ranges) of these arguments are now bundled together with their documentation and default values in a single, SPIN-compliant object. The old solution with owl:Restrictions was a hack that could not really follow commont OWL modeling conventions.

Function calls as SPARQLMotion modules

In addition to calling SPARQL functions inside SPARQL queries, SPARQLMotion 1.x made it possible to use certain SPARQL functions (smf, fn and afn namespaces) as modules in a SM script. This has now been generalized, so that any SPARQL function (including SPIN functions) can be used as a module. The instantiation mechanism of such functions has not changed, but in the process of generalization, we have changed the variables that were used by the old SMF functions. So in case you have used any SMF function directly as a module, you will most likely have to change the property values in its configuration, e.g. from smf:... to sp:arg1 etc.

User-defined functions and Web Services

SPIN introduces a new mechanism for defining your own SPARQL functions from other SPARQL functions. In a nutshell, a SPIN function defines a list of arguments and a function body, which is itself another SPARQL query. When executed, the arguments will be passed into the body function. The very same mechanism is now used by SPARQLMotion for user-defined functions or Web Services. While in previous versions of SM, such functions and Web Services had different formats, SPARQLMotion 2.0 treats them exactly the same. As a result, any function can be used as Web Service and vice versa. Likewise, any function or Web Service can be used as a SPARQLMotion module in scripts.

To migrate existing SM 1.x Web Services to 2.0, you will need to go through the following steps:

1. Create a new subclass of spin:Functions, typically under one of the child classes of Functions to categorize them. This subclass will have the metaclass spin:Function as its type. The URL of the new subclass should be the same as the previous end module of your old service, i.e. you may have to rename the old module to some other URI first.
2. Assign the former end module of your service as sm:returnModule to your new Function.
3. For each sml:BindWithParameter module, create a spl:Argument and assign it as spin:constraint to the function class. To do so, pick a preferred order of your arguments and locate sp:arg1, sp:arg2 etc in the Properties tree. With your function class selected in the form, drag each of these properties, one by one, over the title of the spin:constraint widget on the form. This will ask you to create a template call using spl:Argument as the default choice and sp:arg1 pre-selected as predicate. Add comment, default value and value type as appropriate.
4. Once you have finished defining the Arguments, go to your script (the body of the service) and delete any modules of type spl:BindWithParameter. Instead, you will see your new spl:Arguments as nodes in your script graph. Connect these new argument nodes with the rest of your script using sm:next, the same way as your sml:BindWithParameter modules was defined before.

To verify that the service/function is working as expected, you should select Scripts > Refresh/Display SPARQLMotion Functions to make sure your function is known to the system. Then you can run it in various ways, e.g. in a SPARQL query in the SPARQL View, or as a Web Service through Maestro's built-in personal web server. In the latter case, note that the argument names will have changed.

If you have old 1.x user-defined SPARQLMotion functions, the migration works very similar as with Web Services.

1. Make your 1.x function a subclass of spin:Functions and assert spin:Function as its rdf:type.
2. Modify your script so that it ends with a subclass of sml:ReturnModules, typically sml:ReturnNode or sml:ReturnText.
3. Assert this new return module as the sm:returnModule of your function.
4. For each defined argument, convert its owl:Restriction to a spin:constraint of type spl:Argument.