----
h1. MMS 1.4 Design Guide
----
{cagridtoc:exclude=MMS 1.4 Design Guide}\\
{include:mms14:Overview}
h2. Purpose
The purpose of this document is to describe the architecture of the Metadata Model Service (MMS) grid service. The information in this document is to help developers interested in extending or modifying the MMS.
h1. Implementation
----
h2. Architecture
The MMS is a stateless, single-resource grid service created with [Introduce|introduce14:Home]. As such, it follows the standard package implementation breakdown between, _client_, _common_, _service_, and _resource_. The MMS also contains some additional packages which are specific to its implementation. The organization and purpose of the packages of MMS are described in the table below.
|| Package in org.cagrid.mms || Description ||
| [client|#Client API] | The Introduce generated client package |
| common | The Introduce generated common package |
| [domain|#Domain Model] | The MMS domain model |
| [service|#Service Components] | The Introduce generated service package, with additional classes for the spring-loaded implementation |
| [service.impl|#MMS Interface] | The MMS interface definitions |
| [service.impl.cadsr|#caDSR MMS Implementation] | The caDSR-based implementation of the MMS interface |
| stubs | The Introduce/Axis generated protocol |
The service-side implementation of the MMS is a standard Introduce-generated service infrastructure. However, rather than the standard service _"*Impl"_ class being used to implement the business logic, the MMS leverages [Spring's|#Spring] dependency injection capabilities to load and configure the business logic from a deploy-time specified configuration file. The default implementation makes use of the caDSR as its sole external metadata registry.
h3. External Metadata Registries
As the MMS provides no "management" operations for the metadata models it expects its clients to reference, it is generally expected to be deployed referencing an external metadata registry. For example, the default implementation is configured to make use of caBIG's Cancer Data Standards Repository (caDSR). This external registry provides the means to add, modify, delete, or otherwise manage the UML models and their correspondence to XML Schemas which the MMS leverages. The details of that registry are of no concern to MMS clients; they only need to know that a particular MMS deployment is able to leverage it as a metadata registry (which is described in the [Model Source Metadata|#Model Source Metadata]). The MMS can similarly be configured for any other metadata registry which meets the requirements below.
h4. Registry Requirements
In order to integrate an external metadata registry with the MMS, there are some basic requirements the registry must be able to satisfy. Firstly, the MMS's main purpose is annotating existing Service Metadata, using a registry-specific means of looking UML models for XML Schemas, and generating full UML model representations for an identified subset of a particular project in the registry. As such, it is required the registry provides an identifiable collection of UML Models in sufficient detail to reproduce a UML diagram (e.g. DomainModel). It is strongly suggested the registry also provide a mapping of those models to their representative XML Schema manifestations (in support of the annotateServiceMetadata operation). This is not strictly required (if not possible), as the annotateServiceMetadata can simply return the provided ServiceMetadata instance if no mapping is possible. The second main requirement is that the registry be able to identify its managed UML Projects through consistent means. That is, the MMS client API uses _UMLProjectIdentifier_ (see [the MMS Domain Model below|#Domain Model]) to identify projects of interest. As such, it must assign an identifer and optional version to each project, and where this identifier is not sufficient to uniquely identify a project, it may make use of optional or required additional registry-specific properties. For example, the table below shows the mapping of the caDSR MMS implementation's _UMLProjectIdentifier_.
{include:mms14:caDSR MMS Mapping Table}
h3. Domain Model
{include:mms14:Model Overview}
{include:mms14:Model Source Metadata}
h3. Service Components
The main service-side implementation classes of the MMS are shown below. The service implementation class, _MetadataModelServiceImpl_, reads the settings in the _MetadataModelServiceConfiguration_ class, and uses them to instantiate an implementation of the _MMS_ interface via Spring. The _MMS_ implementation class implements the core business logic of the MMS, and defines the standard operations and their use of the _MMSGeneralException_. These components are described in more detail in the following sections.
!mms_service.png!
h4. MMS Interface
The MMS interface mirrors the service operations of the MMS fairly directly, and allows the general service to be easily used for any external metadata registry which can map between XML Schema and UML Models. These operations are described in detail in the [service operation section of the MMS Developers Guide|Developers Guide#Service Operations Overview].
h4. Spring
The MMS service implementation (_MetadataModelServiceImpl_), uses Spring's _XMLBeanFactory_ to load and configure the MMS interface implementation, using a configuration and property file which are specified via Introduce service properties. The [MMS Administrators Guide configuration section|Administrators Guide#Configuration] provides extensive documentation of this process. As such, the MMS business logic can easily be modified by plugging into custom code or configuration settings without needing to modify any of the MMS service's code or build/deploy process.
h4. caDSR MMS Implementation
The classes involved in the default implementation of the MMS interface, which leverages the caDSR as its external metadata registry, are shown below.
!mms_cadsr.png!
The _CaDSRMMImpl_ is the implementation of the MMS interface, which acts as the entry point to the caDSR-based implementation. It is responsible for constructing the appropriate _MetadataModelSource_ instance, which indicates the allowable caDSR-specific properties the service will support. For generating domain models and annotating service metadata, it delegates to the [_DomainModelBuilder_|#DomainModelBuilder] and [ServiceMetadataAnnotator|#ServiceMetadataAnnotator] respectively. Both these components leverage the caCORE ApplicationService for communicating with the caDSR.
h5. caCORE ApplicationService
The caCORE 4.0 ApplicationService is used by various other components to access information in the caDSR. It provides a simple query API which is available for remote access. The component APIs that make use of the ApplicationService, generally take in instance of it in their constructor. The _CaDSRMMImpl_ creates an instance by using the _ApplicationServiceProvider.getApplicationServiceFromUrl(url)_ call, where the URL used is populated via a mapping of MMS Source Identifier to URL, provided via the Spring configuration.
The ApplicationService is used to issue both HQL (Hibernate Query Language), and simple "query by example" queries. The two caCORE models which are consulted are the gov.nih.nci.cadsr.domain model, which represents the caDSR information and the gov.nih.nci.cadsr.umlproject.domain, which represents a UML-like view of information in the caDSR.
h5. DomainModelBuilder
The DomainModelBuilder provides the ability to generate caGrid standard Data Service metadata instances for project's registered in the caDSR. The Data Service metadata describes the information model being exposed by a Data Service. For more information on the model, consult the [caGrid metadata overview|metadata14:Metadata Models]. The DomainModelBuilder uses the ApplicationService to access the necessary information from the caDSR. It mostly uses optimized HQL queries to efficiently access the necessary information, utilizing eager association fetching where appropriate. The majority of work performed by the DomainModelBuilder is simply aggregating and transforming information in the caDSR into the format necessary to describe the DomainModel metadata of Data Services. As much of the necessary extraction and transformation is independent, and the information is located in a remote system where network delays slow down computation, the DomainModelBuilder benefits greatly from parallelism. In order to achieve this parallelism, the builder employs a work/thread pool. The commonj WorkManager, distributed with Globus, is used for this purpose. In this framework, the work to be done is modeled as implementations of the Work interface, and Work items are scheduled with the WorkManager for execution with a configurable pool of threads. This provides a mechanism to manage the amount of system resources consumed by the service for the purposes of scheduling background tasks. Each task concurrently scheduled beyond the maximum number of worker threads is placed in a priority queue for processing once a currently executing task completes, and a thread becomes available. The DomainModelBuilder utilizes the WorkManager by creating Work items for each UML Class and UML Attribute it processes in the model.
The DomainModelBuilder provides four variants of the operation used for creating domain model instances. Each method, takes as input, a representation of the caDSR Project for which the DomainModel should be created. The first, createDomainModelForProject, takes only the project description, and generates a model which describes the entire domain model being exposed for the project. The second, createDomainModelForPackage, additionally takes an array of Strings which represent UML package names in the Project which should be exposed. The method generates a model which describes exposing all UML Classes which are in UML Packages with a name specified in the array. Any associations to UML Classes outside of the specified packages are not exposed. The third method, createDomainModelForClasses, also takes an array of Strings which represent the fully qualified UML Class names which should be exposed in the model. Any association between classes not specified is omitted. The final method, createDomainModelForClassesWithExcludes, also takes an additional array of Strings which represent the fully qualified UML Class names which should be exposed in the model, but also takes an array of UMLAssociationExcludes which can be used to exclude specific associations from the model (in addition to the already excluded associations which reference classes not specified in the array of class names). The UMLAssociationExclude Class allows the client to specify a sourceRoleName, sourceClassName, targetRoleName, and targetClassName. Any UML Association which would otherwise be included in the computed subset of the DomainModel is omitted if it meets the criteria described by any of the UMLAssociationExcludes. The value of any attribute of the UMLAssociationExclude can be the wildcard "*" which indicates it should match anything. As such, specifying an exclude with "*" as the value for all attributes would effectively omit all associations from the DomainModel. By using no wildcards, a single association can be omitted, and by using a combination of some values and some wildcards, groups of associations can be omitted. For example, specifying an exclude instance with a sourceClassName value of "gov.nih.nci.cabio.domain.Gene" and wildcards for all other attributes would effectively omit any associations from the DomainModel where gov.nih.nci.cabio.domain.Gene was the source of the association. Using these methods, in combination with the service provided methods of finding all Projects, Packages, Classes, and Associations a DomainModel exposing any subset of Classes and Associations can be created. The DomainModelBuilder API allows a client to simply identify the items to be exposed in the Project, and it does the work to create the conforming DomainModel instance.
Administration
...