---

Metadata 1.2 Design Guide

---

	Table of Contents 1 Metadata 1.2 Design Guide 2 Introduction to the Technical Guide 2.1 Overview of the Guide 2.2 Document Text Conventions 3 caGrid Metadata Infrastructure Overview 3.1 Introduction 4 caGrid Metadata 4.1 Cancer Data Standards Repository (caDSR) 4.1.1 Semantic Annotation of UML Domain Models 4.1.2 UML Domain Model Loader 4.1.3 UML to caDSR Mapping 4.1.4 caGrid Reliance on caDSR 4.2 caGrid Standard Metadata Model 4.2.1 Standard Metadata Model (gov.nih.nci.cagrid.metadata) 4.2.1.1 metadata::ServiceMetadata 4.2.2 Common Components (gov.nih.nci.cagrid.metadata.common) 4.2.2.1 metadata::ServiceMetadata 4.2.2.2 common::Address 4.2.2.3 common::Enumeration 4.2.2.4 common::PointOfContact 4.2.2.5 common::ResearchCenter 4.2.2.6 common::ResearchCenterDescription 4.2.2.7 common::SemanticMetadata 4.2.2.8 common::UMLAttribute 4.2.2.9 common::UMLClass 4.2.2.10 common::ValueDomain 4.2.3 Standard Data Service Metadata Model (gov.nih.nci.cagrid.metadata.data) 4.2.3.1 data::DomainModel 4.2.3.2 data::UMLAssociation 4.2.3.3 data::UMLAssociationEdge 4.2.3.4 data::UMLClass 4.2.3.5 data::UMLClassReference 4.2.3.6 data::UMLGeneralization 4.2.4 Service Description Components (gov.nih.nci.cagrid.metadata.service) 4.2.4.1 service::CaDSRRegistration 4.2.4.2 service::ContextProperty 4.2.4.3 service::Fault 4.2.4.4 service::InputParameter 4.2.4.5 service::Operation 4.2.4.6 service::Output 4.2.4.7 service::Service 4.2.4.8 service::ServiceContext 4.3 Metadata APIs 5 Advertisement and Discovery 5.1 Introduction 5.2 Requirements 5.3 Globus Information Services 5.4 WSRF Resource Properties List of Figures Figure 1 : Data Description Overview Figure 2 : UML to caDSR mapping Figure 3 : caGrid Standard Service Metadata Figure 4 : Common Model Figure 5 : Data Service Metadata Model Figure 6 : Service Model Figure 7 Metadata Utilities Figure 8 Metadata Exceptions Figure 9 : Advertisement and Discovery Overview Figure 10 : Globus Resource Framework Figure 11 : Globus Resource Property Framework Figure 12 : caGrid Resource Implementation Figure 13 : Example Registration Configuration Figure 14 Advertisement Client Overview Figure 15 : Discovery API Figure 16 : Discovery API Utilities Figure 17 : Discovery API Example Code Figure 18 : Example Custom Serialization configuration Figure 19 : SDK Serialization Framework Figure 20 : Example WSDD Type Mapping Figure 21 : EA generated Chromosome type from caBIO Figure 22 : GME Namespace Format Figure 23 : Namespace Naming Conventions Figure 24 : Example caTIES Document serialization Figure 25 : caDSR and GME relationship Figure 26 : UML to XML Mapping Figure 27 : BookStore Example UML Model Figure 28 : Package Structure of Example UML Model Figure 29 : Example Project Schema Figure 30 : Common Package of Example Project Schema Figure 31 : Bookstore Package of Example Project Schema Figure 32 caDSR Discovery Tool Figure 33 caDSR Selection Tool Figure 34 Service Metadata Editor Figure 35 Service Metadata Editor Classes Figure 36 Data Service Metadata Viewer Figure 37 XMI-based Schema Creation Figure 38 SDK Type Selection Classes

Introduction to the Technical Guide

---

Overview of the Guide

Brief overview of this developer's guide.

Document Text Conventions

The following table shows various typefaces to differentiate between regular text and menu commands, keyboard keys, and text that you type. This illustrates how conventions are represented in this guide.

Table 1 Document Conventions

caGrid Metadata Infrastructure Overview

---

Introduction

Extending beyond the basic grid infrastructure, caBIG specializes these technologies to better support the needs of the cancer research community. A primary distinction between basic grid infrastructure and the requirements identified in caBIG and implemented in caGrid is the attention given to data modeling and semantics. caBIG adopts a model-driven architecture best practice and requires that all data types used on the grid are formally described, curated, and semantically harmonized. These efforts result in the identification of common data elements, controlled vocabularies, and object-based abstractions for all cancer research domains. caGrid leverages existing NCI data modeling infrastructure to manage, curate, and employ these data models. Data types are defined in caCORE UML and converted into ISO/IEC 11179 Administered Components, which are in turn registered in the Cancer Data Standards Repository (caDSR). The definitions draw from vocabulary registered in the Enterprise Vocabulary Services (EVS), and their relationships are thus semantically described.
In caGrid, both the client and service APIs are object oriented, and operate over well-defined and curated data types. Clients and services communicate through the grid using respectively Globus grid clients and service infrastructure. The grid communication protocol is XML, and thus the client and service APIs must transform the transferred objects to and from XML. This XML serialization of caGrid objects is restricted in that each object that travels on the grid must do so as XML which adheres to an XML schema registered in the Global Model Exchange (GME). As the caDSR and EVS define the properties, relationships, and semantics of caBIG data types, the GME defines the syntax of the XML serialization of them. Furthermore, Globus services are defined by the Web Service Description Language (WSDL). The WSDL describes the various operations the service provides to the grid. The inputs and outputs of the operations, among other things, in WSDL are defined by XML schemas (XSDs). As caBIG requires that the inputs and outputs of service operations use only registered objects, these input and output data types are defined by the XSDs which are registered in GME. In this way, the XSDs are used both to describe the contract of the service and to validate the XML serialization of the objects which it uses. Figure 1 details the various services and artifacts related to the description of and process for the transfer of data objects between client and service.
Figure 1 : Data Description Overview

caGrid Metadata

---

Cancer Data Standards Repository (caDSR)

Semantic Annotation of UML Domain Models

Proper semantic integration requires that each class and it's attributes from the UML domain model gets mapped to appropriate concepts in a controlled terminology. The caCORE SDK utilizes the NCI Thesaurus as its primary terminology source, but any well structured, concept-based description logics terminology should in principle be suitable. The concept selection process can be entirely manual, or it can be partially automated using the Semantic Connector, a tool supplied by the caCORE SDK. The Semantic Connector uses the UML domain Model expressed in XMI as input and uses the caCORE EVS APIs hosted at the NCI to search the NCI Thesaurus for appropriate concepts. Semantic annotations for classes and attributes are specified using tagged values in the UML domain model.

UML Domain Model Loader

The UML domain model, annotated with semantic concept codes, contains a considerable amount of metadata about the ultimate system - both data and analytical services - that will be deployed to the grid. However, it is not in a form that is amenable to query and retrieval in a runtime environment nor easily queried by humans to make use of this information for other purposes. UML domain model loader addresses these limitations by transforming and loading the models into the caDSR, which provides APIs that support runtime access to metadata.
UML domain model annotated with semantic concept information is exported to XMI format using a UML modeling tool such as Enterprise Architect. It is then used as an input to the UML domain model loader, which uses a set of mapping rules to load metadata represented by Classes, Attributes and Associations into entities of caDSR. Following section contains the details of the UML to caDSR mapping rules.

UML to caDSR Mapping

Metadata represented in UML domain model is mapped to caDSR administered component types, illustrated in Figure 2 and using the following mapping rules:

• A UML Class is mapped to an Object Class, which according to ISO 11179 specification represents a thing in real-world.
• An attribute of a UML Class is mapped to a Property, which according ISO 11179 specification represents an attribute of a real-world thing
• Combination of a UML Class and one of it's attributes is mapped to a Data Element Concept.
• Combination of UML Class, one of it's attributes and data type of the attribute is mapped to a Data Element, commonly referred to as a Common Data Element (CDE).
• Project to which the UML domain model belongs to is mapped to a Classification Scheme.
• Packages in the UML model - which may represent sub-projects within a project - are mapped to Classification Scheme Items
• Association between two classes is mapped to Object Class Relationship

Refer to "Registration of Metadata in the caDSR" chapter of caCORE SDK Programmer's guide for complete details on loading UML domain models to caDSR

Figure 2 : UML to caDSR mapping

caGrid Reliance on caDSR

After a UML domain model is transformed, loaded and curated in caDSR, the model is ready to be used as the basis of an object oriented grid client and service. All data movement in caGrid between client and service is done so using instances of Classes registered in the caDSR. caGrid requires that all data types used in the grid are registered in caDSR, and come from a given Project version. That is, even though Attributes and other items in caDSR can be versioned individually, in order to use those types on the grid, they need to be associated with a specific Project version.
Several components of caGrid make use of the wealth of information in the caDSR. As mentioned above, grid services use registered data models as their information model. By doing so, they are able to advertise both the syntax and semantics of the model by exposing an export of the relevant caDSR information as service metadata. The details of the model used to expose this information are shown in the section below. Once the information is exposed in this model, caGrid leverages for grid service advertisement and discovery. These processes are described in detail in Chapter 4. Finally, the information models registered in caDSR are used as the conceptual foundation for the actual communication format used to exchange data on the grid. This process of serializing and deserializeing data instances on the grid, is detailed in Chapter 5.

caGrid Standard Metadata Model

All caGrid Services are expected to publish a set of standard metadata which draws heavily from the metadata registered in caDSR and EVS; it details the functionality of the service, and the institution providing it. The following sections describe these models.

Standard Metadata Model (gov.nih.nci.cagrid.metadata)

metadata::ServiceMetadata

public Class:
metadata::ServiceMetadata Connections

Common Components (gov.nih.nci.cagrid.metadata.common)

metadata::ServiceMetadata

public Class:
metadata::ServiceMetadata Connections

common::Address

public Class:
common::Address Connections

common::Address Attributes

common::Enumeration

public Class:
common::Enumeration Connections

common::Enumeration Attributes

common::PointOfContact

public Class: For the static model, instances of these should be the POCs associated with the design and implementation of the service itself (not deployments of it, e.g. not system support staff)The "role" attribute should probably be an enumeration of known types
common::PointOfContact Connections

common::PointOfContact Attributes

common::ResearchCenter

public Class:
common::ResearchCenter Connections

common::ResearchCenter Attributes

common::ResearchCenterDescription

public Class:
common::ResearchCenterDescription Connections

common::ResearchCenterDescription Attributes

common::SemanticMetadata

public Class:
common::SemanticMetadata Connections

common::SemanticMetadata Attributes

common::UMLAttribute

public Class: caDSR-relatedRepresents a UML attribute of the parent UML Class. Indication of isRequired=false means the operation will function without the existence of this attribute.
common::UMLAttribute Connections

common::UMLAttribute Attributes

common::UMLClass

public Class: caDSR-relatedRepresents the UML Class of the given input or output.
common::UMLClass Connections

common::UMLClass Attributes

common::ValueDomain

public Class:
common::ValueDomain Connections

common::ValueDomain Attributes

Standard Data Service Metadata Model (gov.nih.nci.cagrid.metadata.data)

data::DomainModel

public Class:
data::DomainModel Connections

data::DomainModel Attributes

data::UMLAssociation

public Class:
data::UMLAssociation Connections

data::UMLAssociation Attributes

data::UMLAssociationEdge

public Class:
data::UMLAssociationEdge Connections

data::UMLAssociationEdge Attributes

data::UMLClass

public ClassExtends: UMLClass. :
data::UMLClass Connections

data::UMLClass Attributes

data::UMLClassReference

public Class: Represents a "pointer/reference" to a UMLClass exposed by this DomainModel. The refid attribute must share the value of an UMLClass.id on the exposedClassCollection of this model. This exists solely as an optimization for not duplicating the UMLClass (in XML) everywhere it is associated (which is a significant savings).
data::UMLClassReference Connections

data::UMLClassReference Attributes

data::UMLGeneralization

public Class:
data::UMLGeneralization Connections

Service Description Components (gov.nih.nci.cagrid.metadata.service)

service::CaDSRRegistration

public Class:
service::CaDSRRegistration Connections

service::CaDSRRegistration Attributes

service::ContextProperty

public Class: This represents an exposed property of a service context's state.This is manifested as a resource property in the grid.
service::ContextProperty Connections

service::ContextProperty Attributes

service::Fault

public Class: This represents an error that could occur during the execution of the operation.This is manifested as an operation fault in the grid.
service::Fault Connections

service::Fault Attributes

service::InputParameter

public Class: Represents an input parameter to an operation.This is manifested as a parameter of a service request in the grid.
service::InputParameter Connections

service::InputParameter Attributes

service::Operation

public Class: This represents a method/operation/function in a service context. Its input parameters are described by its InputParameter associations, its output by its Output association, and any errors it produces by its Fault associations.This is manifested as an operation of a service in the grid.
service::Operation Connections

service::Operation Attributes

service::Output

public Class: Represents the result/output of an operation. Its non-existence represents the operation produces no result.This is manifested as the value of an operation response in the grid.
service::Output Connections

service::Output Attributes

service::Service

public Class: A service is a "conceptual" definition of a collection of functional contexts.This has no physical manifestation in the grid.
service::Service Connections

service::Service Attributes

service::ServiceContext

public Class: This is a functional collection of operations that work over a common collection of stateful resources.A service without stateful resources would have a single context.This is manifested as an actual service in the grid.
service::ServiceContext Connections

service::ServiceContext Attributes

Metadata APIs

This section describes the high-level API which can be used to access and manipulate instances of the metadata described above. All the standard metadata models have Java Bean representations which can be used to programmatically interact with the models. The APIs described herein can be used access these models from services, and serialize and deserialize them to and from XML. These methods complement the Discovery API (described later), as once an EPR (End Point Reference) is returned from the Discovery API, these methods can be used access and inspect the full metadata. There are also more detailed methods provided for examining DomainModel metadata in the data service utility API: gov.nih.nci.cagrid.data.utilities.DomainModelUtils.

The MetadataUtils class is a simple class with static methods that provide stand-alone capability to retrieve standardized metadata from remote services, and serialize and serialize those (or other) instances. The ResourcePropertyHelper API not detailed here, is the lower level API which can be used to directly gather information about ResourceProperties (which is how metadata is exposed in caGrid). The MetadataUtils, described herein and shown above in Figure 7, leverage this API, and expose some of its exceptions. The possible exceptions generated by the metadata utility methods are detailed below in Figure 8. A non discerning client may simple opt to catch ResourcePropertyRetrievalException, as it is the base checked exception. An additional non-checked exception, InternalRuntimeException, can also be thrown, but it is solely used to represent an internal logic error in the APIs and so it is not expected clients can "recover" from such an exception. As such, client should not attempt to catch this runtime exception for any other reason than to mask the problem. QueryInvalidException, is thrown if an invalid XPath query is issued. Problems originating from remote services are thrown in the subclass, RemoteResourcePropertyRetrievalException. In general use of the metadata utilities, this is the most likely exception clients may see, as it is thrown if a service is not properly exposing the proper metadata. Clients leveraging the lower level resource property APIs should take care to appropriately address each type of exception if they are communicating with services. For example, even though it is a caBIG requirement to expose the standard service metadata, clients should properly handle the case where it is not present. Asking for specific metadata that a service does not provide would yield an InvalidResourcePropertyException. Detailed examples and API overview can be found in the caGrid Programmer's Guide.
Figure 8 Metadata Exceptions

Advertisement and Discovery

---

Introduction

As caBIG aims to connect data and tools from 50+ disparate cancer centers, a critical requirement of its infrastructure is that it supports the ability of researchers to discover these resources. caGrid enables this ability by taking advantage of the rich structural and semantic descriptions of data models and services that are available. Each service is required to describe itself using caGrid standard service metadata. When a grid service is connected to the caBIG grid, it registers its availability and service metadata with a central indexing registry service (Index Service). This service can be thought of as the "yellow pages" and "white pages" of caBIG. A researcher can then discover services of interest by looking them up in this registry. caGrid provides a series of high-level APIs and user applications for performing this lookup which greatly facilitate the process.
As the Index Service contains the service metadata of all the currently advertised and available services in caBIG, the expressivity of service discovery scenarios is limited only by the expressivity of the service metadata. For this reason, caGrid provides standards for service metadata, as described in the previous chapter, to which all services must adhere.

As shown in Figure 9, the caGrid discovery API and tools allow researchers to query the Index Service for services satisfying a query over the service metadata. That is, researchers can lookup services in the registry using any of the information used to describe the services. For instance, all services from a given cancer center can be located, data services exposing a certain domain model or objects based on a given semantic concept can be discovered, as can analytical services that provide operations that take a given concept as input.

Requirements

The Globus Information Services are a major aspect of the infrastructure needed to satisfy the caBIG requirements for Advertisement and Discovery. These requirements specify what is needed to support the basic use cases of advertising the availability and function of a grid service by a service provider, and the discovery of said information by a user, respectively. The general use cases are explained below.
Advertisement:
The caGrid Grid Service Owner (Actor) composes service metadata describing the service to the grid and publishes it to grid. The service metadata describes properties of the grid services that caGrid users and other grid services may query.
Discovery:
A caGrid Researcher (Actor) specifies search criteria describing a service. The research submits the discovery request to a discovery service, which identifies a list of services matching the criteria, and returns the list to the researcher.
These general themes specify that the caBIG infrastructure must support the following use cases:

• Publish advertisement a Grid Service
• Remove advertisement of a Grid Service
• Update advertisement of a Grid Service
• Discover advertisement a Grid Service

Globus Information Services

The Globus Information Services component, realized as the Monitoring and Discovery System (MDS) is a suite of web services to monitor and discover resources and services on Grids. This system allows users to discover what resources are considered part of a Virtual Organization (VO) and to monitor those resources. MDS services provide query and subscription interfaces to arbitrarily detailed resource data and a trigger interface that can be configured to take action when pre-configured trouble conditions are met. MDS is composed of the following three main components:

• WS MDS Index Service - This service contains a registry of grid resources and collects information from them, making it accessible and queryable from one location. Generally, a virtual organization deploys one or more index services, which then collect data on all of the grid resources available within that VO.
• WS MDS Trigger Service - This service collects data from grid resources and passes the data to appropriate programs to perform various actions in response to events. (not currently used by the caGrid metadata infrastructure).
• WS MDS Aggregator - This is the infrastructure on which the previous services are built. It collects, manages, and indexes data from an aggregator source and sends that data to an aggregator sink for processing.

WSRF Resource Properties

The section provides a brief recap of information about WSRF and the Globus implementation of it. More details can be found in the Globus documentation.
The Globus 4 toolkit provides a toolkit for create WSRF grid services. The WS-Resource Framework (WSRF) is a set of six Web services specifications that define what is termed the WS-Resource approach to modeling and managing state in a Web services context. In this approach, a resource is an entity that encapsulates the state of a stateful web service. Generally, each resource is a separate object but in certain cases it might be a singleton. A resource may just be a front end for state kept in an external entity, such as a file in a file system, a row in a database or an entity bean in a J2EE container.
Figure 10 : Globus Resource Framework
A resource key is represented by a ResourceKey interface. It is a combination of a key name and the actual key value. A resource is represented by a Resource interface. It is a marker interface without any method defined. All resource objects must implement this interface. Resources are managed by an object that implements the ResourceHome interface. The ResourceHome interface provides methods for finding and removing resources as well as methods for identifying the SOAP header element and class for the resource key. In addition to the methods specified by the interface, ResourceHome implementations will generally provide an implementation-specific create() call or any other methods that operate on a set of resources.
Resources may have resource properties. Resource properties are declared in the WSDL of the service as elements of a resource property document. The ResourceProperties interface contains a single accessor method for retrieving the ResourcePropertySet from a resource. It must be implemented by all resources that want to expose resource properties. The ResourcePropertySet is the representation of the resource property document associated with the resource. It contains methods for managing the set of resource properties, e.g. adding and removing resource properties, and for discovering properties of the document itself, e.g. its name. The ResourceProperty interface needs to be implemented by all resource properties. It contains methods for: managing the set of values associated with the resource property, discovering properties of the resource property element, and serializing the resource property to a array of SOAP or DOM elements. The ResourcePropertyMetaData interface contains metadata information about a ResourceProperty such as resource property name, cardinality, etc.

Figure 11 : Globus Resource Property Framework
Once metadata items are exposed as ResourceProperties, they can be queried using standard web service operations defined by the WS-ResourceProperties specification. Consult the specification for more details, but a synopsis of the operations are provided here:

• GetResourceProperty: allows access to the value of any resource property given its QName.
• GetMultipleResourceProperties: allows access to the value of several resource properties at once, given each of t