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

Global Model Exchange (GME) QuickStart

Introduction

GME is a DNS-like data definintion registry and exchange service that can run in a Grid/distributed computing environment. GME is responsible for storing and linking together data models, meta-descriptions of data in the form of XML schema. It enables other services to publish, retrieve, discover, and, remove data models. GME services are arrayed via a DNS-like architecture, in which parent-child namespaces organize the connection of GME nodes into a hierarchical tree structure.

Minimal Configuration

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

To demonstrate basic use of GME, we'll edit the localhost-gme-config.xml in the /conf directory. There is also a localhost-gme-registrar-config.xml file, which serves as an example for how to connect a GME to a Registrar service. We use this file for a later QuickStart demonstration.

Note that localhost config files should not be used for anything other than single GME instance testing. When other GMEs attempt to connect to instances running as localhost, they will be unable to satisfactorily resolve the name and GME will not function properly.

For this QuickStart, we'll be running GME nodes on multiple, remote machines and accessing the nodes from the local machine. This will give a truer picture of how GME is used in practice. If you don't have access to other machines, you can follow this QuickStart, starting a GME using the localhost-gme-config.xml config file.

Change to the conf directory in the mobius_gme... subdirectory of the gme directory and open the localhost-gme-config.xml file in an editor.

Put in your MySQL "root" or "admin" password and change the "username" as appropriate within the <database> section of the <resource name="gmeConfig"...> resource block (the second major element in the config file).

GME config files contain a lot of parameters. There are two key resource blocks:

1. Mobius Configuration
   <resource name="mobiusConfig">, which defines the Network Service Descriptor the service will use when identifying itself on the grid, how to connect to the grid, what requests can be handled, and how to talk to other services
2. GME Configuration
   <resource name="gmeConfig" ... >, which defines things specific to the GME Server, including namespaces, how to find authoritative and subordinate related GMEs, server policies, and database connection information

Log onto a number of remote machines and edit the localhost-gme-config.xml files on those machines, as well. On the remote machines, in addition to any necessary modifications to the MySQL username and password, you will also want to edit two other parameters.

In the first resource block, on each remote machine:

• In the tag <MobiusNetworkServiceDescriptor ...> change the "hostname" attribute value to the fully qualified domain name of the remote machine.
• In the <serviceIdentifier ...> change the "serviceId" to a host-resolvable name, preceded by GME://. The service id must be unique within the set of GMEs that you instantiate, that is, it must be unique within your "Grid". In the examples in this QuickStart, our ids match the names of the machines on which we run the GMEs.

Note: The two requirements for service ids are that they be unique within your Grid and that they be resolvable by the other Grid services that will connect to them.

For this example, we're using a minimal set up and default parameters for everything else. The configuration files are discussed in more detail on the gme configuration page of this online documentation.

Starting the GME

Change to the mobius_gme.../scripts directory on each remote machine.

Type:
$ ./startGME.bat ../conf/localhost-gme-config.xml &
You should see output like the following:

INFO - Dec 14, 2004 5:09:26 PM  -- Creating Database: Kensdc02MobiusGME_GME_REGISTRY
INFO - Dec 14, 2004 5:09:26 PM  -- Creating database: Kensdc02MobiusGME_GME_SCHEMA_STORE
INFO - Dec 14, 2004 5:09:27 PM  -- Server started on GME://kensdc02gme at Tue Dec 14 17:09:27 EST 2004
INFO - Dec 14, 2004 5:09:27 PM  -- Setting Service Identifier to GME://kensdc02gme
INFO - Dec 14, 2004 5:09:27 PM  -- Listening using the protocol TCP on the host 0.0.0.0, port 1111

You will see that MySQL now has (at least) two new databases:
mobiusgme_gme_registry contains the descriptors, namespaces, and other information relevant to GMEs registered in Mobius.
mobiusgme_gme_schema_store contains all of the schema registered with the various GME instances.

GME has a large complement of command line tools to, among other things, add authorities, add namespaces, resolve namespaces, list and publish schemas, destroy GMEs, and check the services' status. These tools are discussed in the GME command line utilities page of this online documentation. We will be using the Java GUI GME View to perform many of these functions.

Starting GME View

On the local machine, in the /scripts directory, type:
$ ./GMEView.bat

Note: Under the "File" menu, you will see "Save Current Configuration". Selecting that option at any time during your GME View session will open a dialog window allowing you to save your session information--the list of GMEs you have added, any other special settings you have established. In a subsequent session, you can pass GME View your previously saved session file, like so:
./GMEView.bat ../config/your_session_parameters
and GME View will load all of the GMEs from your previous session.

Right-click on the "Mobius Grid Services" icon and select "Add Grid Service". In the "Grid Service Id" field in the dialog window, type in GME:// followed by the host-resolvable name of the GME to which you want to connect, for example, GME://dc02.bmi.ohio-state.edu, and click "Okay." For this QuickStart, we've added three remote hosts. Each was added in a similar manner--by specifying a resolvable hostname upon which a GME is running. (See Fig 1.)

You can add subordinate GMEs to any running GME by right-clicking on its icon and choosing "Add XML Data Model Service." Adding a GME to an already running GME instance adds the new GME as a subordinate, making the already running GME its parent.

Removing a GME is a simple operation. Right-click on its icon and select "Remove XML Data Model Service." Select "OK" in the confirmation dialog that appears. Removing a GME does not stop it but does do a number of tear down operations behind the scenes to correctly set authorities and subordinates on the involved nodes. When you remove a node, its subordinates are removed, as well.

Let's go through a number of typical operations. We'll add and remove a namespace, attempt to resolve a namespace, try to lookup authoritative namespaces, and publish and request a schema. Configure your Grid of GMEs as depicted above, with a single parent node and two subordinate nodes.

Add a Namespace

Right-click on the parent GME icon and select "Add Namespace." Put in a namespace that you wish to establish as authoritative. Let's put in projectmobius.org. The GME will now become the authority for that namespace. Whenever you add a namespace, the authority for your GME will be notified of the new namespace ownership. For proper resolution, namespaces must be unique in the tree of GMEs. Adding a namespace that is already taken will produce an error. Also, any namespaces you add to child nodes must be subnamespaces of a parent. For example, if the parent is projectmobius.org, a child node's namespace must be a subnamespace, e.g., childof.projectmobius.org. For this QuickStart, go ahead and add the projectmobius.org namespace to the parent node and the childof.projectmobius.org namespace to a subordinate node.

Remove a Namespace

Right-click the GME icon for which you want to remove the namespace. Select "Remove Namespace" and okay the dialog. Closing the dialog without clicking "Okay" will not commit any changes. You are prevented from removing namespaces on any node for which there are subordinate nodes that contain subordinate/related namespaces. For example, if the parent node had a namespace of projectmobius.org and one of its children had childof.projectmobius.org for a namespace, you would be prevented from removing the parent's projectmobius.org namespace.

Resolve a Namespace

To discover which GME is the authority for any known namespace, right-click any GME icon and select "Resolve Namespace". A dialog window asks for the namespace to resolve and lists the GME that will be queried. Type in the namespace and click "Ok". Namespace resolution requests first move up the tree from the requesting node to its authorities. If no node is found with that namespace, the search procedes down the tree. Either a dialog indicating the node that is the authority of the queried namespace will appear or you will get an error message telling you the namespace cannot be located. Namespaces can only be resolved within the branches of the tree on which the search was initiated. Searches are not global for all GMEs, only those within the connected tree of GMEs. For this QuickStart, you should be able to lookup projectmobius.org and childof.projectmobius.org from any GME node.

Lookup Autoritative Namespaces

To see which namespaces a GME has authority for, right-click on the GME icon and select "Lookup Authoritative Namespaces." This will produce a dialog containing a list of all the namespaces the GME has authority for. For this QuickStart test each of the nodes in your tree to verify the namespaces each has authority for.

Publish a Schema

Data in Mobius are described by XML schemas. GME is a service for storing schemas so that they can be discovered and used by Mobius services. To publish a schema, right-click a GME node icon and select "Publish Schema". Note that schema cannot be removed from the GME, though they can be re-added. Attempting to add a schema that has already been published will produce an error. The inability to remove schema prevents the accidental obsoleting of XML data that might be dependant on the schema. Let's add the schema describing a bookstore. You'll find this schema in the /xml directory. Use the "Browse" button to locate the directory and select and "Open" bookstore.xsd. The path will appear in the "Publish To Service" field. Select "OK". Note that we would not be able to add this schema unless the projectmobius.org namespace had already been registered and the bookstore.xsd schema was part of that namespace.

Request a Schema

To retrieve a schema published on a GME, right-click a GME and select "Request Schema". In the "Namespace" dropdown, choose a namespace from the list. The list is populated only by namespaces for which your node has authority. The "Schema" dropdown will also only list schemas that are available for the chosen namespace. To retrieve the a selected schema, click "Ok". This ability to retrieve schemas can be very useful. For example, you might copy the text out of this window and use it to create a new schema that builds on or modifies the retrieved one.

Request References to All Schema Containing an Element

There will be cases in which you will want to see which schemas contain elements with the same names. For example, you might want a quick way to determine if any of the schemas stored by a GME contain "Book" elements so that you can examine those schemas and see which is the appropriate one for describing the sort of book you want to store or search for. To retrieve references to all schemas within a GME that contain a particular named element, right-click a GME and select "Get Schema Element References" from the dropdown. In the dialog, fill in the the name of the element you want to search for. You can narrow your search by specifying the type of element ("Simple" or "Complex") in the "Element Type" option field. Click "Get References". The "Referencing Schemas" text area will be populated with XML indicating the name of the schema in which your searched for element occurs. See Fig 2., below, which shows that the "Title" is an element within the "BookStore" schema.

Fig 2. Result of a query for a particular schema element