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

Global Model Exchange (GME) QuickStart

• starting the GME
• connecting GMEs to other services

Minimal Configuration

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 required by the <database> section within 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, handlers for events, 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 any string. The identifier 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.

For this example, we're using a minimal set up and default parameters for everything else. The configuration files are discussed in more detail in the configuration and API section 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 - Oct 15, 2004 3:52:10 PM  -- Creating Database: MobiusGME_GME_REGISTRY
INFO - Oct 15, 2004 3:52:10 PM  -- Creating database: MobiusGME_GME_SCHEMA_STORE
INFO - Oct 15, 2004 3:52:14 PM  -- Server started on dc02.bmi.ohio-state.edu at Fri Oct 15 15:52:14 EDT 2004
INFO - Oct 15, 2004 3:52:14 PM  -- Setting Service Identifier to dc02
INFO - Oct 15, 2004 3:52:14 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 command line utilities section of this online documenation. 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 "XML Data Model Services" icon and select "Add XML Data Model Service." In the dialog window, type the fully qualified domain name of the GME service to which you want to connect 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.

Fig 1. GME View with three remote GMEs running, menu expanded

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.

Add a Namespace

Right-click a 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. 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.

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 see verify the namespaces each has authority for.

Publish a Schema

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 readded. 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 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 be 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.

Adding a Handle Factory to Connect to other Mobius Services

There will probably be occassions in which you will want to connect to a GME or group of running GMEs through some means other than the default handle. You might want to locate running GMEs 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.