The Mobius Project, OSU Department of Biomedical Informatics, Multiscale Computing Laboratory

Mako/MakoDB QuickStart

Introduction

Mako is a service for exposing data resources as XML data resources on the Grid. In this QuickStart we will be exposing MakoDB, a Mobius XML database, layered on top of MySQL and optimized for working within a Grid environment.

Minimal Configuration

If you have not already done so, install the Mobius software and its prerequisites.

Change to the mobius_mako.../conf directory and edit localhost-mako-config.xml

Toward the bottom of the file, in the <resource="makoDBConfig" ... > resource block, fill in your password, thus <password>your-mysql-password</password>,

MySQL needs to be installed and running for this example and the <user> should be set to an account that has administrative privileges on MySQL (usually root or admin).

MakoDB, an XML Database layered on top of MySQL, will be used for this quickstart example. The sample localhost-mako-config.xml file contains parameters for establishing collections within MakoDB. You should note that there are configuration files in the conf directory with parameters established for allowing a Mako to talk to other XML databases, including Xindice, XQuark Bridge, and eXist.

Starting the Mako and Adding a Data Service and Collection

cd to /mobius_mako.../scripts

$ ./startMako.bat ../conf/localhost-mako-config.xml &

You should see output like the following:

INFO - Dec 14, 2004 11:08:35 AM  -- The collections database MobiusMako_makodb was created
INFO - Dec 14, 2004 11:08:35 AM  -- The collections table(s) were created
INFO - Dec 14, 2004 11:08:35 AM  -- Server started on MAKO://localhost at Tue Dec 14 11:08:35 EST 2004
INFO - Dec 14, 2004 11:08:35 AM  -- Setting Service Identifier to MAKO://localhost
INFO - Dec 14, 2004 11:08:35 AM  -- Listening using the protocol TCP on the host 0.0.0.0, port 3940

Note: If you are upgrading from a previous version of Mobius, starting a Mako will automatically upgrade your database schemas.

Hit return and type,
$ ./getCollectionList.bat -service MAKO://localhost to see the list of collections currently running on localhost. At this point, there will be no collections listed. For this quickstart, you will create collections using the Mako View.

For a full list of available command line utilities, see the Mako command line utilities reference.

$ ./makoViewer.bat & starts the Mako View Java GUI application.

You'll see a window with a world icon and "Mobius Grid Services." This is the root of all services you'll establish within the Mako.

• Right-click the icon and select "Add Grid Service"
• Enter MAKO://localhost in the "Grid Service Id" field and click "Add". (See Fig 1)
• Add a collection to the service: Right-click on the localhost icon in the Mako View and select "Create Collection"
• Enter a name for the collection in the "Collection" field at the top of the window. For this example, use testMakoDB as the name. You will see below that "MAKO://localhost" has been set as the name for your XML data service. If you had already established other data services, you would be able to put checks in the boxes next to any of the service names upon which you wished to establish a new collection.
• Click "Create." (See Fig 2)

After you add a default data service (a MakoDB service, in this case) and create a collection, in this case, testMakoDB, you will see that MySQL has two new databases, named for their connection and function:
mobiusmako_makodb which will hold information that identifies what collections you have established in your Mako; in this case, it contains a single row, since you only have one collection set up, and
mobiusmako_makodb_collection_1 which holds the attributes of the collection; in this case, it will hold all of the attributes for the first collection you have established in the Mako (testMakoDB).

Adding a Schema, Data, and Performing Queries

Mako is a strongly typed system. The data elements that you store in and query from a Mako need to be described before they can be stored. In order to do this, we use XML schemas. For a Mako to accept an XML document, it is required that a schema describing that document be submitted to the Mako or that the Mako be able to locate a schema describing the XML data. In this QuickStart, we are running a Mako as a stand-alone service and so, below, before adding XML data to the Mako, we manually add a schema describing that data.

In the usual case—when Mako is used within a larger Grid environment—the Mako would be configured to obtain schemas from a GME. For a description of this architecture, see our overview of Mobius. Also see the Mako configuration page for how one sets up a Mako so that it requests schema from a GME on startup.

1. Let's submit an xml schema describing the structure of some XML data,
2. submit some xml data that conforms to the schema,
3. and perform some XPath queries against that data to glean some information from the xml.

Submit a schema to the Mako

• Right-click on the testMakoDB collection in Mako View and select "Submit Schema." The window will show you the path of the collection to which you are applying a schema, testMakoDB in this case.
• Click the "Add..." button and browse to the xml directory. Select "bookstore.xsd," the schema definition that will describe the XML entries you'll import in the next step. The path to the file will be entered into the "Add" field.
• Make sure the checkbox next to MAKO://localhost is checked and click "Submit." A schema result window will display, describing the action you just took and giving the "Status" of the submission (OK).
• You may close the results window.

Submit some XML conforming to the schema

• Right-click the "testMakoDB" icon and select "Submit XML" in the dialog window
• "Browse" to xml/BookStore.xml, a sample file containing fake book descriptions.
• Click "Submit" and you will see another result dialog window. The document you submitted has been assigned a unique ID.

If you want to see a representation of the XML, click the XML button on the result dialog and you'll be given a two-panelled window. The left pane shows a browsable tree view of the XML file via which you can inspect all of the elements and attributes of the BookStore.xml file. The window also allows you to add XML namespaces to the document. (See Fig 3)

Perform a couple of XPath queries on the data

• Again, right-click on testMakoDB
• Select "XPath Query." The query editor window appears. You'll see a field containing the testMakoDB collection and an XPath, which is set to /, the root of the collection, by default.
• Click "Query" and, in the dialog window, the "XML" button. You'll see the XML browser window that you saw earlier. We want to add namespaces definitions to the XPath query editor so that we can perform queries on them.
• To do this, click the "Add Namespaces to Namespace Definitions" button, which will parse the XML file and grab every namespace associated with that document.
• Close the XML browser and the XPath query dialog window and then reload the XPath query editor by selecting "XPath Query" from the dropdown menu associated with the "testMakoDB" icon. This time you'll see that the three namespaces from the XML document have been added to the "Available Namespace Definitions" area.

Let's type in an XPath query to return results for the titles of all of the books in our bookstore:

First, we choose a default namespace upon which to perform the query:

• Click "Edit" on the XPath Query dialog window. You'll see the three namespaces associated with the BookStore document.
• Hover the cursor over the last one in the list, with the namespace prefix mobius. A tooltip will appear: "Right click a definition to set as default." The projectmobius/1/Bookstore namespace appears in the "Default Namespace" field.
• Click "Ok."

Back in the query dialog window, enter the following query in the XPath field to return items for every title in the bookstore:

/BookStore/Book/Title

Each returned result contains the name of the data service, collection, and a unique document id generated for the query result. The query results return well-formed XML results that can be submitted to other collections or re-added to the current collection. Clicking the "XML" button on any entry will bring up the XML browser containing the XML result document.

Here is a query that grabs all books classified as "drama" (See Fig 4):
/BookStore/Book[@section="drama"]

More complicated queries can be performed. Mako supports the following XPath query syntax and its permutations:

/A

Selects all documents with root element A.

/A/B

Select all B elements which are children of a document with root element A.

//B

Select all B elements, regardless of their position in their document.

/A/B[@name]

Select all elements of B which are children of the root element A and have elements which have attribute name.

/A/B/[C/@name]

Select all elements of B which are children of the root element A and have child C elements with the attribute name.

//B[@name]

Select B elements which have attribute name, regardless of their position in their document.

/B[@name='b']

Select all documents with root element B which have attribute name with value 'b'.

/B[@name1='b' and @name2='c']

Select all documents with root element B which have attribute name1 with value 'b' and attribute name2 with value 'c'.

/B[@name1<='b' or @name2>'c']

Select all documents with root element B which have attribute name1 with value less than or equal to 'b' or name2 attributes greater than 'c'.

/A/text()

Select the value of the text node child of all documents with root element A.

There is an excellent XPath tutorial at zvon.org.

Removing XML Data and Collections From the Mako

To remove XML, select "Remove XML" from the testMakoDB contextual menu. You can either enter the document id or an XPath. When using the Mako View, you can only remove an entire document from a collection. If it's necessary to remove a portion of a document or perform an update to the document, you can use the submitXUpdate script in the scripts directory. In coming releases, the Mako Viewer will support XUpdate.

To remove a collection, again, use the contextual menu that appears when you right-click any of the icons within the Mako View main window. Choose "Remove Collection" and enter the name of the collection, testMakoDB in this case. Click "Remove."

In this quickstart example, we are using the MakoDB XML database. After removing the testMakoDB collection, you will notice that the database instance "mobiusmako_makodb_collection_1" has been deleted from MySQL and the "mobiusmako_makodb" database has had its "collections" table updated to reflect the removal of the collection.

Stopping the Mako

To cleanly shutdown the localhost Mako service, cd into /scripts:
$ ./stopMako.bat -services MAKO://localhost