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

Mako Configuration and Application Programming Interfaces (APIs)

• configuration files
• APIs
• using other data services/stores

Mako Configuration File Settings

There is a sample configuration file available in /conf directory The file localhost-mako-config.xml contains a basic setup for a Mako server to run on the local machine.

The localhost config files should never be used for more than single Mako testing purposes. When other Makos connect to it, it will identify itself as localhost, which when the connecting Mako attempts to resolve will cause problems.

The Mako server contains several resources that provide certain functionality and information to other Mako components. These resources are instantiated by the Mako server at startup, and are configured by the config file. The four resources for the Mako are:

1. Mobius Configuration <resource name="mobiusConfig"... >
2. Mako Configuration <resource name="makoConfig"... >
3. Mako Database Configuration <resource name="makoDBConfig"... >

These resources must be specified in order in the config file due to dependencies on the other resources, and all of them must exist.

Mobius Configuration

The Mobius Configuration section is common to all Mobius Network Services. This block defines the Network Service Descriptor the service will use when identifying itself on the Grid, and the handlers for the various protocols in the server. This resource is defined under the element <resource name="mobiusConfig" class="org.projectmobius.services.common.MobiusConfiguration">. All resources are specified in this way; the name attribute is the name the resource will have in the resource manager and the class attribute is the class within Mobius that will be associated with that resource.

The Mobius Configuration has three elements:

<MobiusNetworkServiceDescriptor>

All Mobius services have a Mobius Network Service Descriptor that they use to describe themselves to other services within Mobius. The "serviceType" attribute defines what kind of service this is. For the Mako, set this to MAKO. The hostname attribute defines the name of the host this service is running on. The children of the Mobius Network Service Descriptor describe the service:

<serviceIdentifier>

This element describes the service identification string used to uniquely identify a Mobius Service within the Grid.

<ports>

This element describes the ports the service will use for communication.

<aliases>

This element defines any aliases for the host of the service. Aliases are needed when a host has more than one physical network connection. An <alias> element has attributes id and hostname that define the identification and the hostname that each network interface maps to. A host might have multiple hostnames if it is part of a cluster and/or has multiple network interface cards installed. If the host does not have any extra network interfaces, it is safe to leave the <aliases> element empty.

<handlers>

The handlers define what classes the Mako should use to handle certain protocol requests and responses. Changing these from the way they are defined in the example localhost-mako-config.xml will likely break some functionality.

<serviceRegistry>

This element contains the service ID for the service registry the Mako will use to register itself, if one is running. (See localhost-mako-registrar-config.xml for the necessary parameters for Mako to automatically register itself on startup.

Mako Configuration

The Mako Configuration resource keeps track of the factories specific to the Mako Server. This resource is defined under the <resource name="makoConfig" class="org.projectmobius.services.mako.MakoConfiguration"> element. This element has a child called <mako-configuration ...> that specifies the information Mako Configuration needs:

<factories>

The factories define what class the Mako will use to produce handles to other Makos. If no factories element is present, the Mako will use a default factory.

Mako Database Configuration

This resource contains information about the databases the Mako will use and enables access and modification of the databases. This resource is defined under the element

<resource name="makoDBConfig" class="org.projectmobius.services.makodb.MakoDBConfiguration"gt; The resource element has a child called <makoDB-configuration ...>. Its "id" attribute sets the name of the database in which the schemata are stored.

The Mako Database Configuration has several important elements configurable elements:

<name>

This element specifies the name of the database. For MySQL's root database, this should be nothing.

<driver>

The driver class for accessing the MySQL database.

<urlPrefix>

The url prefix for accessing the database.

<host>

The host the database lives on. Usually, this will be localhost.

<port>

The port via which the database can be accessed.

<username>

The username to log into the database with. This username must have privileges to add and remove databases and tables.

<password>

The password to authenticate the username.

<pool>

This element determines how many connections to the database will be made initially. When the Mako needs to communicate with the database, it will get a connection, and when its done, it releases it. Should the it run out of available connections, it will make a new one, but this causes a slight delay. Set the pool value in anticipation of how many concurrent database operations will be needed.

Mako Application Programming Interfaces (APIs)

Factories and handles are the foundation of the Mako API. Factories create handles to Mako services, providing a clean interface. The primary handle factory can be obtained from the MakoClientConfiguration object, the name of which can be determined from the config file for the Mako server. From this factory, handles to the data service, collection, or individual document can all be obtained.

Factories

The available XMLCollectionFactory and XMLDataServiceFactory allow for easy creation of handles. By passing the name of the data service to the XMLDataServiceFactory, an XMLDataServiceHandle can be obtained using the getXMLDataServiceHandle method. The highest level of functionality is gained by employing handles. The typical process for building Mako applications will involve using a factory to obtain a handle. For example, a collection handle can be created by combininig the XMLDataServiceHandle with the XMLCollectionFactory and calling the getXMLCollectionHandle method.

Handles

There are five types of handles used commonly in Mobius.

1. XMLCollectionHandle
2. XMLDataServiceHandle
3. XMLDocumentHandle
4. XMLAttributeHandle
5. XMLTextHandle

XMLCollectionHandle

The XMLCollectionHandle is used for actions at the table level. Typical interaction is to submit XPath queries, using the submitXPath method. Interaction at this level will allow for modifications to be made to all of the documents within the collection. Support at the collection level includes XPath, XUpdate, and individual document handling, such as creating XMLDocumentHandles.

XMLDataServiceHandle

This represents the entirety of the data service, including all of its collections. Creating a collection is simple with this handle, requiring only the name to be passed into the getXMLCollectionHandle method.

XMLDocumentHandle

Documents in a Mako are lazy loaded, in that they can be either materialized (displayed in full content), or lower levels can be represented as DocumentReferences. A DocumentReference is a pointer to the actual document but requires less overhead than the weight of the actual document. This allows for Makos to be used with very large data sets. XMLDocumentHandles are commonly used in the submitXPath methods, because these calls return a List of XMLDocumentHandles which fulfill the XPath.

XMLAttributeHandle

The attribute handle is a special case in which the XPath request returns attributes. An attribute is a name/value pair.

XMLTextHandle

The text handle is a special case in which the XPath request returns text elements. A text handle can only return its content.

Mako API layers

The DOM

org.projectmobius.dom.xml contains the class Element for use with the DOM. Use of this class is similar to that of JDom, with a few notable differences, namely the inclusion of metadata associated with the Element, such as its documentHandle.

Creation of the element requires that you pass in the XMLDocumentHandle, a "MobiusBoolean" for whether you want children lazy loaded or not, or both. Nodes are handled either as real elements or as text elements. Real Elements are those created using the Element class and created with a XMLDocumentHandle. They have their own distinct handle into the database and therefore can have XUpdate and XPath queries submitted directly to them. If there is no XMLDocumentHandle for the node, it is a text node and has the XMLDocumentHandle of the parent, which may be another text node. In this case, all share the XMLDocumentHandle of the nearest real element. Creation of text nodes is done with the fromXML method or via any node that is lazy loaded.

Examples

First, we use the config file that was used in the Mako servers creation to get an XMLDataServiceFactory, for which we will use the DefaultXMLDataServiceFactory:

MakoClientConfiguration config = MakoClientConfiguration.getInstance();
config.setXMLDataServiceFactory(new DefaultXMLDataServiceFactory());
XMLDataServiceFactory factory = config.getXMLDataServiceFactory();

From the factory, we pass a hostname into getXMLDataServiceHandle to get an XMLDataServiceHandle:

XMLDataServiceHandle dataService = factory.getXMLDataServiceHandle("localhost");

With the XMLDataServiceHandle we can modify things at the dataservice level. For example, we could add a collection or just get an XMLCollectionHandle:

XMLCollectionHandle collectionHandle = dataService.getCollection("CollectionName");

From here, either a document ID or an XPath query is needed to obtain document handles:

List xpathHits = collectionHandle.submitXPath("/");
XMLDocumentHandle handle = (XMLDocumentHandle) xpathHits.get(0);

or

XMLDocumentHandle handle = collectionHandle.getDocumentHandle("123456");

If we then want an Element version of the handle, we can do the following:

Element e = new Element(handle, new MobiusBoolean(true));

Creating New Data Services

Mako has support for several XML data services/stores: eXist, Xindice, X-Bridge, and Mobius' own XML data store MakoDB, the default data service. Plugging Mako into eXist, Xindice, or X-Bridge is accomplished by editing the appropriate configuration files in the conf/ directory and passing Mako that file on startup. For easy identification, these files are each named with the XML service's name. But if you require your own data service, expansion is easy.

The following example demonstrates how to implement the new service or customize a handler that has already been implemented.

An example data service found in the org.projectmobius.example.dataservice package places files in a directory specified in the localhost-exampledsconfig.xml config file. (in the conf/ directory).

The process of creating a data service involves:

• creating a manager that parses a resource and initializes the data service
• creating a configuration file for the parser
• creating handlers to extend support to the data service

A Manager is an implementation of the MobiusConfiguration class and, as such, requires a parse function. As seen in the example data service, the parse function can use the resource manager to locate elements found in the Mako configuration resource portion of the config file. The parse function should also initialize elements in the config file you create or begin an initialization function (as seen in the example data service). To access the resource manager, you can use:

this.makoConfiguration = (MakoConfiguration)resourceManager
.getResource("makoConfig");

Next, you need to create a config file. To do so, follow the examples found in the conf/ directory. You need a makoConfig resource block, a mobiusConfig resource block, and a resource with the configuration you wish to specify. Make sure to also specify which handlers to use. (It is recommended that you write your own.) Finally, specify any other custom configurations you wish.

To create your own resource, add a new resource XML block and fill it with the sub elements you need passed into your custom data service. In the localhost-exampledsconfig.xml, the custom resource contains only the path, which is where the files will be stored.

The final stage is to create custom handlers. There are many examples of this, not only in the example data service. Every implemented data service in Mako has a folder of handlers, all of which extend their respective parent class. For the example, submit, retrieve, collection list, create collection, and remove collection handlers are created which move the xml in the request to the file system or look up an id and send it back in a response.

With the files completed, start Mako as you normally would via the command line script and pass in your newly created config file.