MMS 1.4 Administrators Guide

[ Documentation | Administrators Guide | caGrid Documentation Guides ]


	Contents 1.1 Prerequisites 1.2 Installing the Software 2 Install caGrid and Configure a Non-Secure Container Using the caGrid 1.4 Installer 2.1 Configuration 2.1.1 Service Metadata 2.1.2 Introduce Properties 2.1.3 Service Properties (service.properties) 2.1.4 Deployment Properties (deploy.properties) 2.1.5 MMS Configuration File 2.1.6 MMS Default Implementation 2.1.6.1 MMS Default Implementation Beans 2.1.6.1.1 Main MMS Bean 2.1.6.1.2 metadata Bean 2.1.6.1.3 supportedModelSources Bean 2.1.6.1.4 caDSRProductionSource Bean 2.2 Deployment 2.3 Validation 2.4 Validate the Service is Running 2.5 Validate the MMS (Command Line Client) 2.6 Validate the MMS (Introduce) 2.7 Management

Prerequisites

Standard caGrid Prerequisites
External Metadata Repository (default provided)
The MMS is an extensible framework for generating and annotating caGrid metadata models using information contained in one or more external metadata repositories. The default implementation is configured to communicate with instances of the NCI caDSR via the version 4.0 ApplicationService API. See the MMS Design Document for details on how to integrate other external metadata repositories.

Installing the Software

In this step you will download and install MMS, and a grid service container, using the caGrid Installer. If you already have caGrid 1.4 installed on your machine, as well as a suitable container, you may proceed to the next step.

Once you have installed caGrid, you can find the MMS software in the directory location where you installed caGrid, in the caGrid/projects/mms directory. This guide refers to that location as MMS_HOME
.

To install caGrid/MMS and set up a container, complete the following steps:

Install caGrid and Configure a Non-Secure Container Using the caGrid 1.4 Installer

Download the caGrid 1.4 Installer. The downloaded installer is contained in caGrid-installer-1.4.zip.
Unzip the file caGrid-installer-1.4.zip. This creates the directory caGrid-installer-1.4. This guide refers to that directory as CAGRID_INSTALLER_LOCATION.

From a command prompt, launch the installer by entering the following command:

 > cd *CAGRID_INSTALLER_LOCATION\\\\\\\\\* 
 > java -jar caGrid-installer-1.4.jar

Select the I agree to this license checkbox and click Next.

Select the Install/Configure caGrid Software and the Install/Configure Grid Service Container checkboxes and click Next.

The installer detects if Ant is already installed. It installs or reinstalls it accordingly. In either case, you must specify the location where you want to install Ant.
The installer detects if Globus is already installed. It installs or reinstalls it accordingly. In either case, you must specify where you want to install Globus.

The installer asks for a location on your local file system to install caGrid. Specify a location to install caGrid and click Next.

The installer displays a list of tasks that the installer will perform. Click Next to start the installation process. The installer downloads, builds, and installs several components. Note: This process takes several minutes.
Once the installer has completed installing all the components, click Next.

The installer asks which Grid you would like to configure your installation to use. The installer supports configuring caGrid to work out of the box with many community Grid environments. For testing and development purposes, it is recommended you select the Training Grid. If you do not want to configure caGrid to work with an existing Grid, you may specify that as well. You can modify the installer to support additional Grids.

The installer shows a summary of the tasks to be completed. Click Next to configure caGrid to use the selected target Grids. Note: This process takes several minutes.
Once the installer has finished configuring the target Grid, click Next.

Select the Container where you want to deploy your service. This guide provides instructions for Tomcat. As this container does not ensure security, leave the Should this container be secure? checkbox unchecked and click Next.

In the hostname box, enter the hostname of your server. This should match the hostname used in creating your host credentials. Click Next.

If you plan on using this container to deploy the service registered to an existing grid, it is important to use a publicly resolvable DNS name (or static IP); otherwise, you will need to manually edit configuration files later to correct this.

The next screen asks where you want to install Tomcat. In the Directory box, enter a location and then click Next.

The next screen displays a list of tasks that the installer will perform to install and configure Tomcat. Click Next.

Once the installer has completed installing all the components, click Next.
Click Next. The final screen reminds you to set your ANT_HOME, GLOBUS_LOCATION, and CATALINA_HOME environment variables. Set these variables immediately and then click Finish.
You can find these instructions in CAGRID_POST_INSTALLATION.txt, which is in the directory from which you ran the installer.

Congratulations! You have successfully installed and configured your Tomcat container. You may now close the installer by clicking Close.

Configuration

To simply deploy the MMS with the default configuration, all you need to edit is the service's standard ServiceMetadata, by following these instructions.

Service Metadata

The MMS service provides two resource properties, which act as metadata for its clients, which describe the service's capabilities and information on where it is being hosted. The first Resource Property, the ModelSourceMetadata is MMS-specific and the service automatically generates it. The second resource property is the caGrid standard ServiceMetadata. A file on the file system (serviceMetadata.xml), located in the MMS_HOME/etc directory, loads this instance and the service deploys it. This file is fully populated except for the information about where the service is being hosted; that is completed as if the service were being deployed at Ohio State University. Before deploying the service, you must edit this file and provide the information that describes your organization.

If you aren't comfortable editing in XML, you can use Introduce's graphical editor instead when you deploy the service.

Below is the relevant section of the file that you should edit.

 <ns1:hostingResearchCenter>
  <ns18:ResearchCenter displayName="OSU" shortName="OSU" xmlns:ns18="gme://caGrid.caBIG/1.0/gov.nih.nci.cagrid.metadata.common">
   <ns18:Address country="US" locality="Columbus" postalCode="43210" stateProvince="OH" street1="333 W 10th Ave" street2=""/>
   <ns18:ResearchCenterDescription description="" homepageURL="" imageURL="" rssNewsURL=""/>
   <ns18:pointOfContactCollection>
    <ns18:PointOfContact affiliation="OSU" email="scott.oster@osumc.edu" firstName="Scott" lastName="Oster" phoneNumber="" role="Maintainer"/>
   </ns18:pointOfContactCollection>
  </ns18:ResearchCenter>
 </ns1:hostingResearchCenter>

Introduce Properties

MMS is an Introduce-created service and supports all the standard Introduce configuration points, which are described in the Introduce Administrator's Guide.

Service Properties (service.properties)

MMS provides a single Introduce Service Property (mmsConfigurationFile), which specifies the location of the MMS Configuration File to be used. The default value can be used in most cases, but this allows the service deployer the ability to point to an alternative configuration file at deployment time. This can be useful, for example, if multiple different configurations are commonly used such that the default configuration doesn't need to be edited to switch configurations.

Property Name	Value(s)
mmsConfigurationFile	applicationContext-mms.xml

Deployment Properties (deploy.properties)

The caGrid build process (or the caGrid installer) configures MMS to register to the appropriate Index Service for the target grid you are using. You can follow these instructions to change your target grid, before you deploy the MMS. Alternatively, you can use a custom Index Service by following the documentation in the Introduce Administrator's Guide.

MMS Configuration File

You should not edit the MMS configuration file unless you are familiar with the MMS design, as described in the MMS Design Guide, and don't want to use the production caDSR as your metadata source.

The MMS configuration file is located by the value of the mmsConfigurationFile Introduce Service Property, and used to configure the service via Spring. The file is expected to minimally contain a bean with the id mms which identifies a class that implements the org.cagrid.mms.service.impl.MMS interface.

Minimal MMS Configuration File

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans xmlns:p="http://www.springframework.org/schema/p">
  <!--
    Configure your MMS-implementation here; the only bean
    that will be looked up will be the one named "mms"
  -->
  <bean id="mms" class="YOUR_CLASS_HERE"/>
</beans>

MMS Default Implementation

The default implementation configures the service to use an implementation which communicates with any number of external caDSR instances, via their remote ApplicationService API. Any number of URLs can be configured as sources of metadata.

Default MMS Configuration File

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:p="http://www.springframework.org/schema/p"
  xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd">

  <!--
    Configure your MMS-implementation here; the only bean that will be looked up will be the one
    named "mms"
  -->

  <!--  This specifies the caDSR-based implementation -->
  <bean id="mms" class="org.cagrid.mms.service.impl.cadsr.CaDSRMMSImpl">

    <!--  Used to specify the MMS metadata constructed below -->
    <constructor-arg>
      <ref bean="metadata" />
    </constructor-arg>
    <!--
      These keys represent the sourceIDs that are supported, and the caDSR ApplicationService remote
      URL that will be used for the corresponding sourceID.
    -->
    <constructor-arg>
      <map>
        <entry key="caDSR Production" value="http://cadsrapi.nci.nih.gov/cadsrapi40/" />
      </map>
    </constructor-arg>
  </bean>

  <!--  The metadata defines the default source, and the list of supported sources -->
  <bean id="metadata" class="org.cagrid.mms.domain.ModelSourceMetadata">
    <property name="defaultSourceIdentifier" value="caDSR Production" />
    <property name="supportedModelSources" ref="supportedModelSources" />
  </bean>

  <bean id="supportedModelSources" class="org.cagrid.mms.domain.ModelSourceMetadataSupportedModelSources">
    <property name="source">
      <list>
        <ref bean="caDSRProductionSource" />
      </list>
    </property>
  </bean>

  <!--
    The caDSR-based implementation assumes the supported source properties (and that they are the same
    for all sources), and populates them automatically; they don't need to be specified for the
    listed sources.
  -->
  <bean id="caDSRProductionSource" class="org.cagrid.mms.domain.SourceDescriptor">
    <property name="identifier" value="caDSR Production" />
    <property name="description"
      value="The production instance of the National Cancer Institute's Cancer Data Standards Repository (caDSR)." />
  </bean>
</beans>

The default file, shown above is setup to configure the MMS with a single Metadata Model Source (see the MMS Design Guide for more information). This source is identified as "caDSR Production" and is configured to point to the remote ApplicationService URL (http://cadsrapi.nci.nih.gov/cadsrapi40/) of the Production caDSR instance run by the NCI.

This default configuration can easily be extended to point to a different remote caDSR just by changing the URL of the application service, and optionally the key and description used to identify it. Furthermore, additional, non-default Metadata Model Sources can be added to the service. However, the default MMS implementation does assume that all sources are caDSR-based; to support a different source type, a custom MMS implementation must be created and specified for the mms bean.

MMS Default Implementation Beans

This section describes the beans in the default MMS configuration file.

Main MMS Bean

As stated above, the MMS Configuration File must contain a bean with ID mms, and specify its implementation of the MMS Interface. In the default file, this is set as the org.cagrid.mms.service.impl.cadsr.CaDSRMMSImpl class. This class takes, in its constructor, a reference to the metadata bean and a map of Metadata Source Model identifier to caCORE ApplicationService remote URL. Multiple entries may be added to the map, but you shouldn't need to modify the reference to the metadata bean.

Each entry key must match the identifier used in the SourceDescriptor.

In this file, the *caDSR Production* key is the identifier assigned to SourceDescriptor in the caDSRProductionSource bean.

<bean id="mms" class="org.cagrid.mms.service.impl.cadsr.CaDSRMMSImpl">
    <!--  Used to specify the MMS metadata constructed below -->
    <constructor-arg>
      <ref bean="metadata" />
    </constructor-arg>
    <!--
      These keys represent the sourceIDs that are supported, as well as the caDSR ApplicationService remote
      URL that will be used for the corresponding sourceID.
    -->
    <constructor-arg>
      <map>
        <entry key="caDSR Production" value="http://cadsrapi.nci.nih.gov/cadsrapi40/" />
      </map>
    </constructor-arg>
  </bean>

metadata Bean

The metadata bean is used to construct the ModelSourceMetata instance of the service, which is exposed as a resource property of the service, and specifies the information about what external metadata sources are available, as well as their properties.

The bean has two properties, the defaultSourceIdentifier and the supportedModelSources. It uses these to automatically create the necessary ModelSourceMetata. You shouldn't need to edit the supportedModelSources, as it is only a reference to the supportedModelSources Bean, but you may edit the defaultSourceIdentifier to change the metadata source that the service should use when the client doesn't explicitly specify one.

The defaultSourceIdentifier must match the identifier used in the SourceDescriptor.

 <!--  The metadata defines the default source, and the list of supported sources -->
  <bean id="metadata" class="org.cagrid.mms.domain.ModelSourceMetadata">
    <property name="defaultSourceIdentifier" value="caDSR Production" />
    <property name="supportedModelSources" ref="supportedModelSources" />
  </bean>

supportedModelSources Bean

The supportedModelSources bean is used by the metadata bean to create a list of supported metadata sources. This is just a list of bean references to instances of SourceDescriptor. In the default file, only the caDSRProductionSource Bean is listed, but others can be similarly added to add additional sources.

  <bean id="supportedModelSources" class="org.cagrid.mms.domain.ModelSourceMetadataSupportedModelSources">
    <property name="source">
      <list>
        <ref bean="caDSRProductionSource" />
      </list>
    </property>
  </bean>

caDSRProductionSource Bean

The caDSRProductionSource bean is referenced by the list of supported sources in the supportedModelSources Bean, and is used to construct a org.cagrid.mms.domain.SourceDescriptor instance. The bean only specifies the identifier and description of the source, as the remaining properties of the SourceDescriptor are common for all caDSR sources, and set automatically by the default MMS implementation.

Other sections of the file use the identifier specified here as a key. The client also uses the identifier when wishing to leverage non-default sources. It is important to keep it consistent, though the description is only informational.

  <!--
    The caDSR based-implementation assumes the supported source properties (and that they are the same
    for all sources), and populates them automatically; you don't have to specify them for the
    listed sources.
  -->
  <bean id="caDSRProductionSource" class="org.cagrid.mms.domain.SourceDescriptor">
    <property name="identifier" value="caDSR Production" />
    <property name="description"
      value="The production instance of the National Cancer Institute's Cancer Data Standards Repository (caDSR)." />
  </bean>

Deployment

MMS is an Introduce-created service and supports all standard Introduce deployment processes, which are described in the Introduce Administrator's Guide.

For example, to deploy the service to Tomcat from the command line, you can type the following command from the MMS_HOME directory:

 > ant deployTomcat

Start up Tomcat so your service is available. Run this command:

 > $CATALINA_HOME/bin/startup.sh

or in Windows

 > %CATALINA_HOME%\bin\startup.bat

Validation

The MMS can be validated for proper function by interacting with the service directly through its API, as well as indirectly by using the Introduce features that rely on it. This section details the steps you can take to validate the MMS.

Validate the Service is Running

To ensure the MMS is working properly, we must first validate that the service is actually running and that its log contains no errors. For example, if you deployed to Tomcat, you should look at the log file in $CATALINA_HOME/logs/catalina.out and make sure there are no exceptions present. Finally, open your web browser, and point it to the URL of your service. This should be of the form:

http:/YOUR_HOST:YOUR_PORT/wsrf/services/cagrid/MetadataModelService

For example, if you used the default ports, you should be able to use the following URL on the machine on which you deployed the MMS: "http://localhost:8080/wsrf/services/cagrid/MetadataModelService".

When you connect to this URL, you should see the following text on the screen:

cagrid/MetadataModelService

Hi there, this is an AXIS service!
Perhaps there will be a form for invoking the service here...

If you see an error, the service is not deployed correctly. If you get a connection refused, check that your container is actually running, and that the URL you are using is correct.

Validate the MMS (Command Line Client)

Once you have verified the service is running, you can check some of its functionality from the command line by running the following command from the MMS_HOME directory:

 > ant -Dservice.url=*YOUR_SERVICE_URL\\\\\\\\\* runClient

If you used the defaults, and are running the command from the machine on which you installed the MMS, you can simply type this command, and the default URL will be used:

 > ant runClient

This command requests the MMS to generate a DomainModel for a well-known model, and should print out the model's description. Below is a sample of what you should see:

[meadowgrain:caGrid/projects/mms] oster% ant runClient
Buildfile: build.xml

setGlobus:

checkGlobus:
     [echo] Globus: /Users/oster/grid/ws-core-4.0.3

defineClasspaths:

defineExtendedClasspaths:

runClient:
     [echo] Connecting to service: http://localhost:8080/wsrf/services/cagrid/MetadataModelService
     [java] Running the Grid Service Client
     [java] caTIES application version for Grid Reference Implementation is based on this model.

BUILD SUCCESSFUL
Total time: 14 seconds

Note: this approach assumes you haven't edited the default MMS Configuration File. If you have, you must edit the main method of the org.cagrid.mms.client.MetadataModelServiceClient class, to make it relevant to your environment.

Validate the MMS (Introduce)

The MMS is used internally by the caDSR data type browsing extension of Introduce. You can use this feature to ensure that the MMS is properly generating DomainModels.

You can launch Introduce from the directory in which you installed caGrid (there should be a caGrid folder), by typing the following command:

 > ant introduce

Once Introduce starts, select the Window->Preferences menu and set the MMS Service URL as your service's URL. Click Save.

Note: this approach also requires the caDSR Data Service to correctly function and assumes the caDSR extension is installed in Introduce (which it is for a full caGrid install).

With Introduce now configured to communicate with your MMS service, you can use the data type browser to browse Projects and Packages in the caDSR, and have Introduce use the MMS to render a UML View of the selected Package. To do this, follow these steps:

In Introduce's top toolbar, click the Browse Data Types button. The Browse Data Types window appears.
Click the caDSR tab. A progress bar appears.
Once the progress bar completes, select a Project from the Project list (for example, caArray (version 2.1)).
Once the progress bar completes, select a Package from the Package list (for example, gov.nih.nci.carray.domain.sample).
Once the progress bar completes, you should see a UML model in the panel below, similar to what is shown below. If you get an error, try selecting a different Project/Package. If the error persists, the MMS may not be functioning properly.

Management

The MMS has no management operations that you must perform on the running service. The only changes that can be made to the service are described in the Configuration section. Make any such changes to the configuration in the files in MMS_HOME, then redeploy the service and restart the container.