----
h1. MMS 1.4 Administrators Guide
----
{include:Administrators Guide Navigation}
{cagridroundpanel}
{pre:class=cagridheaderfont}Contents{pre}
{toc:outline=true|exclude=MMS 1.4 Administrators Guide|style=none}
{cagridroundpanel}
h2. Prerequisites
----
* [Standard caGrid Prerequisites|caGrid14:Software Dependencies]
* *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|http://ncicb.nci.nih.gov/NCICB/infrastructure/cacore_overview/cadsr] via the version 4.0 ApplicationService API. See the [MMS Design Document|Design Guide] for details on how to integrate other external metadata repositories.

h2. 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|#Configuration].

{tip}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{_}*
.
{tip}To install caGrid/MMS and set up a container, complete the following steps:
{include:caGrid14:Install caGrid and Configure a Non-Secure Container Using the caGrid 1.4 Installer}
h2. Configuration
----
{tip}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].{tip}
h3. 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|#Deployment] 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.

{tip}If you aren't comfortable editing in XML, you can use [Introduce's graphical editor|metadata14:Developers Guide#caGrid Service Metadata Editor] instead when you deploy the service.{tip}Below is the relevant section of the file that you should edit.
{code:xml} <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>
{code}
h3. 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|introduce14:Administrators Guide#AdministratorsGuide-ConfigurationFiles].

h3. Service Properties (service.properties)

MMS provides a single Introduce Service Property _(mmsConfigurationFile)_, which specifies the location of the [MMS Configuration File|#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 |

h3. 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|caGrid14:How to Change Target Grid] 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|introduce14:Administrators Guide#AdministratorsGuide-deploy.properties].


h3. MMS Configuration File
{warning}You should not edit the MMS configuration file unless you are familiar with the MMS design, as described in the [MMS Design Guide|Design Guide], and don't want to use the production caDSR as your metadata source.{warning}The MMS configuration file is located by the value of the _mmsConfigurationFile_ Introduce Service Property, and used to configure the service via [Spring|http://www.springsource.org/]. 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.

{code:xml|title=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>
{code}
h3. 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.

{code:xml|title=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>
{code}The default file, shown above is setup to configure the MMS with a single Metadata Model Source (see the [MMS Design Guide|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.

h4. MMS Default Implementation Beans

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

h5. Main MMS Bean

As stated above, the [MMS Configuration File|#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|#metadata Bean] and a map of Metadata Source Model identifier to caCORE ApplicationService remote URL.&nbsp; Multiple entries may be added to the map, but you shouldn't need to modify the reference to the _metadata_ bean.

{info}Each _entry_ _key_ must match the _identifier_ used in the SourceDescriptor.{info}In this file, the \*caDSR Production\* key is the identifier assigned to SourceDescriptor in the [caDSRProductionSource bean|#caDSRProductionSource Bean].

{code:xml}<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>
{code}
h5. 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|#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.
{info}The _defaultSourceIdentifier_ must match the _identifier_ used in the SourceDescriptor.{info}
{code:xml} <!-- 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>
{code}
h5. supportedModelSources Bean

The _supportedModelSources_ bean is used by the [metadata bean|#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|#caDSRProductionSource Bean] is listed, but others can be similarly added to add additional sources.

{code:xml} <bean id="supportedModelSources" class="org.cagrid.mms.domain.ModelSourceMetadataSupportedModelSources">
<property name="source">
<list>
<ref bean="caDSRProductionSource" />
</list>
</property>
</bean>
{code}
h5. caDSRProductionSource Bean

The _caDSRProductionSource_ bean is referenced by the list of supported sources in the [supportedModelSources Bean|#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.

{info}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.{info}
{code:xml} <!--
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>
{code}
h2. Deployment
----
MMS is an Introduce-created service and supports all standard Introduce deployment processes, which are described in the [Introduce Administrator's Guide|introduce14:Administrators Guide##AdministratorsGuide-Deployment Undeployment].

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

{terminal}> ant deployTomcat{terminal}Start up Tomcat so your service is available. Run this command:

{terminal}> $CATALINA_HOME/bin/startup.sh{terminal}or in Windows
{terminal}> %CATALINA_HOME%\bin\startup.bat{terminal}
h2. 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.

h2. 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|#Deployment] 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:

{noformat}cagrid/MetadataModelService

Hi there, this is an AXIS service!
Perhaps there will be a form for invoking the service here...
{noformat}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.

h2. Validate the MMS (Command Line Client)

Once you have [verified the service is running,|#Validate 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:
{terminal}> ant \-Dservice.url=*YOUR_SERVICE_URL\\\\\\\\\* runClient{terminal}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:
{terminal}> ant runClient{terminal}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:

{noformat}[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
{noformat}
{info}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.{info}
h2. Validate the MMS (Introduce)

The MMS is used internally by the [caDSR data type browsing extension|metadata14:Developers Guide#DevelopersGuide-caDSRTypeDiscovery] 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:

{terminal}> ant introduce{terminal}Once Introduce starts, select the _Window->Preferences_ menu and set the *MMS Service URL* as your service's URL. Click *Save*.

!IntroducePreferences_URLs.png!

{info}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).{info}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.

!caDSR_Browser.png!

h2. 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|#Configuration]. Make any such changes to the configuration in the files in *{_}MMS_HOME{_}*, then redeploy the service and restart the container.