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

Mako/VMako QuickStart

• running a single Mako
• accessing multiple Makos via a VMako (virtual Mako)
• connecting Makos to other services

Minimal Configuration

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, replace <password /> with <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, XBridge, 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 - Oct 7, 2004 2:19:20 PM  -- The collections database localhost_1_mako was created
INFO - Oct 7, 2004 2:19:20 PM  -- The collections table(s) were created
INFO - Oct 7, 2004 2:19:20 PM  -- Server started on localhost at Thu Oct 07 14:19:20 EDT 2004
INFO - Oct 7, 2004 2:19:20 PM  -- Setting Service Identifier to localhost
INFO - Oct 7, 2004 2:19:20 PM  -- Listening using the protocol TCP on the host 0.0.0.0, port 3940

In a new shell or command window,
$ ./getCollectionList.bat -service 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.

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

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

• Right-click the icon and select "Add XML DataService"
• Enter localhost in the "Service Name" field and click "Add Data Service." (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 testMakeDB as the name. You will see below that "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:
localhost_1_makoi 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
localhost_1_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

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.
• 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 "localhost" 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 mobius namespace appears in the "Default Name" field.
• Click "Ok."

Back in the query dialog window, enter the following query 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

Select the root element A.

/A/B

Select all elements B which are children of the root element A.

//B

Select all elements B.

/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.

/B[@name='b']

Select B elements which have attribute name with value 'b'.

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

Select B elements which have attribute name1 with value 'b' and attribute name2 with value 'c'.

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

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

/A/text()

Select A elements which have text node children.

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 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 "localhost_1_collection_1" has been deleted from MySQL and the "localhost_1_mako" 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 localhost

Virtual Mako (VMako): Aggregating Mako Servers

A VMako is a single Mako server that acts as a front-end to multiple remote Mako instances. The single VMako instance maps its (virtual) collections onto a user-defined set of remote Mako collections. This reduces the complexity for the client application, presenting a single virtualized interface to a number of distinct, federated Makos. The primary purpose for a Virtual Mako is to enable distributed query execution. In a Virtual Mako, requests are broken down into sub-queries and sent to appropriate remote Makos. Responses are then aggregated at the VMako and returned to the client. Additionally, collections added to a VMako can be distributed across the remote Makos, thus reducing the load carried by any single instance. The default "ingestor" class uses a round-robin algorithm for distributing load across the federated Makos.

As in the other QuickStarts, before instantiating a VMako, you will want to edit the configuration file. There is a localhost-vmako-config.xml file in the /conf directory. It contains the configuration to stand up a basic VMako instance. In the <MobiusNetworkServiceDescriptor ...> tag, edit the "hostname" attribute as appropriate. Also set the "serviceId" in the <serviceIdentifier ...> tag, immediately below it.

A VMako aggregates other Mako services. Because of this, it needs no configuration for MySQL. Instead it can either be instantiated alone and then you can use the Mako Viewer or command line utilities to manually aggregate other Makos "within" it. Or you instantiate the VMako so that it reads a cache file and automatically "ingests" collections from already running Makos.

The resource element whose "name" attribute is set to "vmakoConfig" contains a sub-element called <vmako-storage ...> which takes only a "file" attribute. In the distribution's localhost-vmako-config.xml file, that attribute is set to "vmako-storage.xml".

Let's start the VMako
./startMako.bat ../conf/localhost-vmako-config.xml

If you have left the <vmako-storage ...> element with its default "file" value, then any collections you add (via the Mako Viewer or the command line) will be recorded in the vmako-storage.xml file. The file will be created in the /scripts directory by default (since that is where the startMako script is). But you can also specify a path when setting the value for "file". The collections you add to your VMako during the session will be recorded and, the next time you start the VMako, the file will be read in and the collections ingested.

In the /conf directory, there is an example VMako cache file called "vmako-cache-example.xml". We can load the remote Makos and collections specified in this file when we start our VMako.

Edit the file and point the "serviceId" attribute within the <xml-data-service ...> at a remote Mako service. In the <xml-collection-handle ...> tag, repeat the service id and fill out the "collectionName" attribute with the XPath path to a collection on that server that you would like to aggregate under your VMako. In the <virtual-collection ...> tag, fill out the "name" attribute with a virtual collection name of your choosing (here we have used TestVirtualCollection).

Restart the VMako, as above. You will see output similar to the following:

INFO - Nov 5, 2004 1:02:27 PM  -- Adding service dc01
INFO - Nov 5, 2004 1:02:27 PM  -- Adding service dc02
INFO - Nov 5, 2004 1:02:28 PM  -- Adding the virtual collection TestVirtualCollection
INFO - Nov 5, 2004 1:02:28 PM  -- Server started on localhost at Fri Nov 05 13:02:28 EST 2004
INFO - Nov 5, 2004 1:02:28 PM  -- Setting Service Identifier to localhost
INFO - Nov 5, 2004 1:02:28 PM  -- Listening using the protocol TCP on the host 0.0.0.0, port 3940

Now, any XPath queries performed via command line or viewer against the TestVirtualCollection collection will, in fact, be run against the collections on the remote nodes you configured in the "vmako-cache-example.xml" file ( in this case, dc01 and dc02).

Adding a Handle Factory to Connect to other Mobius Services

There will probably be occassions in which you will want to connect to a Mako or group of running Makos through some means other than the default handle. You might want to locate running Makos on remote hosts by querying some type of Grid service registry, for example.

Our online documentation has an example of how to do this by calling a handle factory to make a connection to another service.