WS Information Services : Developer's Guide

Overview
API: Aggregator | Service Data Providers
WS Service Data Providers
Web Service Data Browser
Querying Service Data (Xpath)
Querying Service Data (ogsi-find-service-data)
Querying Examples
GLUE schema
>Migrating from Pre-WS to WS: Porting Guide

Migrating from Pre-WS to WS: Porting Guide

The Globus® Toolkit Version 3.2 (GT3.2) includes a set of core Service Data Providers as well as the capability for you to create your own Service Data Providers. GT3.2 additionally gives you the capability to port existing user-created GT2.x/MDS2.x information provider programs into WS Service Data Providers, as described in this document.

This document is intended primarily for developers who want to extend the Information Services in their GT3.2 configuration by porting existing MDS2 information providers.  A knowledge of OGSA and Grid concepts, particularly as described in The Physiology of the Grid, is presumed.

Note: In order for an Index Service provider to make use of the Java APIs in GT3, you must substantially rewrite the provider or write a new provider, which is beyond the scope of this document.  See Creating Service Data Providers.

This document contains the following sections:

• Provider Overview
• Comparison of Provider Creation/Operation in Pre-WS and WS
• Porting a Pre-WS User-Created Provider Into WS

Provider Overview

The Information Services component of the Globus Toolkit includes a set of core Service Data Providers used to generate details about such things as platform type, host OS, system load, memory, file systems, CPU count, and other host resource information.

The Toolkit also provides the ability for a user to create their own Service Data Providers to generate any required data.

Pre-WS Information Providers

A set of core providers is included with MDS 2.2 and is described in detail in MDS 2.2 Core GRIS Providers .  While these providers can output host information and are available for several platforms, note that the purpose of this document is not to describe the porting of core host providers to new platforms.  In fact, this type of porting in WS is essentially the same as in Pre-WS, and the existing documentation (the above document and MDS 2.2 GRIS: Adding New Information Providers ) should be sufficient for that task.

The purpose of this document is to describe the porting of custom providers that output application-specific data.

WS Service Data Providers

A set of core providers is also included as part of the WS Information Services component and is described in detail in Creating Service Data Providers.  These providers produce host information as well as having script and interface utility functions.

Custom Service Data Providers in GT3.2 can be as simple or as complicated as needed.  The baseline case requires only that the provider developer create a Java class implementing the functions of one interface – SimpleDataProvider – whose purpose is to produce XML output as a result of its execution.  Refer to the above-referenced document for more details.

Comparison of Provider Creation/Operation in Pre-WS and WS

Before moving into the specifics of provider porting, let's review the basics of creating a custom provider and compare the differences and similarities between Pre-WS and WS in doing so.

The basic steps for creating a provider are as follows:

1. Decide on the kind of data you will need from the provider program, based on the needs or constraints of your application.

2. Decide on how you want the data to be represented and identified.

3. Create a program that adheres to the input and output requirements of the interface you are using.

4. Enable the provider program through the appropriate configuration mechanism, so it is properly defined and identified for execution.

These steps are described in more detail in the following sections, with Pre-WS/WS differences and similarities indicated.

Step 1: Determine Data to be Generated

As indicated above, almost any kind of data can be generated from your provider program, limited only by your intended application and the particular input, output, and configuration requirements of the environment (Pre-WS or WS) in which the provider will run.

Step 2: Define Format/Representation of Data

The next step is to decide how you want the data represented and identified.

In Pre-WS, you need to decide how the data should be represented in the Directory Information Tree (DIT).  This requires the definition of an LDAP schema for the GRIS to accept your data, an OID assignment, and naming conventions for the data.

In WS, you can define an XSD schema and a namespace to represent your provider data.  Definition of an XSD schema is optional, but recommended.  Definition of a namespace is required.  Refer to the Porting a Pre-WS User-Created Provider Into WS section later in this document for more information on defining a schema and a namespace.

Step 3: Create a Program That Adheres to Input/Output Requirements

Now, you need to create a program that adheres to the input and output requirements of the interface you are using.

In Pre-WS, your program must be callable by the fork() and exec() facilities of the GRIS back end, and must return LDIF objects conforming to the defined schema on stdout.

In WS, you can first create a Pre-WS/MDS-style executable and then use the fork() and exec() facilities of the ScriptExecutionProvider (a core WS provider) to invoke the program.  The ScriptExecutionProvider provides a wrapper for your program to generate XML on stdout, conforming to the XSD schema if one exists.

Step 5: Enable the Provider Program

Finally, you need to enable the provider program through an appropriate configuration mechanism, so it is properly defined and identified for execution.

In Pre-WS, you need to add an entry for your program to the grid-info-resource-ldif.conf file, which defines all active GRIS providers.

In WS, you will be using the ScriptExecutionProvider to invoke your program, as described above.  This means that there will need to be an entry in the Index Service configuration file, index-service-config.xml, file that references the ScriptExecutionProvider.   

You will need to perform some additional configuration steps to make the provider known to WS Information Services so it can be run for you.  These steps are described in detail in Creating New WS Service Data Providers.

Example

To further illustrate information provider creation and operation in Pre-WS and WS, let's use an example that we'll call “Machine Room Temperature Information Provider.”  The purpose of this provider is to communicate with a digital thermometer and return a numerical value in degrees centigrade.

The essence of this or any provider, then, is that it receives data from some external source and then publishes the data in the desired format.  This means that the main portion of the provider code (no matter what programming tools are used to create it) stays the same regardless of whether it is used in Pre-WS or WS.

For use in Pre-WS/MDS, we want the provider to output LDIF, so some code like the following could be added, where the current temperature would be substituted for $TEMPERATURE :

dn: mds-temperature-name=machineroom, ....
mds-temperature-name: machine-room
mds-temperature-value: $TEMPERATURE
mds-temperature-units: centigrade

For use in GT3, we want the provider to instead output XML, so some code like the following could be added:

<sensorns:temperature
    sensorns:name="machine-room"
    sensorns:value="$TEMPERATURE"
    sensorns:units="centigrade"
    xmlns:sensorns="http://www.example.com/sensors"
/>

Porting a Pre-WS User-Created Provider Into WS

Now that we've reviewed the similarities and differences in creating providers for use in Pre-WS and WS, we're ready to focus in on the steps for porting a Pre-WS user-created provider into WS, which are as follows:

1. Redefine the format and representation of the data.

2. Rewrite the existing code to output XML instead of LDIF.

3. Enable the revised provider via the appropriate configuration mechanism.

These steps are described in detail in the following sections.

Step 1: Redefine the Format and Representation of the Data

Redefining the format and representation of your data involves three steps, as follows:

a) Choose an XML namespace for the data.
b) Optionally, write an XSD schema for the data.
c) Register the provider, namespace, and schema if you have one.

These steps are described in detail below.

Step 1a: Choose an XML Namespace for the Data

As the development of user-created Service Data Providers expands, it becomes increasingly important that the providers have unique, nonconflicting XML namespaces.  Without this, the providers may collide with each other.  Namespace assignments are a requirement of the Open Grid Services Infrastructure (OGSI) Specification. 

The declaration of namespaces is described in detail in the World Wide Web Consortium document Namespaces in XML.

XML namespaces are essentially URIs (they don't have to point to a web page) designed to provide universally unique names for elements and attributes. This allows you to define elements and attributes that can be reused in other schemas or instance documents without fear of name collisions.

For example, consider a namespace defined for the GLUE schema as:  http://glue.base.ogsa.globus.org/ce/1.1.  The Host element can be referenced in this namespace, with the knowledge that it is different from the Host element in a different namespace that may have been defined elsewhere and may not otherwise be known.

Step 1b: Write an XSD Schema for the Data

It is not required that you define a schema for the data output by your ported provider.  However, we do recommend having a schema for the following reasons:

• You can use third-party schema validation tools to check provider output.
• You can use automated language stub generators (like the one that is part of Axis in the GT3.2 distribution) to generate code that converts between XML and Java classes automatically.

The schema you write for your ported provider will replace your existing MDS2.x schema.         

Step 1c: Register the Provider, Namespace, and Schema

As a service to Globus Toolkit users, ISI/CGT will keep track of user-created Service Data Providers and their namespaces and schemas.  This will assist the user community in finding existing providers that have functionality in which they are interested.  To register a provider and related information with ISI/CGT, send e-mail to benc@isi.edu .

Step 2: Rewrite the Existing Code

The next step in the porting process is to replace the existing MDS2.x code with new code that outputs XML elements.  There are no particular constraints on the programming tools you can use to do this.

If backwards compatibility with MDS2 is desired, you can optionally create a single command that will invoke the provider, with separate command-line options for XML and LDIF.  That way the provider will continue to work in Pre-WS and will then work in WS as well.  The LDIF option can be removed if or when you fully transition to GT3.

Step 3: Enable the Revised Provider

The final step in the porting process is to enable your revised provider program so that it is properly defined and identified for execution.

As described in Create a Program That Adheres to Input/Output Requirements earlier in this document, you can use the fork() and exec() facilities of the ScriptExecutionProvider (a core WS provider) to invoke the program.  The ScriptExecutionProvider provides a wrapper for your program to generate XML on stdout.

Since you are using the ScriptExecutionProvider to invoke your program, there needs to be an entry in the index-service-config.xml providers file that references the ScriptExecutionProvider.

You will need to perform some additional configuration steps to make the provider known to WS Index Services so it can be run for you.  These steps are described in detail in Creating Service Data Providers.