TopBraid Application Development Quickstart Guide Version 3.3 October 27, 2010
2 TopBraid Application Development Quickstart Guide Introduction
TopBraid Application Development Quickstart Guide TOC 3 Contents Chapter 1: Introduction... 5 1.1 Documentation conventions... 6 1.2 Note for Macintosh users...6 Chapter 2: Using TopBraid Composer...7 2.1 Basic layout... 8 2.2 Navigating and editing a graph...9 2.3 Adding instances... 13 2.4 Querying the data with the SPARQL query language...14 2.5 Prefixes, preferences, and online help...16 Chapter 3: Writing new SPARQL functions with SPIN...19 3.1 Calling built-in functions...20 3.2 Defining your own functions...20 Chapter 4: Creating and running a SPARQLMotion script... 25 4.1 Creating the script... 26 4.2 Running it... 30 Chapter 5: Creating and running a semantic web service...31 5.1 Creating your script... 32 5.2 Defining the function to call...32 5.3 Creating the SPARQLMotion script... 33 5.4 Registering and calling your web service...35 Chapter 6: Creating a TopBraid Ensemble application... 37 6.1 TopBraid Ensemble: the basics... 38 6.2 Creating the sample application... 39 Chapter 7: Getting data from SPARQL endpoints and saving data in a spreadsheet...45 7.1 Retrieving data from a SPARQL endpoint...46 7.2 Saving data in a spreadsheet...46 Chapter 8: Calling a SPARQLMotion script from TopBraid Ensemble... 49 8.1 Defining the function to call...50 8.2 Creating the SPARQLMotion script... 50 8.3 Testing it...51 8.4 Taking it further...52
4 TopBraid Application Development Quickstart Guide TOC Chapter 9: Reading triples from a relational database...55 9.1 Getting the database driver...56 9.2 Configuring TopBraid to read a MySQL database...56 9.3 Reading the data with a SPARQLMotion script... 57 Chapter 10: Using XSLT in a semantic web application... 61 10.1 Creating XML... 62 10.2 Creating an XML version of SPARQL query results in a SPARQLMotion script...63 10.3 Applying an XSLT stylesheet in a SPARQLMotion script... 63 10.4 Taking it further...66 Chapter 11: Deploying your TopBraid applications on a TopBraid Live Enterprise server...67 11.1 Referencing your server... 68 11.2 Deploying apps to the server... 68 11.3 Installing TopBraid Ensemble Apps on the Enterprise Server...70
Chapter 1 Introduction Topics: Documentation conventions Note for Macintosh users TopBraid Composer (TBC) is the leading tool for creating and editing semantic web models and applications. Creating a model can be as simple as adding one or two customizations to a standard ontology such as SKOS or GoodRelations, and it can be simple to create and deploy applications that read from and write to a variety of local and remote data sources and perform simple or sophisticated manipulation of the data in between. This book, which is based on the How to postings on the TopQuadrant weblog, will get you started writing those applications. The premier version of TopBraid Composer, the Maestro Edition (TBC-ME), gives you all the application development power of TopBraid Suite. You can download the 30-day evaluation version of TBC-ME from the download page on TopQuadrant's website and try every example in this book except for the one in the last chapter, which describes How to deploy your TopBraid applications on a TopBraid Live Enterprise server so that other people on your network can use your applications. For that, you'll need access to a TopBraid Live Enterprise server. The TopBraid Suite builds on the W3C RDF, SPARQL, and OWL standards. The examples in this book assume that you know the basics of RDF for example, that the primary unit of information is a triple, which consists of a subject, a predicate, and an object, and that subjects and predicates must be URIs while an object can be a URI or a literal value (typically a string, but sometimes of a different data type such as an integer, date, or boolean value). You don't have to know any SPARQL to work through the examples in this book, because the exercises provide you with all the SPARQL queries you need to copy and paste into your sample applications, but the more SPARQL you know the more you'll be able to appreciate and build on those examples. These examples use none of the advanced features of the RDF Schema (RDFS) or OWL standards other than the occasional declaration of some classes and properties associated with those classes. Most of the examples build on each other in order, so if you skip ahead you may find a brief treatment of a series of steps that are covered in more detail in an earlier chapter. Usually, a link will point you to the more detailed coverage, but it's best to work through the exercises in order. (Exceptions are the chapters on reading relational data and using XSLT, which may not be as useful to people who are new to those tools.) When you're finished, you'll probably have lots of ideas for your own things to build with the SPARQLMotion building blocks. Let us know what you come up with!
6 TopBraid Application Development Quickstart Guide Introduction 1.1 Documentation conventions Class, property and individual names are written in a sans serif font like this. Names for user interface widgets and menu options are presented in a style like this. Information to be entered by the user is shown in a monospaced font like this. Exercises and required tutorial steps are presented like this: 1. Execute the first step. 2. Then, execute the second step. 3. Here is the third step to carry out. Tips and suggestions for using TBC ontologies are presented with this icon. Potential pitfalls and warnings are presented next to this icon. General notes use this icon. 1.2 Note for Macintosh users This book and its screen shots were prepared with TopBraid Composer running under Windows. Mac users will find two small differences in the user interface: Under Windows, tree-like screen widgets showing the structure of directories and files, classes and subclasses, or properties and subproperties have little plus signs next to nodes that can be expanded to see their child nodes. The Mac uses a small gray triangle instead of a plus sign to show which nodes can be expanded. The Preferences menu selection is found on the Window menu in the Windows version of TopBraid Composer and on the TopBraid Composer menu in the upper-left of a Mac screen. TopQuadrant, Inc www.topquadrant.com Corporate Office Alexandria, VA 330 John Carlyle Street Suite 180 Alexandria, VA 22314-5760 Phone: +1 703.299.9330 Fax: +1 703.299.8330 Development Office Mountain View, CA 201 San Antonio Circle Building B, Suite 230 Mountain View, CA 94040-1254
Chapter 2 Using TopBraid Composer Topics: Basic layout Navigating and editing a graph Adding instances Querying the data with the SPARQL query language Prefixes, preferences, and online help TopBraid Composer is a semantic web modeling and application development environment available for Windows, Mac, and Linux. It's built on top of Eclipse, an open source Integrated Development Environment popular with software developers. Eclipse is particularly popular for Java development, but built-in features and free and commercial plugins can turn it into a sophisticated editor for XML files, UML models, and many popular programming languages besides Java. TBC adds features that let you edit and navigate OWL and RDFS models and data associated with those models, as well as features to let you visually assemble scripts that can read RDF from and write to a variety of sources. These include many sources that you might not associate with RDF, such as Excel spreadsheets and relational databases. You can specify complex manipulations of data for your application to perform by clicking, dragging, and filling out dialog boxes. The TopBraid Live Personal Server included with TBC builds on Eclipse's Jetty web server to let you build and test web-based applications around these models. You can then deploy your applications on the TopBraid Live Enterprise Server for use by anyone with a web browser, whether they have TBC or not. This chapter will tell you just enough about TBC to help you navigate around it and use its features as you work through the remaining chapters of the book. For a more detailed introduction with a good introduction, to the creation of ontologies, see TopBraid Composer Getting Started Guide.
8 TopBraid Application Development Quickstart Guide Using TopBraid Composer 2.1 Basic layout When you start up TBC, you'll see a collection of specialized panes known in Eclipse as views. A collection of views grouped together for a specific task, such as editing programs in a particular language or, in TBC's case, editing semantic web models and applications, is known as a perspective. The Navigator view, shown in the lower-left of the following illustration, lets you navigate among projects, folders, and files in your workspace. Because this is such a common need in nearly any use of Eclipse, you'll find the Navigator view in almost all perspectives and Eclipse-based products. On the other hand, the Classes view in the upper-left and the Properties view in the upper-right of the same picture are very specific to the needs of semantic web application development, because they let you view, add, and edit class and property definitions. As you learn to use TBC, you'll become very familiar with these views. The middle of the lower part of the image shows the Imports view and tabs for several other views behind it such as Instances and Domain. Clicking one of these tabs will bring its view to the front, and dragging a tab moves its view to another place on the screen. If you're doing a lot of work in a particular view and it doesn't have enough room to see what you're doing, double-click its tab to maximize its view within the TBC window, and double-click the tab again when you're ready to return the view to its original size. If you only want to make it a little bigger, drag the view's edges to resize it. The "X" on the right side of a selected view's tab lets you close that view if you want to reduce the clutter. If you want to re-open a view you closed or hear about a useful view and don't see it, select Show View from the Window menu. This displays a cascade menu with a list of additional views that you can add. An Other choice at the TopQuadrant, Inc www.topquadrant.com Corporate Office Alexandria, VA 330 John Carlyle Street Suite 180 Alexandria, VA 22314-5760 Phone: +1 703.299.9330 Fax: +1 703.299.8330 Development Office Mountain View, CA 201 San Antonio Circle Building B, Suite 230 Mountain View, CA 94040-1254
TopBraid Application Development Quickstart Guide Using TopBraid Composer 9 bottom of that menu leads you to an even more extensive list to choose from. If you don't see an Error Log view in the currently displayed perspective, that would be a good one to select on the cascade list to add to the current views, because it shows both error and warning messages that can be useful during application development. 2.2 Navigating and editing a graph A collection of RDF data is often called a graph. It can store class and property information about data being stored, or the data itself, or both. Many of the graphs distributed with TBC are there for you to import into the ontologies you create to give you a head start on the structure of your ontologies if you want to build on a standard such as SKOS or FOAF, and also to provide you with hooks that invoke application development features such as user-defined functions and SPARQL Inferencing Notation (SPIN) rules. When you first start up TBC, you'll see that a single project in the Navigator view called "TopBraid" has several folders with commonly used models, example data, and other ontologies that will speed your ontology and application development. (If you don't see these folders, click the plus sign next the TopBraid project.) If the kennedys.rdf model is not already selected, as shown in the screen shot above, double-click the kennedys.rdf model in the TopBraid project's Examples folder to open it. When you double-click a file in the Navigator view to open it, Eclipse automatically calls the appropriate editor program for that file. If you double-clicked a file named hello.java, Eclipse would open the file in a Java programming editor. To use an editor other than the default for example, if you want to open an XML file or an Excel spreadsheet as RDF triples instead of with a more traditional editor for those file types right-click the file's icon in the Navigator and select from the choices (in this case, Open With->TopBraid) from the cascade menu. If you edit and save a file in one of your projects with a non-eclipse editor, Eclipse may not know about the changes. Tell it to refresh its view of the file or files by right-clicking the file or its containing folder in the Navigator and picking Refresh. Let's create a new project. 1. Pick New from the File menu and you'll see that the cascade menu offers Project... as one of the choices. (It also offers choices of file types that you can create with TopQuadrant to put in your project, so we'll be coming back to this menu shortly.) Select Project... TopQuadrant, Inc www.topquadrant.com Corporate Office Alexandria, VA 330 John Carlyle Street Suite 180 Alexandria, VA 22314-5760 Phone: +1 703.299.9330 Fax: +1 703.299.8330 Development Office Mountain View, CA 201 San Antonio Circle Building B, Suite 230 Mountain View, CA 94040-1254
10 TopBraid Application Development Quickstart Guide Using TopBraid Composer 2. Click the plus sign next to General on the New Project dialog box, click on Project under that, and click the Next button. 3. Enter TestProject in the Project name field and click the Finish button. Your new project will appear in the Navigator view above the TopBraid project. We're going to add an ontology and some instance data to that project, but instead of creating an ontology from scratch, we'll reduce our work by taking advantage of an existing standard: SKOS, the W3C standard Simple Knowledge Organization System ontology used for controlled vocabularies and thesaurii. SKOS is defined using the OWL standard to describe classes of vocabulary terms and their possible relationships, and taxonomy and thesaurus vocabularies that use these classes and relationships can interoperate with each other much more easily than vocabularies defined using the proprietary formats commonly used by vocabulary editing tools. (To draw an analogy to XML, OWL is like the DTD or schema language, SKOS is like the schema itself for example, Docbook or DITA and a taxonomy of animals described using SKOS is like a document conforming to the Docbook schema.) With your TestProject selected in the Navigator view, select New from the File menu, and then instead of picking Project... like before, pick RDF/OWL File. On the Create RDF/OWL File dialog box, replace "unnamed0" in the Base URI field with SKOSTest. You'll see this added automatically to the File name field as you do so. In the Initial imports field, check SKOS. We'll see the effect this has shortly. TopQuadrant, Inc www.topquadrant.com Corporate Office Alexandria, VA 330 John Carlyle Street Suite 180 Alexandria, VA 22314-5760 Phone: +1 703.299.9330 Fax: +1 703.299.8330 Development Office Mountain View, CA 201 San Antonio Circle Building B, Suite 230 Mountain View, CA 94040-1254
TopBraid Application Development Quickstart Guide Using TopBraid Composer 11 Click the Finish button, and TBC will create the file in the TestProject project and open it for you: You can close the file by clicking the X on the SKOSTest.n3 tab or by picking Close from the File menu. After closing it, you can reopen it using the File menu or by double-clicking the file in the Navigator view. With your SKOSTest.n3 file open, click the Imports tab in the bottom middle of the screen if it's not in the front of that group of views. It shows that the SKOS core ontology has been imported into the ontology you've created TopQuadrant, Inc www.topquadrant.com Corporate Office Alexandria, VA 330 John Carlyle Street Suite 180 Alexandria, VA 22314-5760 Phone: +1 703.299.9330 Fax: +1 703.299.8330 Development Office Mountain View, CA 201 San Antonio Circle Building B, Suite 230 Mountain View, CA 94040-1254
12 TopBraid Application Development Quickstart Guide Using TopBraid Composer because you clicked the SKOS checkbox in the Initial imports field when you first created your file. If you hadn't checked that, you could import the file by opening up the TopBraid project's Common folder in the Navigator view and then dragging the skos-core.rdf file from there to the SKOSTest.n3 Imports tab. Other files that you'll be importing in this book's exercises do more than define ontology classes and properties, like skos-core.rdf does. Many define functions and script modules whose availability will make your application development go much more quickly. Let's look more closely at what gets imported with skos-core.rdf. Click the Classes tab in the upper-left of your screen if it's not the front view in that section, and then click the plus signs next to owl:thing and skos:collection to expand the class tree. Feel free to resize the Classes view. This shows that the SKOS ontology that you imported declares Collection, Concept, and ConceptScheme classes as subclasses of owl:thing and an OrderedCollection class as a subclass of Collection. The little icons in the view's upper-right let you add and delete classes; mouse over them for descriptions of what they do. Like many other views, the Classes view also has a little icon of a white triangle pointing down which displays the context menu of relevant actions when you click it. The Properties view in the upper-right of the TBC screen lists properties declared for this ontology. Click the plus sign next to skos:semanticrelation and you'll see its subproperties, and then click their plus signs to see their subproperties. If you're familiar with how SKOS organizes vocabulary terms, you'll see the properties it uses to define relationships between concepts, such as "broader" to show that the concept "mammal" is a broader term for "dog" (because the class of all dogs is a subset of the class of all mammals) or the "related" property, which can show that the concept "doghouse" is related to the concept "dog" without having a broader or narrower relationship to the term. Let's say that your business wants to use the SKOS standard to store controlled vocabularies, but along with the standard properties that get assigned to each concept, you want to add a Control Number property that is unique to your business's operations. Click the Properties view's white triangle to display its menu and note the choices there, along with the icons next to the triangle that provide shortcuts to these functions. If you picked Create rdf:property, you could add a controlnumber property for use in your ontology. With that one simple addition, you would turn SKOSTest.n3 into a customized version of the SKOS standard. (The other three "Create" menu choices let you define more specialized kinds of properties.) You can also add brand-new classes, or subclasses of existing SKOS classes, all by clicking, dragging, and filling out dialog boxes. Note that common naming style is to begin class names such as Concept with upper-case letters and property names such as controlnumber with lower-case letters. TopQuadrant, Inc www.topquadrant.com Corporate Office Alexandria, VA 330 John Carlyle Street Suite 180 Alexandria, VA 22314-5760 Phone: +1 703.299.9330 Fax: +1 703.299.8330 Development Office Mountain View, CA 201 San Antonio Circle Building B, Suite 230 Mountain View, CA 94040-1254
TopBraid Application Development Quickstart Guide Using TopBraid Composer 13 2.3 Adding instances Click the Instances view's tab to bring it to the front of the views in the lower-middle of your screen, and then click the yellowish-brown circle next to skos:concept in the Classes window. If your graph had any instances of this class, they would then be listed in the Instances view, but so far you don't have any. To create one, click this view's white triangle to display its menu and pick Create Instance. (Note also how this menu shows which icons next to the triangle are shortcuts to the menu's choices.) In the Create skos:concept dialog box, enter Mammal in the Name of new instance field. Click the OK button, and you'll see it appear in the Instances view. You'll also see a Resource Form appear for your new instance with various properties that you could set for it. Before looking closely at this form, create another Concept instance called Dog, and then your screen should look like this: While watching the Resource Form in the middle of the screen, click the yellowish-brown circle next to skos:concept in the Classes view, and then click the purple diamond next to Dog in the Instances view. Each time you select a class or an instance, you'll see that the form changes to let you edit properties of the resource that you selected. You don't have to view a form representation other tabs at the bottom of that area let you view the resource in other ways, and we'll see with SPARQLMotion scripts how a graph representation can be especially useful but for now we'll stay with the Form tab. With the Dog instance selected at the bottom, let's add some property values. First, we'll indicate that Dog has a broader value of Mammal. Click the white context menu triangle next to skos:broader on the Dog resource's form to display the property's context menu and pick Add empty row. A blank appears for you to fill out. TopQuadrant, Inc www.topquadrant.com Corporate Office Alexandria, VA 330 John Carlyle Street Suite 180 Alexandria, VA 22314-5760 Phone: +1 703.299.9330 Fax: +1 703.299.8330 Development Office Mountain View, CA 201 San Antonio Circle Building B, Suite 230 Mountain View, CA 94040-1254
14 TopBraid Application Development Quickstart Guide Using TopBraid Composer In the SKOS ontology, the skos:broader property (and others) are defined with a domain and range of Concept. This means that if resource X has a skos:broader value of Y, then both X and Y are concepts (that is, instances of the Concept class). To put this in taxonomy terms, a given node's "broader" relationship can't refer to just anything; it must refer to another defined concept. Built-in features of TBC and the applications you build with it make it easier to ensure that domain and range specifications are enforced, which means that your application's end users will have an easier time entering appropriate values. To see this in action, enter the letters Mam in the blank that appeared when you picked skos:broader. A red border will appear around the field, showing that "Mam" is not a valid value. Now press Ctrl+space, and TBC's completion feature fills in the rest for you, because it knows that "Mammal" is the only valid value that begins with the letters that you typed, and the red border becomes a black border. The black border and the little Ok that appears to the right show that you're not done yet perhaps several valid values begin with the letters "Mammal", so you need to show that you're done entering data in this field by either clicking on Ok or pressing the Enter key. Do one of these and you'll see the black border become a gray border. (To save your work, pick Save from the File menu at the top of the screen.) It's a common mistake when using an Eclipse application to type a value into a field but not to finish the text entry by pressing the Enter key or clicking Ok, and then the system doesn't really know about the new value. When things don't behave the way you expected, check whether any fields are waiting for you to finish some data entry with this step. Let's look at another way to add a value. Click the context menu triangle to the right of the Mammal value that you entered and pick Delete to remove it. Next, click the white triangle to the right of the skos:broader property name again, but this time, instead of picking Add empty row like before, pick Add existing, which tells TBC that you want to pick an appropriate existing value from a dialog box. That dialog box appears, showing all the defined Concept instances: Pick Mammal on the right, click the OK button, and you'll see it appear as the skos:broader value. While some properties such as skos:broader are connected to specific classes using domain specifications, others can be used with a wide variety of classes, especially the rdfs:label and rdfs:comment properties. To add an rdfs:comment value to the Dog Concept, drag rdfs:comment from the Properties view on the right onto the Dog Resource form, and a blank will appear for you to fill out. Enter any comment you like and press Enter or click Ok next to the field. 2.4 Querying the data with the SPARQL query language TopQuadrant, Inc www.topquadrant.com Corporate Office Alexandria, VA 330 John Carlyle Street Suite 180 Alexandria, VA 22314-5760 Phone: +1 703.299.9330 Fax: +1 703.299.8330 Development Office Mountain View, CA 201 San Antonio Circle Building B, Suite 230 Mountain View, CA 94040-1254
TopBraid Application Development Quickstart Guide Using TopBraid Composer 15 Click the SPARQL view's tab in the lower-middle of the screen to bring it to the front. It has two sections: a Query Editor tab on the left and a results pane. There's already a default query in the query editor, so click the green "Execute SPARQL" arrow above the result section and TBC will run that query. In a SPARQL query, a term beginning with a question mark is a variable. In this query, the position of the two variables in the triple pattern show that they represent the subject and object of a triple. (The names used for the variables make this even clearer, but you can use any variable names you like.) This query says to list all the? subject and?object values where?subject is a subclass of?object, and with the SKOS library that you've imported, there are a lot of subclass/class relationships. There are so many, in fact, that they're jammed pretty tightly into that small space, so double-click the SPARQL tab to expand its view to the whole TBC window: (When you're ready to use other TBC views, double-click the SPARQL tab again to return its view to its original size.) Replace the default query with the following one, which uses shorter variable names to ask for the subject, predicate, and object of any triples where the subject has an rdf:type of skos:concept: SELECT?s?p?o WHERE {?s?p?o.?s rdf:type skos:concept. } Click the green arrow (or press Ctrl+Enter while your cursor is still in the SPARQL editor window) and you'll see all the information about the two SKOS concepts that you defined earlier. In much of your TopBraid development, you'll add SPARQL queries to class definitions, SPARQLMotion modules, and other places. The SPARQL view for querying the currently displayed graph is especially handy for trying out queries before you add them somewhere in your application. And remember, TBC supports all the Jena extensions to the W3C SPARQL standard and adds a few of its own. In the next chapter, in addition to learning about some of these functions, you'll learn how you can define and call your own SPARQL functions. If you misspell rdf:type or skos:concept when you enter the query above, you'll see a red squiggly line under it. Like the dynamic spell checking feature in many word processors, TBC does this for terms that it doesn't recognize (in this case, for properties or classes not defined in the ontology currently being viewed) to help you avoid typos. TopQuadrant, Inc www.topquadrant.com Corporate Office Alexandria, VA 330 John Carlyle Street Suite 180 Alexandria, VA 22314-5760 Phone: +1 703.299.9330 Fax: +1 703.299.8330 Development Office Mountain View, CA 201 San Antonio Circle Building B, Suite 230 Mountain View, CA 94040-1254
16 TopBraid Application Development Quickstart Guide Using TopBraid Composer 2.5 Prefixes, preferences, and online help If you've used SPARQL before, you'll know that namespace prefixes must be declared before they're used. How did TBC know which namespaces rdf: and skos: referred to in the query above? You can see which prefixes are defined for a given ontology in the overview information about the ontology. To display this overview information, click the little house icon at the top of the screen. The resource form will show you information about the SKOSTest ontology that you've defined, and a new Overview tab will appear at the bottom of the form. Click that tab and you'll see a table of all the namespace prefixes defined for this ontology: These are the prefixes that you can use in the SPARQL view and in all components of applications built with this ontology. You can click on a prefix or namespace URL on the table to edit it, and the buttons to the right of the table let you add, delete, and do more with these mappings of namespace prefixes to URLs. Prefix assignments shown in gray on the table are from ontologies imported into this one, so you can't edit them from within the currently open ontology. Much of Eclipse and TBC can be customized. Pick Preferences from the Window menu (or, on a Macintosh, from the TopBraid Composer menu in the upper-left of your screen) and you'll see this dialog box: TopQuadrant, Inc www.topquadrant.com Corporate Office Alexandria, VA 330 John Carlyle Street Suite 180 Alexandria, VA 22314-5760 Phone: +1 703.299.9330 Fax: +1 703.299.8330 Development Office Mountain View, CA 201 San Antonio Circle Building B, Suite 230 Mountain View, CA 94040-1254
TopBraid Application Development Quickstart Guide Using TopBraid Composer 17 It lets you pick different categories of things to set, and some of the categories have subcategories. In the illustration, the TopBraid Composer Forms category is selected, and the right side of the dialog box shows some of the Formrelated settings that you can modify. Try exploring other categories, especially the General one, to see the kinds of things that you can customize. TopBraid Composer includes extensive online help. Pick Help Contents from the Help menu and you'll see a new window showing the main categories of help for your copy of Eclipse: TopQuadrant, Inc www.topquadrant.com Corporate Office Alexandria, VA 330 John Carlyle Street Suite 180 Alexandria, VA 22314-5760 Phone: +1 703.299.9330 Fax: +1 703.299.8330 Development Office Mountain View, CA 201 San Antonio Circle Building B, Suite 230 Mountain View, CA 94040-1254
18 TopBraid Application Development Quickstart Guide Using TopBraid Composer Expand the TopBraid Composer section of the help panel's table of contents and you'll find plenty of places to learn more about various aspects TBC. Remember that this help is always here as you continue on in this book to learn more about developing semantic web applications. TopQuadrant, Inc www.topquadrant.com Corporate Office Alexandria, VA 330 John Carlyle Street Suite 180 Alexandria, VA 22314-5760 Phone: +1 703.299.9330 Fax: +1 703.299.8330 Development Office Mountain View, CA 201 San Antonio Circle Building B, Suite 230 Mountain View, CA 94040-1254
Chapter 3 Writing new SPARQL functions with SPIN Topics: Calling built-in functions Defining your own functions This chapter shows how you can define your own functions using the SPARQL Inferencing Notation, which is an important building block for many of the techniques that we'll learn about in later chapters. This material is excerpted from the "Getting Started with SPIN" (pdf) document, which is available for you to download. The complete "Getting Started with SPIN" document also covers inferencing, constructors, constraints, and more. Before we cover the definition of new functions, let's review the calling of functions in TopBraid, because there are so many useful ones available to you.
20 TopBraid Application Development Quickstart Guide Writing new SPARQL functions with SPIN 3.1 Calling built-in functions The "TopBraid SPARQLMotion Functions Library" page of TopBraid Composer's online help lists over 70 functions available for you to call from your applications, including string, mathematical, logical, and ontology functions. Because TopBraid Composer uses the Jena SPARQL engine, it supports the LET keyword for assignment of variables, which gives you a way to experiment with built-in variables using a short, simple SPARQL query. For example, to try the mathematical function smf:random() (a TopBraid Composer extension to the Jena function library), enter the following query in the SPARQL view's Query Editor tab: SELECT?x WHERE { LET (?x := smf:random()). } To execute it, either click the "Execute SPARQL" green triangle button or press Ctrl+Enter, and you'll see a random number between 0 and 1 appear in the [x] column of the SPARQL query result. Because this function returns a different value each time you call it, go ahead and execute it a few more times. Another built-in extension function is smf:parsedate(), which converts a string in a semi-structured date format into an xsd:date, xsd:datetime, or xsd:time value. (To learn more about smf:random(), smf:parsedate(), and other available functions, select Help Contents from the Help menu and then TopBraid Composer -> Reference -> SPARQLMotion Functions Reference.) This function takes two parameters: a date string and a template showing which pieces of the date are where in that string. Try pasting the following query into the SPARQL view's Query Editor tab and executing it: SELECT?x WHERE { LET (?x := smf:parsedate("7/30/10","mm/dd/yy")). } The value displayed under [x] is "2010-07-30". The TopBraid Composer online help for this function includes the URL of a web page with greater detail about options for the format string in the smf:parsedate() function's second parameter. We're going build on this function to create a simpler function to convert dates from the MM/dd/yy format to ISO 8601 format. 3.2 Defining your own functions TopQuadrant, Inc www.topquadrant.com Corporate Office Alexandria, VA 330 John Carlyle Street Suite 180 Alexandria, VA 22314-5760 Phone: +1 703.299.9330 Fax: +1 703.299.8330 Development Office Mountain View, CA 201 San Antonio Circle Building B, Suite 230 Mountain View, CA 94040-1254
TopBraid Application Development Quickstart Guide Writing new SPARQL functions with SPIN 21 Before creating anything you'll need a file to store it in. Select the TestProject project created in the last chapter, pick New from the File menu and pick RDF/OWL/SPIN File. In the wizard dialog box that appears, replace unnamed0 with FunctionDemo in the Base URI field and click the Finish button. TBC will create your file for you. The Import view will show you that the spin.rdf file has been imported from the SPIN folder of your Navigator view's TopBraid project. If you had selected RDF/OWL File instead of RDF/OWL/SPIN File from the File -> New menu, you could later drag that spin.rdf onto your new file's Import view for the same effect. With the spin.rdf graph imported into yours, you'll see see several nodes in the Properties view that wouldn't have been there otherwise. Each has an sp: or spin: prefix and a plus sign next to it that expands the node to show more SPIN properties. For now, you won't need to use these properties from this view, because TopBraid Composer gives you forms to fill out to specify everything you need to define a new function. The Classes view also shows a few new classes. Click the plus sign next to spin:modules to expand it, and you'll see that one of the subclasses is spin:functions. To create your new function, 1. Right-click on spin:functions and pick Create subclass from the context menu. 2. On the Create Classes dialog box, click on the default new function name of "Functions_1", replace it with the name mmddyy2iso8601, and press Enter. 3. Click the OK button. You'll see that your new subclass of spin:functions is currently selected in the Classes view, and the class form will have the Name and rdfs:subclassof values already filled out. TopQuadrant, Inc www.topquadrant.com Corporate Office Alexandria, VA 330 John Carlyle Street Suite 180 Alexandria, VA 22314-5760 Phone: +1 703.299.9330 Fax: +1 703.299.8330 Development Office Mountain View, CA 201 San Antonio Circle Building B, Suite 230 Mountain View, CA 94040-1254
22 TopBraid Application Development Quickstart Guide Writing new SPARQL functions with SPIN Your new function will have an argument passed to it: the date string to convert. The body of the function must reference this argument, so let's define the argument before creating the function body. Like everything else in SPIN, this definition will ultimately be stored with a series of triples, but because argument definition is so common in application development, SPIN includes a template to make it easier. 1. SPIN models arguments to functions as constraints on those functions. On the mmddyy2iso8601 class form, click the context menu white triangle next to the spin:constraint property name and pick Create from SPIN template. 2. Select spl:argument from the Available Ask/Construct Templates list, and then fill in the following two fields in the Arguments panel on the right of the Create from SPIN template... dialog box: In the comment field, enter Convert mm/dd/yy formatted date to xsd:date type and format. (Remember to press the Enter key after entering a value on one of these forms. If you tab to another field and the comment field has a heavier border around it and and the Create from SPIN template dialog box's OK button is grayed out so that you can't click it, go back to the comment field and press the Enter key.) Instead of typing a value directly into the predicate field (which has a red outline because an empty value for this property is not valid), click the plus sign to the right of it. This displays a Select Resource... dialog box; because we're defining our first (and only) argument to pass to the new mmddyy2iso8601 function, click sp:arg1 on the right panel and then the OK button. 3. Click the OK button to finish with the Create from SPIN template dialog box, and you'll see that the spin:constraint field of the class form for your new mmddyy2iso8601 function has been filled out. 4. All that remains is to define the function body. Click the spin:body widget on the class form and select Add empty row. 5. Enter the following as the body: SELECT?x WHERE { LET (?x := smf:parsedate(?arg1, "MM/dd/yy")). } The body of this function uses?x as the variable name, but you can use any name you want. If you have more than one variable, and they bind to more than one value, the function will return the first value of the first variable, so there's no point in putting more than one variable after the SELECT keyword. In this SPARQL query, the first argument to the smf:parsedate() function is arg1, which we defined on the spin:constraint part of the form earlier. Your new function should be ready to use. Test it by entering and executing the following in the SPARQL view: SELECT?x WHERE { LET (?x := :mmddyy2iso8601("9/6/10")). } Like any other classes, functions belong to a particular namespace. For example, parsedate() is in the namespace represented by the smf prefix. The colon at the beginning of your :mmddyy2iso8601("9/6/10") function call shows that it's in the default namespace. For production application development, it's better to define a specific prefix for this file's namespace, as described in the previous chapter, and to then reference functions defined in this file with that prefix. This will make it easier to import the code into another file without confusion. TopQuadrant, Inc www.topquadrant.com Corporate Office Alexandria, VA 330 John Carlyle Street Suite 180 Alexandria, VA 22314-5760 Phone: +1 703.299.9330 Fax: +1 703.299.8330 Development Office Mountain View, CA 201 San Antonio Circle Building B, Suite 230 Mountain View, CA 94040-1254
TopBraid Application Development Quickstart Guide Writing new SPARQL functions with SPIN 23 mmddyy2iso8601() is now a function that you can call anywhere when using or importing this file, including from the body of new functions that you create. Test it further in the SPARQL view by passing other dates as a parameter. TopQuadrant, Inc www.topquadrant.com Corporate Office Alexandria, VA 330 John Carlyle Street Suite 180 Alexandria, VA 22314-5760 Phone: +1 703.299.9330 Fax: +1 703.299.8330 Development Office Mountain View, CA 201 San Antonio Circle Building B, Suite 230 Mountain View, CA 94040-1254
24 TopBraid Application Development Quickstart Guide Writing new SPARQL functions with SPIN TopQuadrant, Inc www.topquadrant.com Corporate Office Alexandria, VA 330 John Carlyle Street Suite 180 Alexandria, VA 22314-5760 Phone: +1 703.299.9330 Fax: +1 703.299.8330 Development Office Mountain View, CA 201 San Antonio Circle Building B, Suite 230 Mountain View, CA 94040-1254
Chapter 4 Creating and running a SPARQLMotion script Topics: Creating the script Running it SPARQLMotion is a visual scripting language that lets you tie together triples from diverse data sources (whether they're natively stored as triples or not), process them using SPARQL, and then save the results in a wide choice of output formats. You can run one of these scripts from TopBraid Composer, as a semantic web service, or as the back end to a user interface created with TopBraid Ensemble. You create a SPARQLMotion script by dragging icons representing different kinds of processing modules from a palette onto a workspace and then filling out a dialog box for each to configure it. In this chapter, we're going to look at the creation of a simple script, and in future chapters we'll learn about more modules and what they can add to your application development: reading and writing spreadsheet data, reading from relational databases and SPARQL endpoints, HTML and XML processing, and more. Our sample script will import the triples from the FOAF ("Friend of a Friend") files of some well-known semantic web advocates, extract the names and nicknames of their friends who are listed there, and save the results in a new RDF file. Much more complex scripts are possible, but the creation of those scripts will always follow the basic steps described here.
26 TopBraid Application Development Quickstart Guide Creating and running a SPARQLMotion script 4.1 Creating the script To create a SPARQLMotion file, create a new file in TopBraid Composer the same way you would create any other file. When you indicate that you want to create a file, you'll see that SPARQLMotion File is one of the options. Picking it creates a file that already has the sparqlmotionfunctions and sparqlmotionlib libraries imported; these have what you need to add a script to your new file. Assign the file any Base URI and File name you like (for example, http://www.example.com/sm1 and sm1) and click the Finish button to indicate that you're done with the Create SPARQLMotion File dialog box. Next, select Create SPARQLMotion Script from TopBraid Composer's Scripts menu. Starting with TopBraid 3.4, when you create a new script, instead of asking you to specify an initial module right away, TopBraid Composer will take you right to the SPARQLMotion palette, where you can select your first module the same way that you select the others, as described below. A Select initial module type dialog box will ask you about the first module to add to your script. Because the script will import RDF files from the web, start with an ImportRDFFromURL module and name it GetTimBLData: After filling out the dialog box as shown and clicking the OK button, the script appears with its single module: TopQuadrant, Inc www.topquadrant.com Corporate Office Alexandria, VA 330 John Carlyle Street Suite 180 Alexandria, VA 22314-5760 Phone: +1 703.299.9330 Fax: +1 703.299.8330 Development Office Mountain View, CA 201 San Antonio Circle Building B, Suite 230 Mountain View, CA 94040-1254
TopBraid Application Development Quickstart Guide Creating and running a SPARQLMotion script 27 Starting with TopBraid 3.4, the SPARQLMotion palette looks a little different: the choice of modules to add is in a tree on the left, as shown here, instead of being in an accordion list on the right, as shown in the other illustrations in this chapter. You will find ImportRDFFromURL under the the Import from Remote branch of the tree on the left; drag it onto the workspace and continue as described below. Double-click the icon representing the module to configure it. The only information you must add to an ImportRDFFromURL module is the URL of the RDF to import. To set the value of a property such as sml:url on one of these dialog boxes when there is no existing value, display its context menu by clicking the white triangle next to it and select Add Empty Row. To to set the property value to retrieve Tim Berners-Lee's FOAF file, enter the value http://www.w3.org/people/berners-lee/card.rdf, as shown below. Note from the Ok to the right of the sm:url that the data entry of this field is not complete TopBraid Composer will not know about this new value until you either press the Enter key with the cursor in that field or click on Ok to make it go away. TopQuadrant, Inc www.topquadrant.com Corporate Office Alexandria, VA 330 John Carlyle Street Suite 180 Alexandria, VA 22314-5760 Phone: +1 703.299.9330 Fax: +1 703.299.8330 Development Office Mountain View, CA 201 San Antonio Circle Building B, Suite 230 Mountain View, CA 94040-1254
28 TopBraid Application Development Quickstart Guide Creating and running a SPARQLMotion script We'll see shortly why you don't have to add a value for the sm:next property on this dialog box. Click the Close button to return to the script workspace. At this point, your script only has one module, but you can still run it. Mouse over the small green triangle icon at the top of the SPARQLMotion workspace to display its title: "Run SPARQLMotion script (up to selected module)"). Click the GetTimBLData module icon to select it and then click the green triangle. After it retrieves the triples from the designated URL, TopBraid Composer displays a message box offering to display the result triples in TopBraid Composer's SPARQLMotion Results view. Click the SPARQLMotion Script Executed message dialog box's Display result triples checkbox and click the Close button to do so. As with so many semantic web applications, this one becomes more interesting when you add more data sources and then select a subset of the combined data that meets your needs. If you don't see the module palette on the right side of the script workspace, click the small white triangle in the upper-right of the workspace to display it. Remember that you can resize the views if your SPARQLMotion workspace isn't very big. To add a second module, click Import from Remote on the palette and click the tiny darker triangle to scroll through the choices there. When you see Import RDF from URL, add a new one of these modules to your workspace by dragging it there and name it GetJimHendlerData. Enter http://www.cs.umd.edu/~hendler/2003/foaf.rdf as the data's location. Then, add a third Import RDF from URL module named GetDanBrickleyData and set http:// danbri.org/foaf.rdf as the sml:url value. (At any point in the creation and editing of your script modules, you can rearrange the icons by selecting and dragging them.) Now we'll create a module that gathers data from these three sources and only passes along the triples that identify the name and nickname values found the source data. Drag an Apply Construct module from the RDF Processing section of the palette onto the workspace and name it ExtractData. After this module appears, double-click it and set the sml:constructquery property's value to the following: CONSTRUCT {?s a <http://xmlns.com/foaf/0.1/person>.?s <http://xmlns.com/foaf/0.1/name>?name?s <http://xmlns.com/foaf/0.1/nick>?nick } WHERE {?s <http://xmlns.com/foaf/0.1/name>?name?s <http://xmlns.com/foaf/0.1/nick>?nick.... TopQuadrant, Inc www.topquadrant.com Corporate Office Alexandria, VA 330 John Carlyle Street Suite 180 Alexandria, VA 22314-5760 Phone: +1 703.299.9330 Fax: +1 703.299.8330 Development Office Mountain View, CA 201 San Antonio Circle Building B, Suite 230 Mountain View, CA 94040-1254
TopBraid Application Development Quickstart Guide Creating and running a SPARQLMotion script 29 } SPARQL SELECT queries pick specific pieces of information to pass along. CONSTRUCT passes along entire triples, which may be copies of input triples or new triples created by rearranging and cross-referencing input data to infer and create new information based on the input. Our simple query here merely finds and passes along triples that match two patterns. It also uses the a abbreviation of the rdfs:type property name to declare that the subject that has these properties is a Person as defined by the FOAF vocabulary. After entering this CONSTRUCT query, set the same dialog box's sml:replace value to True so that only the constructed triples get passed along to the output without the input data. Now you're finished with this dialog box, so click its Close button. We haven't identified the input of this CONSTRUCT module yet. Instead of writing code, we can do it by just pointing and clicking. To make your first connection, select the Add connection icon on the Palette, click on the GetTimBLData module, and then click the ExtractData module. An arrow will appear to show that data will flow from one to the other when the script is run: Follow the same steps to connect the other two data retrieval modules to ExtractData. Instead of waiting until the application is finished to test it, we can do more incremental testing here. Select the ExtractData module, click the green arrow at the top, and you should end up with a list of names, nicknames, and foaf:person type declarations in the SPARQLMotion Results view. Our final step has two parts: 1. Tell the script to save the results of the ExtractData module to an RDF disk file. From the Export to Local section of the Palette, drag an Export to RDF file module onto the workspace and call it SaveOutput. Double-click the new module and set the sml:baseuri property to http://mytest/ (or any URI you like; it will be used as the base URI of the saved file) and set sml:targetfilepath to sm1out.rdf. If you don't specify a path for this file, the SPARQLMotion script will save the file in the same directory as the script itself. After setting these two values, click the Close button. 2. By including the FOAF ontology in your output, applications that read the file created by your script will have more context about the meaning of the data. You can import this ontology from the web, but the TopBraid Composer distribution includes many popular ontologies so that importing them will happen more quickly. From the Import from Local section of the SPARQLMotion palette, drag an Import RDF from workspace module onto the workspace and name it FOAFOntology. Double-click it and set its sml:sourcefilepath property to / TopBraid/Common/foaf.owl to pull the foaf.owl file from the Common folder of the Navigator view's TopBraid project. Press Enter, and then click the dialog box's Close button. TopQuadrant, Inc www.topquadrant.com Corporate Office Alexandria, VA 330 John Carlyle Street Suite 180 Alexandria, VA 22314-5760 Phone: +1 703.299.9330 Fax: +1 703.299.8330 Development Office Mountain View, CA 201 San Antonio Circle Building B, Suite 230 Mountain View, CA 94040-1254