- 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.
In this step you will download and install MMS, and a grid service container, using the caGrid Installer. If you already have caGrid 1.3 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:
- Download the caGrid 1.3 Installer. The downloaded installer is contained in caGrid-installer-1.3.zip.
- Unzip the file caGrid-installer-1.3.zip. This creates the directory caGrid-installer-1.3. This guide refers to that directory as CAGRID_INSTALLER_LOCATION.
- From a command prompt, launch the installer by entering the following command:
- 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 whether or not you have already installed Ant. It installs or reinstalls it, depending on your installation status. In either case, you must specify the location where you want to install Ant.
- The installer detects whether or not you have already installed Globus. It installs or reinstalls it, depending on your installation status. 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 we recommend selecting 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 you 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.
|To simply deploy the MMS with the default configuration, all you need to edit is the service's standard ServiceMetadata, by following these instructions.|
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.
MMS is an Introduce-created service and supports all the standard Introduce configuration points, which are described in the Introduce Administrator's Guide.
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
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.
|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.
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.
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.
This section describes the beans in the default MMS configuration file.
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.
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 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.
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.|
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:Start up Tomcat so your service is available. Run this command: or in Windows
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.
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:
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:
When you connect to this URL, you should see the following text on the screen:
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.
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:
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:
|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.|
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: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.
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.