TopBraid Application Development Quickstart Guide. Version 3.3

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

30 TopBraid Application Development Quickstart Guide Creating and running a SPARQLMotion script Use Add connection to connect the ExtractData and the FOAFOntology modules to the Save Output module. Your completed script should look like this: 4.2 Running it After saving your application, test it by selecting the Save Output module and clicking the green arrow. As it runs, watch the Console view, which provides informational messages about your script as it runs. The Console and Error Log views are valuable for debugging complex scripts. The script should create the sm1out.rdf file described above in the directory where your script is stored. Open it up, and then in TopBraid Composer's Classes view, drill down from owl:thing to foaf:agent and select foaf:person so that the instances you've created appear in TopBraid Composer's Instances view. Selecting any of them there will display details about that person in the Form view, where you'll see the name and nickname assigned to that person somewhere on that form. (You may need to scroll the form down a bit to see those particular properties.) If you look through the several module choices on the SPARQLMotion palette you'll get some idea of the wide variety of possibilities you have for the kinds of data that a script can read and write and the sophisticated options for processing that data. We'll look at several of them in later chapters. Meanwhile, take a look at this short video, which shows you how to create another simple script that uses a few more interesting modules. 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 5 Creating and running a semantic web service Topics: Creating your script Defining the function to call Creating the SPARQLMotion script Registering and calling your web service When you know how to write a SPIN function and how to create a SPARQLMotion script in TopBraid Composer, you can put these two skills together to create a RESTful web service that can be called from any computer with HTTP access to the server running your web service. In a production environment where many people and systems might do so, the TopBraid Live Enterprise Server would be the best way to host it, but for developing and testing you can use the TopBraid Live Personal Server built into TopBraid Composer Maestro Edition. In this chapter we'll see how to create a web service that searches the database about the Kennedy family included with TopBraid Composer and returns RDF/XML that lists everyone with a particular first name. But first, what makes this a "semantic" web service? TopBraid Composer puts all the power of semantic web technology, such as SPARQL, OWL, and more, behind your development efforts, and it lets you read and write both semantic web data formats and more traditional ones. By delivering RDF, your web service can connect to other semantic web applications, although you're certainly not limited to RDF as a delivery format you can deliver XML, a spreadsheet, or even HTML, so that a browser hitting the URI you designate for your service would actually be displaying a web page dynamically generated by a SPARQLMotion script. If you've never defined your own SPIN functions or created a SPARQLMotion script in TopBraid Composer, you'll want to review the earlier chapters mentioned above before continuing.

32 TopBraid Application Development Quickstart Guide Creating and running a semantic web service 5.1 Creating your script Start by creating a SPARQLMotion File in one of your projects, but on the Create SPARQLMotion File dialog box, remember to check the Script will declare (Web) Services or Functions (.sms extension) checkbox. If you name your file ws1 and leave the file extension set to n3, you'll see that TopBraid Composer then saves it with the full name ws1.sms.n3. Once you've created this file, turning it into a web service script involves two steps: 1. Defining the function that the web service URI will call. 2. Defining the script that will be triggered by the function call. 5.2 Defining the function to call Under the spin:modules branch of the Classes view, create a new subclass of spin:functions and name it searchkennedys. To configure it, 1. Add an sp:arg1 argument as a spin:constraint value using Create from SPIN template (as described in Writing new SPARQL functions with SPIN) with a predicate value of sp:arg1. 2. For the argument's comment field, enter String to search for. 3. Set its valuetype to a data type of xsd:string so that the function receiving the passed argument value knows to treat it as a string and not as a URI. With that, you'll be finished configuring your spl:argument and can click the OK button. In the create a SPARQLMotion script chapter, the script you created had a single endpoint called SaveOutput. A given SPARQLMotion script can have several possible endpoints, each returning different variations on how the data is processed, so identifying a set of script modules to run means identifying a specific endpoint in a script. On the class form for your new searchkennedys function, set the sm:returnmodule property by clicking the context menu white triangle and then selecting Create and add... You will create this return module before adding it because you haven't created your script yet, so there's no endpoint module to point to. On the Create and add dialog box, pick sml:returnrdf as the first module to add, as shown below. (It's a subclass of ExportToRemoteModules because your web service will return its results to a remote caller you'd pick something from ExportToLocalModules if it were going to save the results in a local file.) Name your new module ReturnSearchResults. 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 semantic web service 33 Click the OK button. 5.3 Creating the SPARQLMotion script Next, select Edit SPARQLMotion script from the Scripts menu. You'll see that two modules have already been added to your new script: your ReturnSearchResults module and an Argument module to represent the arg1 argument being passed to your script. 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

34 TopBraid Application Development Quickstart Guide Creating and running a semantic web service Note the gray "arg1" with a little arrow on a circle in the lower-right of the Argument module icon, which shows the name of the variable that's being set and passed along by this module. Your script will use this variable to specify what to search for in the Kennedy family data. The next step is to add something to the script to read the data that it will search. Drag an Import RDF from Workspace icon from the Import from Local section of the palette onto the workspace and name it GetKennedysData. To configure it, double-click its icon, set its sml:sourcefilepath property to /TopBraid/Examples/ kennedys.rdf, and then click the Edit GetKennedysData dialog box's Close button. Now we'll add the module that searches through the data and extracts the subset that we need. Drag an Apply Construct module from the palette's RDF Processing section onto the workspace and name it SelectData. Set its sml:replace property to True so that it only passes along the selected data and not the input data as well by adding an empty row and then setting it to True. Set the sml:constructquery value to the following: PREFIX k: <http://topbraid.org/examples/kennedys#> CONSTRUCT {?s k:firstname?first.?s k:lastname?last. } WHERE {?s k:firstname?first.?s k:lastname?last. FILTER regex(?first,?arg1, "i" ) } After you press Enter, TopBraid Composer will replace the "k" namespace prefixes with the namespace URIs. If you wanted this query to always search for firstname values with "John" in them, you could put that as the second argument of the regex function in the CONSTRUCT query's FILTER expression, but this query has something more flexible: a reference to the arg1 variable that will be passed in from the Argument module. (The third argument of "i" to this function tells it to ignore case when searching.) The use of the regex function means that it will search for substring matches as well, so that a search for "car" will turn up Caroline Kennedy, Carolyn Bessete, and Cart Hood. You're finished configuring this module, so click the Close button and connect the two input modules to it like this (don't worry about connecting up the Return Search Results module just yet, and remember that at any time you can drag the module icons around to make the script's flow easier to understand): 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 semantic web service 35 Click the SelectData module to select it and then click the green arrow near the upper-left of the workspace to run your script up to that module. Because no value has been passed for the Argument, a SPARQLMotion Script Input dialog box prompts you for one. Enter "jean" as a test, press Enter, and then click the Next button. When it's finished, you should see triples storing the firstname and lastname values for Jean Olssen, Jean Kennedy, and Jeannie Ripp appear in the SPARQLMotion Results view. Double click the tab of the SPARQLMotion Results view to maximize it so that you can see the results better, and then double-click it again to return it to its original size. Your web service script can now do everything except return the data that it extracted from the data source to the process that called the service. Connect the SelectData module to the ReturnSearchResults module, which still needs one bit of configuration: to tell it to return the data as RDF/XML. Double-click that icon, and if the sml:serialization property doesn't already have a value of RDF/XML, click the white triangle that displays the property's context menu. Don't pick "Add empty row" this time; you want to add one of the predefined values from the sml:rdfserialization class, so pick "Add Existing." On the Add existing dialog box, click on sml:rdfserialization, select sml:rdfxml on the right (note the other choices available to you), click this dialog box's OK button, and then click the Edit ReturnSearchResults dialog box's Close button. Save your work. The final script should look something like this: 5.4 Registering and calling your web service Before something can tell TopBraid Live to call the searchkennedys function that calls this script, the function must be registered with the server. To do this, select Refresh/Display SPARQLMotion functions... from the Scripts menu, and after a few seconds you'll see the updated list of registered functions on the Console view. To test your web service, enter the following into any web browser running on the same computer as your copy of TopBraid Composer; note how its two parameters identify the function to call and the argument value to pass to it: http://localhost:8083/tbl/actions?action=sparqlmotion&id=searchkennedys&arg1=rob 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

36 TopBraid Application Development Quickstart Guide Creating and running a semantic web service After making this call, you should see RDF/XML data in your web browser about the six people in the database who have "Rob" in their first name: five Roberts and a Robin. (For some browsers, you may need to to a View Source to see all the XML.) Congratulations! You now have a working, RESTful, semantic web service up and running. Any tool that can send a URI to an HTTP server and then parse the result can call this service. Most modern program languages include libraries that make sending a URL to a web server and parsing the results simple. If you install your web service and the appropriate data files on a computer running a TopBraid Live Enterprise Server, multiple systems can retrieve data from that service at once. When you consider the possibilities of using data from more diverse, large-scale data sources and creating SPARQLMotion scripts that take advantage of a wider range of the modules available on the workspace palette, you'll start to see the tremendous possibilities of what you can do with your TopBraid semantic web services. 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 6 Creating a TopBraid Ensemble application Topics: TopBraid Ensemble: the basics Creating the sample application TopBraid Ensemble (TBE) is a Flex-based web application for assembling and displaying TopBraid applications. The user interface runs on web browsers with Adobe Flash installed. When developing applications, the data behind the application is hosted by the TopBraid Live Personal Server included with TopBraid Composer Maestro Edition (TBC-ME); applications can then be deployed for multi-user use on a server running the TopBraid Live Enterprise Server product. In this chapter we'll see how to use TBE to create an editor that lets an end user edit a thesaurus using the SKOS vocabulary management ontology. This exercise is excerpted from the TopBraid Ensemble Application Development and Reference Guide (pdf), which you can download and use to find more detailed background on TBE's features and architecture.

38 TopBraid Application Development Quickstart Guide Creating a TopBraid Ensemble application 6.1 TopBraid Ensemble: the basics TBE lets developers quickly configure applications around semantic web models by: Assembling pre-packaged graphical user interface components such as search forms and tree-based displays into desired configurations that let the end user view or edit data Adding custom business logic through SPARQLMotion scripts Building and using new custom components Once the application developer designs forms and event logic around a data model and deploys this TBE application on a server running the Enterprise edition of TopBraid Live, the developer's end users can use this application with any web browser that supports Adobe Flash and has access to that server. The twelve user interface component types offered in TopBraid release 3.3 include trees, grids, forms and maps. A developer can arrange these across multiple pages that function like a tabbed interface to reduce the clutter than can result from squeezing too much onto a single screen. Each UI component can: Contain one or more widgets that can display or provide an edit mode for information from the connected information source Include its own menu actions and icons Broadcast events to other components and listen for and react to events broadcast by other components TBE also provides non-ui, or invisible components, which work behind the scenes to perform data transformation and to relay events between components. A developer designs one or more input screens with TBE components and specifies the data graphs that it will work with. These applications can call SPARQLMotion scripts, combining sophisticated back-end triples processing with quick development of application user interfaces to create powerful, intuitive semantic web applications. Creating an application consists of four basic steps: 1. Select whether you want to begin with a New Application or a Default Application 2. Identify the data to use with your application 3. Select and configure the components to go on your screens 4. Test your application Starting with a New Application means starting with a blank form and then adding and configuring the components that you need. This is especially useful for experienced TBE developers creating simple applications. New TBE developers often find it easier to begin with a Default Application, which includes several components arranged in a default layout and configured to post and listen for several events. You can then modify this application by deleting, adding, moving, and reconfiguring the components and then save the application with a new name. The following shows a Default Application before any modifications have been made, with kennedys.rdf specified as the data to use with it: 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 a TopBraid Ensemble application 39 A configured TBE application specifies what components are shown when it is launched, how components are arranged, and how they interact with each other. An application may or may not define which data graphs to use with it. Some applications, such as the default apps and the new app, are configured to work with any data. Other applications are configured to work with specific datasets. When creating a TBE application, components can be rearranged, resized, removed and added. For example, you can have two Results Grid components on the screen instead of one, or no result grids. You can also customize the menu options for each component and the way the components interact with each other by specifying which events each posts and listens for and now they react to events. TopBraid Ensemble's Default configurations are general TBE applications included in your installation. These configurations include most of the built-in components, laid out and wired for interaction with each other so that when an event such as a resource selection happens in one component, information displayed in some of the other components changes. For example, when you select a class in the tree, the members of the class appear in the grid, and when you select a resource in the grid, it populates the form with information about that resource. You can learn a lot about the potential power of these forms by studying how the components in the default configurations generate and listen to the events that make this kind of component interaction possible. 6.2 Creating the sample application Our sample SKOS thesaurus editing application will have only two components: A tree displaying resources connected by the skos:broader property. (For example, the concept Dog might have a skos:broader value of the concept Mammal, although as with any RDF resource, these concepts are actually represented by URLs and would use names such as "Dog" and "Mammal" as their skos:preflabel value.) A form showing details of each resource. When the end-user clicks a node of the tree or a class name on the form, the form will refresh to display all the details about that class. TBE applications typically work with ontologies created using TBC, so before creating our TBE app, we need to create the data model. Step 1: Create Ontology In TBC, create a new RDF/OWL file called thes1 and either check SKOS in the Initial imports section of the Create RDF/OWL File wizard or import skos-core.rdf from the Common folder of the TopBraid library into your new model. Among other things, this imports the declaration of the skos:concept class; create an instance of 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

40 TopBraid Application Development Quickstart Guide Creating a TopBraid Ensemble application skos:concept (a subclass of owl:thing) in this model and call it TaxonomyRoot. Remember which project you've stored thes1 in, because you'll need its TaxonomyRoot instance as a root resource for the tree you create on your TBE form. Save your work. Step 2: Create New Application To get started with developing and configuring a TBE application, first send your browser to the TopBraid Suite Console, which can be accessed at http://localhost:8083/tbl when running the TopBraid Live Personal Server included with TBC Maestro Edition. This will take you to the TopBraid Administration Console. In the TBL Personal Server Console, select "New Application". On the Data Graphs Compatible With New Application screen, select the thes1 model that you just created from the project where it was stored. Step 3: Select Components In TBE, click the plus sign icon and select Add Components to add a Tree component and a Form component to the application. Drag their tabs to lay them out side by side as shown in the following: The default configuration of the tree component is to show the class structure of the data model. You'll be reconfiguring it to show the tree of taxonomy terms being edited by your new application's end user. Step 4: Configure Application Open the Application Configuration console by clicking the wrench icon or pressing F2. This lets you configure various aspects of your application's components by setting specialized attribute values for those components, by naming events to be be posted upon certain actions, and by naming actions to perform when a component "hears" an event posted by another components. You began by opening a copy of the application called "New Application". Click the "New Application" title at the top of the Application Configuration navigation pane on the left, and then under General on the right change the application label to SKOS Editor and press Enter. 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 a TopBraid Ensemble application 41 To change an existing attribute value on the Application Configuration screen, hover your pointer to the left of the existing value and click the edit button that appears there. Step 5: Configure Tree Now click on the Tree component on the left side of the Application Configuration console. (You may need to first click the Components node of the tree to expand it into a list of available components.) You're going to configure some of its attributes and have it post a particular event when a tree node is clicked. An event is a named signal sent by one component to another, bringing the URL of a particular resource with it. Once you define an event to be posted, you'll most likely configure at least one more component to listen for that event and probably do something with the resource whose URL was passed. Make the following modifications to your tree component's configuration: Rename the Tree's label to read Concept Hierarchy. Under Tree/Attributes, change the Show the root of the tree in the display setting to true. Change the Root Node to TaxonomyRoot (the new resource you created in TBC earlier). Once you type the first few letters of "TaxonomyRoot", the complete value should appear in a dropdown list where you can select it, because TBE knows that this is an available valid value for this field. Change the Transitive Property that identifies tree node child/parent relationships to broader (the label assigned to the skos:broader property). Under Events, create a new Post Event for Single-click Selection and call it Tree Selection. If you don't uncheck the Select after creation checkbox, then when you're done, TBE will automatically take you from the Components and Layout screen of the Application Configuration window to its Event Wiring screen, which makes it easier to manage events. If this happens, you can always click Components and Layout in the upper-left to return to that screen. Your configuration should look similar to the one shown here: 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

42 TopBraid Application Development Quickstart Guide Creating a TopBraid Ensemble application Step 6: Configure Form Now select the Form component on the left of the Application Configuration console and make the following modifications: Wire the Form to listen to the Tree Selection event. Click on the plus sign next to Update Displayed Resource under Listen Event. Select Add existing entry and start typing Tree. When "Tree Selection" appears in the drop down list, select it and click OK. If the information displayed on a form about a given SKOS concept includes a reference to another SKOS concept (for example, if the information about the concept Dog names Mammal as the broader concept), then when the application's user clicks on Mammal, we want the form to display information about the Mammal concept. In other words, we want the value to function as a hypertext link to information about the named concept. To do this, create a new Post Event for the Click Resource Link post event and call it Form Selection. The form is already configured to refresh when the application's user clicks a tree node, which posts a Tree Selection event. Now we'll tell it to refresh when an appropriate value on the form is clicked that is, when the Form Selection event defined above gets posted. Click the plus sign and then Add existing entry next to the Update Displayed Resource listen even and start typing Form. When "Form Selection" shows up in the drop down list, select it. It will join Tree Selection as the second event that can trigger the Form's Update Displayed Resource action. Your configuration should look similar to the one shown here: 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 a TopBraid Ensemble application 43 Step 7: Test and Save Your new application is done. You can close the configuration console by clicking the X at the upper right and test your new application by creating new nodes in the tree with the buttons in the upper-right of the tree component and entering additional information in the forms as shown below. The buttons in the upper-right of the tree component are just a few examples of the different specialized buttons included with many of the TBE components. Mouse over each to see what it does. If you don't want them displayed on a particular component in your application, you can hide them in the Buttons section of the component's configuration section on the TBE Application Configuration screen. As you add and select nodes in the Concept Hierarchy, the tab title and many of the fields in the form on the right will update automatically to provide information about the selected tree node. You can edit form values such as the comment and label by mousing over the area to the right of the property name and clicking the edit button that appears. If no value exists, click the plus sign to the left of the property name and then pick Add empty row to add a new value. 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

44 TopBraid Application Development Quickstart Guide Creating a TopBraid Ensemble application To save your application, click the Save App button. The Save Application dialog box offers the self-explanatory choices Save as New Application, Save Application, Discard Changes of Application, and Cancel. Because you began this application development session by opening up the "New Application" default application, TBE will not let you pick Save Application here, because the New Application must be left in its original form to provide the basis for future new applications. To save the data you've created using your new SKOS editor application, such as the bird information shown in the screen shots, you or your application's end users would click the Save Data button. Applications like this can be hosted on the TopBraid Live Enterprise Server, where any users with browser access to that server can run your application and browse and edit the data you choose to make available. They don't need TopBraid Composer, and they don't need to know about RDF or any data modeling issues; they only need to know how to use the graphical, interactive SKOS editing application that you designed for them using TopBraid Ensemble. This chapter has only shown you a small part of what a TBE application can do for your end users. Take a look at the TopBraid Ensemble Application Development and Reference Guide (pdf) to learn more. 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 7 Getting data from SPARQL endpoints and saving data in a spreadsheet Topics: Retrieving data from a SPARQL endpoint Saving data in a spreadsheet This chapter covers two useful SPARQLMotion techniques: how to retrieve and use data from SPARQL endpoints, and how to save data so that you can open it with a spreadsheet program such as Excel or OpenOffice Calc. While this may look like a lot of material to cover, both techniques are so simple that this is the shortest chapter since the introduction.

46 TopBraid Application Development Quickstart Guide Getting data from SPARQL endpoints and saving data in a spreadsheet 7.1 Retrieving data from a SPARQL endpoint A SPARQL endpoint is a server that accepts SPARQL queries and returns the result using the SPARQL Query Results XML Format, a W3C standard XML-based format that is much simpler than RDF/XML. The endpoint can be part of your intranet, providing access for others there to data behind your firewall, but more and more SPARQL endpoints are available on the public internet to provide you with data to use in your applications. Excitement about the new possibilities provided by this data is a big driver of the Linked Data movement. The ability to retrieve SPARQL endpoint data from within a SPARQLMotion script is not a feature specific to SPARQLMotion, but actually an extension to the Jena framework that will hopefully become part of SPARQL 1.1: the SERVICE keyword. This lets you name a data source right in your query, and the source can be a remote SPARQL endpoint. To try it out, enter the following query into TopBraid Composer's SPARQL view and execute it. Instead of pulling data from the currently open data graph, this query gets it from the SPARQL endpoint specified by the URI http:// dbpedia.org/sparql, which is the endpoint for the huge DBpedia collection of triples harvested from the structured infobox data in Wikipedia pages: SELECT?subsidiaryName?description WHERE { { SERVICE <http://dbpedia.org/sparql> { <http://dbpedia.org/resource/ibm> <http://dbpedia.org/ontology/subsidiary>?ibmsub.?ibmsub <http://dbpedia.org/ontology/abstract>?description.?ibmsub rdfs:label?subsidiaryname. FILTER (lang(?description) = "en") FILTER (lang(?subsidiaryname) = "en") } } } This query retrieves the English language ("en") names and descriptions of IBM subsidiaries from DBpedia. A DBpedia query that works one week with a particular SPARQL endpoint may not work the following work if any of the property URLs change. As the linked data counterpart to Wikipedia, DBpedia is a volunteer effort with ongoing data cleanup efforts that can affect the organization of its vocabulary and namespaces. You can use this technique anywhere that you can use a SPARQL SELECT query in your TopBraid development including in the sml:selectquery property of a SPARQLMotion Create Spreadsheet module, as we'll see. 7.2 Saving data in a spreadsheet If you search the TopBraid Composer online help for the word "spreadsheet" you'll see that TopBraid offers several ways to read and write spreadsheet data. The simplest way to create a spreadsheet from a SPARQLMotion script is the Create Spreadsheet module. After you enter a SELECT query in its sml:selectquery property, it sends a tabdelimited spreadsheet to the next SPARQLMotion module with a column for each variable in the select query. Any spreadsheet program can read a tab-delimited file. OpenOffice Calc doesn't offer "tab-delimited file" as a choice of file format to open, but if you tell it to open a "Text CSV" file and point it at a tab-delimited file, it will find that tab characters are the delimiters and import it properly. For 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 Getting data from SPARQL endpoints and saving data in a spreadsheet 47 example, with the SELECT query shown above, this module will create a two-column spreadsheet with subsidiaryname values in the first column and description values in the second. Let's create a SPARQLMotion script that does this. Create a new SPARQLMotion file as described at Creating and running a SPARQLMotion script, calling the file endpointtsv. Next, select Create SPARQLMotion script from the Scripts menu, and when it asks you to select an initial module type, select sml:createspreadsheet from the sml:textprocessing module choices under sml:processingmodules. Name the module GetIBMSubs and click OK. When the icon for your new module appears on the SPARQLMotion workspace, double-click it to configure it and set sml:selectquery to the query shown above. The sml:createspreadsheet module creates a spreadsheet in memory, not on disk, to provide you with the flexibility of doing other things with its output before you send it to a specific destination such as a disk file, so set the sm:outputvariable property to the name spreadsheetdata so that subsequent modules can reference it. You're finished configuring this module, so click the Close button. Our SPARQLMotion script will only have one subsequent module: the one that saves the spreadsheet to a disk file. Drag an Export to text file module from the Export to local section of the palette onto the workspace and name it SaveSpreadsheet. Double-click its icon to configure it and set the following properties: Set sml:targetfilepath to ibmsubs.txt. The sml:text property is where you assign the text to store in the file being created; set it to {? spreadsheetdata} so that it uses the value of the variable being set in the GetIBMSubs module. Set sml:replace to true so that running the script more than once replaces the existing disk file instead of appending the data onto the file. (Of course, setting sml:replace to false can be very handy in other scripts that you write.) Click the Close button, and then click on Add connection on the palette. Connect your two icons, and you're finished with your simple little script: 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

48 TopBraid Application Development Quickstart Guide Getting data from SPARQL endpoints and saving data in a spreadsheet Save it, select the SaveSpreadsheet icon on your script, and click the green arrow at the top of the SPARQLMotion workspace to run the script. You should see an ibmsubs.txt file appear in the same directory as the script itself, because you didn't specify a path name when you configured the sml:targetfilepath property. (You're welcome to include a path with the filename there if you like.) Open up this new file in a spreadsheet program, and then you can use any of the program's formatting features that you like before saving the spreadsheet using the program's native format. (You'll need to know which directory on your computer is serving as your TopBraid Composer workspace in order to find the file with your spreadsheet program.) Here are the first few rows of the spreadsheet in Microsoft Excel after some simple formatting: If you combine these two techniques with others covered in this book, you could have all of this triggered by a web service call, or the script could combine the data retrieved from a SPARQL endpoint with other data from other sources before saving the spreadsheet, or it might output the data in another of the destinations available in the Export to sections of the SPARQLMotion workspace palette. Take another look at those palette choices, or better yet, review the help page for them. I'm sure you'll get some great ideas. 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 8 Calling a SPARQLMotion script from TopBraid Ensemble Topics: Defining the function to call Creating the SPARQLMotion script Testing it Taking it further In earlier chapters, we saw how to create and run a semantic web service and how to create a TopBraid Ensemble application. When you combine these, the user interface that you create with TopBraid Ensemble (TBE) can take advantage of all the power of SPARQLMotion scripts, which can accept parameters from a TBE application, run in the background, and pass the results back to be incorporated into the TBE user interface. In this chapter, we'll see how to pass information between a TBE application and SPARQLMotion by creating a an "Age at death" choice to the TBE gear menu, which triggers SPARQLMotion scripts. When your end user selects a person in the kennedy data and picks this menu choice, a SPARQLMotion script will return either a message about the person's age at death (assuming that they've already had their birthday in the year of their death) or the phrase "Still alive" for display in TBE.

50 TopBraid Application Development Quickstart Guide Calling a SPARQLMotion script from TopBraid Ensemble 8.1 Defining the function to call As we saw in the chapter on creating web services, the first step is to define a SPIN function that points to a SPARQLMotion script, and then we create the script. (The following description assumes that you've read the more detailed description of the same steps in Creating and running a semantic web service.) Start by creating a new SPARQLMotion file called personscripts, and remember to check Script will declare (Web) Services or Functions (.sms extension) on the Create SPARQLMotion File dialog box. Next, in the Classes view, create a subclass of spin:functions called AgeAtDeath. The rdfs:label value for this function is important, because that's the text that will appear on the TBE gear menu; drag this property from the Properties view onto the class form for your new function and enter Age at death there. The next step is to use the function's spin:constraint property to identify the argument being passed to the function. For our new application, we want the argument to be the identifier for the member of the Kennedy family that is currently selected in the TBE application when the menu choice is picked or, in TBE development terms, the URI for the selected resource so that the function knows whose age at death to calculate. To make the selected resource the argument, on the AgeAtDeath class form click the spin:constraint property's white triangle context menu and pick Create from SPIN template. On the Create from SPIN template dialog box, pick sml:selectedresourceargument from the selection of Available Ask/Construct Templates. This will put that value into the predicate field on the Create from SPIN template form. You're now finished specifying the spin:constraint, so click OK. Remember, a SPIN function identifies the SPARQLMotion script to call by naming the script's last module in the function's sm:returnmodule property. The module that we need to point to doesn't exist yet, so pick Create and add... from this property's context menu, and then pick sml:returntext from the sml:exporttoremotemodules section of the sml:exportmodules choices and name your new module ReturnComputedAge. It's exporting to a remote module because a script on the server will return the value to a calling process on the client, and when a TBE application gets text passed by a Return Text module, its default behavior is likely to display that text in a message box, which is what we want for this application. 8.2 Creating the SPARQLMotion script You don't need to create a new SPARQLMotion script, because when you defined the sml:selectedresource and sm:returnmodule modules as part of the AgeAtDeath function, TopBraid Composer put them into a new script for you. Select Edit SPARQLMotion Script from the Scripts menu, and you'll see this script with icons representing these two modules waiting for you to add new modules and connect them up. Drag the Selected Resource icon to the top of the screen, because it will be the beginning of your script. Under it, create a new module to perform the query that will compute the age at death of the selected resource by dragging a Bind by select icon from the Control Flow section of the SPARQLMotion workspace palette onto the workspace. Name this module ComputeAge and set its sml:selectquery property to the following SPARQL query: PREFIX k: <http://topbraid.org/examples/kennedys#> SELECT?deathAge WHERE {?selectedresource k:birthyear?birthyear. OPTIONAL {?selectedresource k:deathyear?deathyear. }. LET (?deathage := smf:if(bound(?deathyear), (?deathyear -?birthyear), "Still alive")). } 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 Calling a SPARQLMotion script from TopBraid Ensemble 51 It uses the SPARQLMotion extension function sml:if to calculate and return the person's age at death if the? deathyear variable is bound and to return the string "Still alive" if not. The sml:selectquery property is the only one to set for this module, so you're ready to add a connection from the Selected Resource module icon to the ComputeAge one. The ComputeAge module knows what SPARQL query to execute, but it doesn't know what data to query. Drag an Import current RDF module, which passes all of the triples of the currently open model to the script, from the Import from Various section of the palette to the workspace. Name it ImportTBETriples and add a connection from this module to the ComputeAge one. You don't need to set any of its properties. It will know what to do. The query above binds the computed answer to the variable?deathage. This is what we want to return to the TBE application that calls the AgeAtDeath function, so set the sml:text property of the ReturnComputedAge module that's been waiting for you to use it to {?deathage} and connect the ComputeAge module icon to the ReturnComputedAge one. Your completed script should look like this: The gear menu in TBE won't know about the AgeAtDeath function until you register it with the TopBraid Live Personal server, so select Refresh/Display SPARQLMotion functions... from from the TopBraid Composer Scripts menu, and after a few seconds you'll see the updated list of registered functions on the Console view. 8.3 Testing it From the TBL main screen, pick "Default Application (configurable)," and on the "TopBraid Live Data Personal Server Selection" screen pick kennedys from the "Data from Project TopBraid" section. When the application appears, click Person in the Tree component in the upper-left to list data about members of the Person class on the Results Grid. Once they appear there, click a row that includes both a "Year of birth" and a "Year of death" value to select it. Click the gear menu in the upper-right, and you should see your new "Age at death" menu choice: 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

52 TopBraid Application Development Quickstart Guide Calling a SPARQLMotion script from TopBraid Ensemble Select it, and you'll see a message box showing the result of the calculation from the SPARQLMotion script: Try again with a row of the Results Grid that has a "Year of birth" but no "Year of death" value, and you should see a similar message box appear with the "Still alive" message. 8.4 Taking it further If you created ten different applications like this, the menu choices for all ten would appear on all gear menus in all of your TBE applications. To limit the menu choice to only appear on the gear menu for applications showing instances of a particular class, such as members of the Person class from the kennedys data, you can name that class in the ValueType property of the sml:selectedresourceargument when you configure the constraint in the function you're defining. The SPARQL query used in your SPARQLMotion script set the return value of?deathage to a very simple value: either (?deathyear -?birthyear) or the string "Still alive". Browse through the "TopBraid SPARQLMotion Functions Library" help panel and you'll see an extensive choice of functions that you can use to assemble a much more complex string to return, with substring and case manipulation functions, regular expression matching, concatenation functions to assemble multiple pieces together, and more. This SPARQLMotion script also had very limited input: the URI of the resource to query about and the data from the kennedys file. As other chapters of this book demonstrate, a SPARQLMotion script can open up many other kinds of 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 Calling a SPARQLMotion script from TopBraid Ensemble 53 both local and remote data, so the URI passed from TBE can be used in much more sophisticated kinds of processing. And, as we saw in Creating a TopBraid Ensemble application, you can custom-design your own TBE screens to be the front end of your application. It's a great combination of front end client-side design flexibility and back end server-side scripting capabilities. 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

54 TopBraid Application Development Quickstart Guide Calling a SPARQLMotion script from TopBraid Ensemble 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 9 Reading triples from a relational database Topics: Getting the database driver Configuring TopBraid to read a MySQL database Reading the data with a SPARQLMotion script TopBraid includes the D2RQ interface to relational database management systems and automates most of the configuration for you, giving your TopBraid applications easy access to relational data. In this chapter, we'll see how easily a SPARQLMotion script can use data stored in a MySQL database. You would use a similar process to get at data stored using Oracle, Sybase, SQL Server, and PostgreSQL. This chapter's exercise uses MySQL's sample world database, a collection of data about countries around the world. See MySQL's Other MySQL Documentation page to download the database and to find information on installing it.

56 TopBraid Application Development Quickstart Guide Reading triples from a relational database 9.1 Getting the database driver Before making a connection from TBC to MySQL, you'll need a driver jar file, which you can get from the Download Connector/J. It will probably have a filename similar to mysql-connector.jar, but with a version number. Rename it to mysql-connector.jar and put it in the root of your workspace folder. For more information on getting and using driver files to connect to relational databases, see the TopBraid Suite Frequently Asked Questions web page. 9.2 Configuring TopBraid to read a MySQL database Once you have running copy of MySQL with the world database and you've installed a database driver to interface to MySQL, the next step is to tell TopBraid Composer to create the configuration files that let you treat this relational database as a virtual triplestore. Start by right-clicking the project or folder in the Navigator window where you want TBC to put these files and picking Import from the context menu. From the TopBraid Composer section of the Import wizard, pick Create Mapping Files for D2RQ Relational Database Interface. Click the Next button, and you'll see the dialog box where you specify the settings for creating this interface. For the database connection file name, enter worlddb, and then change the Base URI of each of the configuration files to something that reflects this filename, as shown in the screen shot below. The last four fields are where you specify the key information for giving TopBraid access to the database. The dropdown list for the Database URL field offers a choice of templates for different RDBMS systems; for our MySQL database, select jdbc:mysql://<server>/<database> and change it to jdbc:mysql://localhost/world. (This assumes that MySQL is running on the same machine as your copy of TBC. If not, substitute the appropriate name for localhost. The part after the last slash is the database that you want to read from the MySQL server on that system.) In the next two fields, enter a user name and password for an account that has access to the worlddb database when using tools included with MySQL, and then in the Driver Class field, select com.mysql.jdbc.driver. Click the Finish button, and TBC will create the configuration files and display a message box about it: 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 Reading triples from a relational database 57 The "Importing Relational Databases with D2RQ" online help panel has good background on this whole process, especially on the role that each of these configuration files play. Among other things, it points out that the property names assigned to the columns of the relational database tables are just a starting point that can be reconfigured by editing these files. For example, the tablename_columnname format of the property names that you use to access the data is only a default and can be changed. 9.3 Reading the data with a SPARQLMotion script To see how SPARQLMotion can use this data, we're going to create a simple script that gets the database's value for the president of the United States. After running it, we'll update the data using a MySQL tool and then run the SPARQLMotion script again to see the update reflected in the data that TopBraid is using. Start by creating a new SPARQLMotion file as described at Creating and running a SPARQLMotion script and call it mysqltest. Create a new SPARQLMotion script for this file, and for its initial module pick sml:importrdffromworkspace from the sml:importfromlocalmodules section of the sml:importmodules category. Call it GetWorldData, and when its icon appears, set this module's sml:sourcefilepath property to worlddb-test.rdf. This was one of the files created earlier by the configuration process, and it imports two others: the worlddb-schema.rdf schema file and the worlddb.d2rq file that serves as a placeholder for the actual data in the MySQL world database. sml:sourcefilepath is the only property that you need to set for this module. Next, we'll add a module with a SPARQLMotion query that asks the database for the name of the president of the United States. Add a Bind by select module from the Control Flow section of the SPARQLMotion palette and call it PresidentQuery. Set its sml:selectquery property to the following query (note how the namespace for the property names is the "Base URI of generated Schema file" value you assigned when configuring how TopBraid would import the MySQL data, as shown in the preceding screen shot): PREFIX w: <http://example.org/worlddb/myschema.owl#> 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

58 TopBraid Application Development Quickstart Guide Reading triples from a relational database SELECT?headOfState WHERE {?s w:country_name "United States".?s w:country_headofstate?headofstate. } This sml:selectquery property is the only one to set for this module, so close the Edit PresidentQuery dialog box, click Add connect on the SPARQLMotion palette, and connect the GetWorldData module icon to the new icon. When you work with a database like this, TopBraid keeps cached copies of the data to speed up later queries on the same data. This has obvious advantages, but it can be a disadvantage if you're more interested in data currency than in quick retrieval times. Our database is small, and we want to see changes reflected as soon as possible, so we're going to add a module that clears out this cache each time the script is run. Drag a Collect garbage module from the Control Flow section of the palette to your workspace and name it EmptyCache. Set its sml:baseuri property to the URI for the database you want to clear from the cache: http:// example.org/worlddb/mydatabase.rdf, which is the base URI for the worlddb.d2rq placeholder file. (This is the URI you entered in the "Base URI of Instances (Database)" field when you set up the initial import and configuration.) After configuring this one property, connect the President query module icon to the Empty cache icon. Select the Empty cache icon and click the green arrow icon to run this short script up to that module. You'll see in the Console view (a handy view when developing and debugging scripts) that the headofstate property has the value "Barack Obama": Let's add his middle initial. Update the data using your favorite MySQL tool. For example, from MySQL's command line interface, you could enter this: mysql> USE world Database changed mysql> UPDATE country SET HeadOfState="Barack H. Obama" -> WHERE HeadOfState="Barack Obama"; 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 Reading triples from a relational database 59 Run the SPARQLMotion script again, and you should see the update reflected in the Console view. If it wasn't for the script's Empty cache module, your SPARQL query might have used a cached copy of the data that did not include this updated value. As the online help tells us, it's a good idea to be careful with the sml:collectgarbage module, especially if you're developing a multi-user application where data is frequently updated. If quick access to updated data is not a priority in your application, omitting this module will mean faster response times for your users. It's up to the needs of your application, and it's good to know that you can have it either way. Instead of opening the worlddb-test.rdf file with your application like your script's GetWorldData did here, you're more likely to have your script open a file that you created that imports one or more of the configuration files generated above and perhaps some other files as well. (Again, read the "Importing Relational Databases with D2RQ" help panel to learn more about what each file can contribute to your application.) You could add additional data files and RDFS or OWL files describing relationships between the various imported files so that you can do interesting things with the combinations. For example, you could declare the properties that reference MySQL database columns to be subproperties of others declared for your application or declared in a standard vocabulary such as Dublin Core, GoodRelations, or OpenGraph. Something else that can ease your script development is importing the generated schema into your script in this case, dragging the worlddb-schema.rdf file onto the Import view of the mysqltest file. This way, the namespace prefixes will already be defined for you in the script file so that you can use autocompletion when you enter class and property names in your SPARQL queries. The sample application here didn't do much on its own, but when you combine the imported data with other data and metadata and take advantage of the other techniques described in this book, the ability to incorporate live relational data in your semantic web applications adds some great possibilities to what those applications can do. 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

60 TopBraid Application Development Quickstart Guide Reading triples from a relational database 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 10 Using XSLT in a semantic web application Topics: Creating XML Creating an XML version of SPARQL query results in a SPARQLMotion script Applying an XSLT stylesheet in a SPARQLMotion script Taking it further XML-based tools form the plumbing of modern electronic publishing systems, so when your semantic web application can create XML, it can easily feed content into one of these systems. The W3C standard XSLT is the most popular tool for converting one kind of XML into another, so in this chapter we'll see how SPARQLMotion scripts can use XSLT to create customized XML from your triples. (TopBraid Suite is also very good at reading XML; see the TopBraid Composer help panel "Creating, Importing, Querying, Saving XML documents with Semantic XML" for more on this.) Our example script will save its output as an XHTML file, but you can create XML conforming to any DTD or schema you like and save it as a file or return it via a web service.

62 TopBraid Application Development Quickstart Guide Using XSLT in a semantic web application 10.1 Creating XML TopBraid offers several ways to create XML. The Semantic XML feature lets you read arbitrary XML and gives you fine-grained control over XML that you create, but for a quick conversion of data to XML, there are simpler options. The W3C's RDF/XML serialization standard is the most well-known (if not the most popular) format for representing triples in XML, but its flexibility in the representation of triples can add complexity to the XSLT stylesheet, which must account for several possible locations of a given triple's subject, predicate, and object in various combinations of XML elements and attributes. The simplest, most straightforward XML format that a semantic web application can create is the W3C standard SPARQL Query Results XML Format. For example, with the following query against the kennedys.rdf file included with TopBraid Composer, PREFIX k: <http://topbraid.org/examples/kennedys#> SELECT?last?first?birth WHERE {?s k:lastname?last.?s k:firstname?first.?s k:birthyear?birth. } ORDER BY (?birth) the SPARQL query results XML representation of the result will have the following structure, with a head element listing the variables followed by a results element that contains a result child for each row of results returned by the SPARQL engine: <sparql xmlns="http://www.w3.org/2005/sparql-results#"> <head> <variable name="last"/> <variable name="first"/> <variable name="birth"/> </head> <results> <result> <binding name="last"> <literal>kennedy</literal> </binding> <binding name="first"> <literal>joseph</literal> </binding> <binding name="birth"> <literal datatype="http://www.w3.org/2001/xmlschema#integer">1888</literal> </binding> </result> <result> <binding name="last"> <literal>fitzgerald</literal> </binding> <binding name="first"> <literal>rose</literal> </binding> <binding name="birth"> <literal datatype="http://www.w3.org/2001/xmlschema#integer">1890</literal> </binding> </result> <!-- more result elements --> </results> </sparql> 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 XSLT in a semantic web application 63 As we'll see, a very brief XSLT stylesheet can handle this. 10.2 Creating an XML version of SPARQL query results in a SPARQLMotion script In our sample application, the XSLT stylesheet will create an XHTML version of the data returned by the query above. Start by creating a SPARQLMotion File in a new TopBraid Composer file called xsltdemo. Create a SPARQLMotion script in this file with an ImportRDFFromWorkspace initial module named GetKennedyData, and set its sml:sourcefilepath property to /TopBraid/Examples/kennedys.rdf. (For more details on following these steps, see Creating and running a SPARQLMotion script.) For your script's second module, drag a SerializeSPARQLResults module from the SPARQLMotion palette's Text Processing section onto the workspace and name it SelectRptData. Set the following three properties to configure it: Set its sml:selectquery property to the SPARQL query shown above. Set sm:outputvariable, a property that names the variable that will hold the results of the query, to queryresults. If the sml:serialization property is not already set to sm:xml, click the white triangle to display the context menu and select Add Existing, because you want to pick from the predefined list of legal values. On the Add existing dialog box, select sm:xml on the right. (If you click on sml:rdfserialization on the left of this dialog box, you'll see that this module can also output N3, NTriples, RDF/XML, and Turtle RDF.) Close the Edit SelectRptData dialog box and connect the GetKennedyData module's icon to the SelectRptData one. When you develop an XSLT stylesheet, you want some sample input XML data handy to test it, so let's have this script create a file for this. Add an Export to XML File icon from the Export to Local section of the palette and call it SaveTestXML. Set its sml:xml property to {?queryresults} to retrieve the data that your SelectRptData module stored in this variable, and set sml:targetfilepath to testdata.xml. That's all you need to set, so connect your SelectRptData icon to it as shown here: Select that third icon and click the green run arrow icon at the top of the SPARQLMotion workspace to run it, and you should see a testdata.xml file appear in the same directory as your script. This file will have XML that follows the structure of the example shown above. 10.3 Applying an XSLT stylesheet in a SPARQLMotion script First, you need to create the XSLT stylesheet file. If you're using an Eclipse-based XML editor such as oxygen or XML Spy, go ahead and use one of those editors. Otherwise, after selecting the folder in the Navigator view where you put your xsltdemo file, pick New from the File menu. Because you're not creating one of the specialized files that TopBraid Composer typically deals with, pick Other from the cascade menu. Pick XML from the XML section of the New dialog box and click Next. Call the file createkennedyhtmlrpt.xsl, and click Finish on the New XML File dialog box. (Clicking Next on that dialog would lead to wizards that make the process more complicated than this example requires.) If the default Eclipse XML editor displays with the Design tab active, which is for tree-based viewing of a file, click the Source tab. 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

64 TopBraid Application Development Quickstart Guide Using XSLT in a semantic web application Paste the following stylesheet, which was developed using the testdata.xml file created above as input, onto the editor and save the stylesheet: <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/xsl/transform" xmlns:sp="http://www.w3.org/2005/sparql-results#" xmlns="http://www.w3.org/1999/xhtml"> <xsl:template match="sp:sparql"> <html> <head><title>xslt demo</title></head> <body> <table border="1"> <tr> <th>last Name</th> <th>first Name</th> <th>birth</th> </tr> <xsl:apply-templates/> </table> </body> </html> </xsl:template> <xsl:template match="sp:result"> <tr> <td><xsl:value-of select="sp:binding[@name='last']"/></td> <td><xsl:value-of select="sp:binding[@name='first']"/></td> <td><xsl:value-of select="sp:binding[@name='birth']"/></td> </tr> </xsl:template> </xsl:stylesheet> If you create the stylesheet outside of TopBraid Composer, make sure to put it in the same folder as your script. Then, right-click the folder's icon in the Navigator view and select Refresh so that Eclipse knows that the new file is there. The stylesheet converts the XML into an XHTML file with a table that has a row for each row of the result set. The next module to add to the SPARQLMotion script is the one that applies this stylesheet to the XML. Drag a Convert XML by XSLT module from the XML Processing section of the palette, name it CreateHTML, and configure it by setting the following three properties: Set sm:outputvariable to HTMLResult. This variable will store the result of the XSLT transformation. Set sml:template to {?stylesheet}. We haven't added the script module that sets this variable yet, but will soon. Set sml:xml to {?queryresults}. As we saw above, the SelectRptData module stores the XML of the query results in this variable. The SaveTestXML module also used the contents of this variable. Connect the SelectRptData module to your new CreateHTMLRpt module. SelectRptData is already connected to SaveTestXML, but sending a module's output to multiple modules is a common technique in SPARQLMotion scripts to create variations on the same processing through code re-use. To read the createkennedyhtmlrpt.xsl stylesheet disk file and send its contents to the CreateHTMLRpt module for use in the XSLT transformation, drag an ImportTextFile module from the Import from Local section of the palette and name it ReadXSLTStylesheet. Tell it where to find the stylesheet file by setting its sml:sourcefilepath property to createkennedyhtmlrpt.xsl, and then set its sm:outputvariable property to stylesheet the variable where the CreateHTMLRpt module will expect to find the text of the stylesheet 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 XSLT in a semantic web application 65 that it applies to the output of the SelectRptData module. Once you're finished setting these properties, connect the ReadXSLTStylesheet module to the CreateHTMLRpt module. The last module will save the results of the XSLT transformation in a disk file. Drag another ExportToXMLFile module from the Export to Local section of the palette and name it SaveHTMLFile. Set its sml:xml property to {?HTMLResult} so that it reads the variable set by the CreateHTML module, and then indicate where to save this variable's value by setting the module's sml:targetfilepath property to KennedyRpt.html. Connect the CreateHTML module to the new SaveHTMLFile module. Your completed script should look something like this: To test it, select the CreateHTML icon and click the green arrow icon to run all the modules leading up to that one. (note that SaveTestXML is not one of the modules leading up to it.) You should see a KennedyRpt.html file appear in the same project as the xsltdemo file that holds your script. In a browser, this HTML file will look like this: Now that the script is applying the XSLT stylesheet to the XML and creating the HTML, you can right-click your SaveTestXML script module and select Delete to remove it from your script if you want to, but maybe you don't want to if you ever need to refine the SELECT query in the SelectRptData module or the XSLT stylesheet that the ReadXSLTStylesheet module feeds to the CreateHTML module, the ability to create another disk file of test data may prove handy in the future. 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

66 TopBraid Application Development Quickstart Guide Using XSLT in a semantic web application This also demonstrates another technique of sophisticated SPARQLMotion scripts: the ability to share common processing modules for different output modules. You essentially have two SPARQLMotion scripts here SaveTestXML and SaveHTMLFile which share several modules. That's why, when you pick Edit SPARQLMotion script or Execute SPARQLMotion modules from the Scripts menu, you'll see these two "scripts" listed as choices, even though they're graphically represented as a single flow chart with a choice of end points. 10.4 Taking it further If you had created this script as a web service, then instead of ending with an Export to XML File module from the Export to Local section of the palette, you could route the XML from the Convert XML by XSLT module to a Return XML module from the Export to Remote section of the palette. (Or, that could be a third endpoint added to the two discussed above!) If you set the Return XML module's sml:mimetype property to text/html and had it return XHTML like the xsltdemo script above does, you'd be setting up the dynamic creation of a web page, so that users browsing to the URL that invoked the service would think that they were just linking to a web page. Of course, it doesn't have to return HTML. It can return anything that an XSLT script can create, and you can set sml:mimetype to any valid HTTP MIME type, and any application that can do an HTTP GET can request delivery of this data, which opens up a wide range of possibilities for the contributions that this application can make to a larger system. 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 11 Deploying your TopBraid applications on a TopBraid Live Enterprise server Topics: Referencing your server Deploying apps to the server Installing TopBraid Ensemble Apps on the Enterprise Server So far, as we've learned how to call a SPARQLMotion script from TopBraid Ensemble or from a web service, we've always used the TopBraid Live (TBL) Personal Server that's built into TBC to test our applications. The reason developers create these applications on TBC, though, is for others to use, and that's where the TBL Enterprise Server (purchased separately from TBC) comes in. When you deploy your TopBraid applications on an Enterprise TBL Server, many users can use your applications simultaneously, and none of them need a copy of TopBraid Composer. In this chapter, we'll see how simple it is to copy your applications to a TBL Enterprise Server where you end users have access to them. Remember, those "end users" aren't always people when you deploy a semantic web service to a TBL Enterprise Server, it can be a first-class member of any number of Service-Oriented Architecture applications, serving as a building block for larger applications by fulfilling requests from automated processes elsewhere in the application architecture.

68 TopBraid Application Development Quickstart Guide Deploying your TopBraid applications on a TopBraid Live Enterprise server 11.1 Referencing your server In the following example, we'll deploy an application to a TBL Enterprise Server running on a local machine. It's configured to run with the Apache web server as a Tomcat servlet listening to port 8080, making the URL of the server http://localhost:8080/tbl/tbl. If the Enterprise Server was installed on a host named www.domain.com and used the same port, the URL would be http://www.domain.com:8080/tbl/tbl, so you would substitute that name in the steps below. 11.2 Deploying apps to the server If you package all the files needed to run an application in a single project, which is a root directory in TBC's Navigator view, it's a convenient way to upload a collection of related files to the TBL Enterprise Server. So, for example, if the personscripts.sms.n3 file that you created in the last chapter is not in its own project, create one called personproject by right-clicking in the Navigator view and picking New -> Project -> Project and then move the file there. To deploy this project, right-click on the project folder icon in TBC's Navigator view and pick Export. On the Export dialog box, select Deploy Project to TopBraid Live Server from the TopBraid Composer section of the menu and click the Next button. On the Deploy Project to TopBraid Live Server dialog box that appears, enter the URL of the server where you want to send your app (for example, http://localhost:8080/tbl/tbl, as described above) in the Server URL field. The remaining fields are self-explanatory: enter a user name and password if the server was set up to require them and check Overwrite existing project with the same name if there is any chance that a project with that name already exists. For serious production applications available over a network to a wide variety of users, passwordcontrolled access to applications is usually a good idea, especially if the application lets users change the data. Click the Finish button, and TBC will show you upload progress and let you know it's finished: 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 Deploying your TopBraid applications on a TopBraid Live Enterprise server 69 If you sent a project with the personscripts.sms.n3 file created in the Calling a SPARQLMotion script from TopBraid Ensemble chapter to the Enterprise server, and a different computer can access that one as http:// www.domain.com:8080/tbl/tbl/ or http://192.168.1.2:8080/tbl/tbl/, then sending a browser on the other computer to one of these URLs will display the TopBraid Suite Console screen. On that computer you can then follow all the steps described in that chapter's Testing it section, even though you're doing it remotely, right up through the use of the "Age at Death" menu choice that you implemented. You can upload a web service to the Enterprise TBL server the same way. For example, in Creating and running a semantic web service we saw that after defining a web service in the file ws1.sms.n3 and registering the function that invokes the service by selecting Refresh/Display SPARQLMotion functions from the TBC Script menu, you could test this web service by entering the following URL in a browser: http://localhost:8083/tbl/actions?action=sparqlmotion&id=searchkennedys&arg1=rob This sent the request to the TBL Personal Server included with TBC. To deploy the web service on the Enterprise Server, upload the project that holds the ws1.sms.n3 file file as described above. Then, if the server is running on the local machine and listening to port 8080, you can test it with the following URL: 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

70 TopBraid Application Development Quickstart Guide Deploying your TopBraid applications on a TopBraid Live Enterprise server http://localhost:8080/tbl/tbl/actions?action=sparqlmotion&id=searchkennedys&arg1=rob To call this web service from another computer on the same network (which could be another one on your intranet, or a computer on the public internet if the machine running the TBL Enterprise Server is accessible there), substitute the appropriate computer name or IP address for "localhost" in that URL. 11.3 Installing TopBraid Ensemble Apps on the Enterprise Server As we've seen in an earlier chapter, when you create a TopBraid Ensemble (TBE) application, you save your screen layout with the Save App button. After clicking this button, the Save To field on the Save Application As dialog box shows server.topbraidlive.org as the default project in which to save the application, but you can select another one. You can't create a new project from within TBE, so if you want to save the application in a particular project, make sure you've already created that project you need in TBC's Navigator view. If you named your TBE application MyTBEApp and saved it in a project named MyTBEProj, in TBC's Navigator view you'll see that it stored MyTBEApp.n3 in a subdirectory of MyTBEProj named user-applications. Once you upload the MyTBEProj project to the TBL Enterprise Server the same way you uploaded the other projects described above, you'll see MyTBEApp listed on the right side of TopBraid Live's TopBraid Suite Console screen at http://localhost:8080/tbl/tbl/ under the column heading "Applications Under Development": When you click the application name on the TopBraidSuite Console, if it wasn't saved with a particular set of data, it will prompt you to pick one. Once you see the application screen you designed, your browser's navigation toolbar will show the URL that you would use (once you substituted the computer name for "localhost" as described above, if necessary) to have your end users use that application with that data. It will be a long URL, so instead of actually giving that URL to your users, you'd be more likely to use it as the href value of a link on a web page that takes them to the application. TopBraid Composer puts a lot of capabilities at your fingertips. When you deploy the web services, TBE applications, and any SPARQLMotion scripts called by those TBE applications from TBC to a TBL Enterprise Server, you can make the power of your semantic web applications available to a wide range of people and applications throughout your enterprise or even throughout the World Wide Web. That's a lot of power. 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