SPARQLMotion Example
DBPediaCountryCapitals Service

Creating a Web service script. Scripts can be created by choosing Scripts > Create SPARQLMotion function/web service... from the top menu bar in TopBraid Composer-Maestro Edition. Enter a name for the function (which is used as the Web service identifier) and, optionally, provide names of arguments and choose a return type. Selecting OK will display the script in the Graph View (shown next).

Adding a module to a script. The wizard opens the Graph View for the SPARQLMotion script, with the return module specified in the wizard automatically created. A palette of SPARQlMotion modules appears to the left. A tool tip explanation is available by mousing over any module type in the palette. To add a new module, such as the sml:ConcatenateText module shown here, click on the module in the palette and click in the work area. To connect modules, click Add connection from the Editing tools part of the palette. Then click on the source, then target module. A sm:next property will be created, meaning that the source module executes before the target module in the script.

Script function generated by wizard. The Create SPARQLMotion function/web service... wizard creates a subclass of sm:Functions with the specified name. This SPIN function is the Web service identifier which is passed to the SPARQLMotion service with the id parameter (see 'id' parameters of the sample Web service URLs above). As shown in the screenshot below, you can navigate to it in the Classes tree and examine its definitions in a form. Function arguments are specified in the spin:constraint property. The sm:returnModule property is the URI of the last module executed in the script. The wizard will automatically create a new instance of the selected return module type and set the value of sm:returnModule.

Defining arguments passed to script. Arguments are defined by creating an instance of spin:constraint in the function class (see spin:constraint property in the Class Form). If you did not create arguments as part of Create SPARQLMotion function/web service wizard, use "Create from SPIN template..." in the form, as shown in the image to the right. This displays the SPIN template dialog shown here (this is the same dialog for adding arguments that is used in the wizard). Specify an argument using an existing property . The datatype property country is used here. The predicate will be bound to a variable named with the local name of the property, ?country in the example. Each instance of spin:constraint defines an Argument module in the SPARQLMotion script. Set the value type to the type required for the variable.

Create options (type: Concatenate Text). Performs a SPARQL SELECT query on the DBPedia SPARQL endpoint (specified in the SERVICE clause of the query). The query body is sent to the endpoint and returns bindings for ?countryName, the variable in the SELECT clause. Note that the red underline indicates that the script does not define any of these qnames. These are applied to their prefix definitions and sent to the endpoint, without being interpreted by the script (other than syntax checking). The script defines two prefixes, dbp: (http://dbpedia.org/property/) and dbpo: (http://dbpedia.org/ontology/). The query finds all members of dbpo:Country that define a value for the dbpo:capital property and a census value of greater than 200,000 (this is used to prune the list to more familiar countries, and can be omitted).

sml:ConcatenateText will take all bindings from the query results and create a string consisting of the binding for each query match with the text defined in sml:separator in between each binding. For example if the query result has two bindings for ?countryName, "Australia"@en and "Mexico"@en, then the result from sml:ConcatenateText is the string "Australia</option><option>Mexico</option><option>". The resulting text is used to define a set of options for an HTML Form tag that is used in the next module. Output from this module is bound to the variable text in sm:outputVariable, and is therefore available for the remainder of the script with the variable ?text.

DisplayListOfCountries_Return (type: Return Text). Creates a text response from the sml:text property and returns it to an HTTP client with the sml:mimeType set to text/html. The text body represents a template that defines an HTML document and substitutes the value bound to the variable ?text for {?text}. Note that ?text was bound in the previous module and defines a list of <option> tags. The result is a HTML form with a select tag consisting of country names queried from DBPedia.

This example defines a rundimentary Web page. The Return Text module can return any form of text, such as JSON, as supply the appropriate mime type for the client. For creating more complex Web pages, SPARQL Web Pages (SWP) is suggested.

Argument country (type: Argument). This module is created when the function is created (see Creating a Web service script) or when an argument is defined for the function class (see Defining arguments passed to script), and appears automatically in the script's Graph View. It takes an argument from a query string (or user input if executed in TopBraid Composer-ME) and binds it to a variable named ?country that can be used in the rest of the script.