This document is intended to be a starting guide to writing non web-service based information providers for the WS MDS using the RPProvider Framework. It covers the concepts and walks through a simple example of how to get arbitrary information into the WS MDS using the External Element producer. This External Element producer is part of the RPProvider Framework and is used for gathering arbitrary XML information about a resource by executing an external script. This is mostly useful for scenarios where you would like to publish information into the WS MDS from a non web-service based information source. For WSRF compliant web-service based information sources that export known Resource Properties, it is much easier to use Configuration file: parameters for the query aggregator source. However, that source is outside the scope of this document.

This document covers writing a simple information provider that publishes fortune information at a regular interval into the WS MDS's Index Service. This example was chosen because it is dynamic and simple, yet it illustrates all the fundamentals of this type of information provider.

It should be noted that this document is very similar to the document describing how to write an execution aggregator provider of the same fortune example. However, there are many differences using the newer RPProvider framework, and this document covers them.

2. Choosing (or conforming to) a Schema

The first step to getting information into the WS MDS is to decide which information you would like to have published. Since the data is in XML format, you should choose (or pick) the schema that you'd like the data to conform to. This generally means coming up with element names and types and creating some mapping of the data you're about to retrieve from your non web-service based application before putting it in to the WS MDS. For this example, I'm going to choose this very simple format for the data:

<fortuneInformation>
   <fortuneData>
      ... here is the fortune ...
   </fortuneData>
   <fortuneDateAndTime>
      ... date and time of retrieval ...
   </fortuneDateAndTime>
   <fortuneSourceURL>
      ... the URL of where the fortune was retrieved ...
   </fortuneSourceURL>
</fortuneInformation>

As you can see, that format is very simple. An example output will look like this:

<fortuneInformation>
   <fortuneData>
     186,282 miles per second: It isn't just a good idea, it's the law!
   </fortuneData>
   <fortuneDateAndTime>
     Thu Jul 14 18:16:01 CDT 2005
   </fortuneDateAndTime>
   <fortuneSourceURL>
     http://anduin.eldar.org/cgi-bin/fortune.pl?text_format=yes
   </fortuneSourceURL>
</fortuneInformation>

Once you've chosen how to represent your data in XML format, you can start thinking about how you're going to retrieve and prepare that data for publication.

3. The Code

The second step to getting information into the WS MDS is to write a script (or program) that gathers and formats the appropriate data. This can be C code, shell script, perl code, etc, and it doesn't matter what kind of methods it uses behind the scenes, so long as it produces well formatted XML data.

For example, if we wanted to publish a fortune into the Index Service (using the free and charitable online service located at http://anduin.eldar.org/cgi-bin/fortune.pl), we could write a simple shell script to retrieve it and format it into our chosen XML schema.

You can sample the source code for this example implementation [here]. It is written as a bash shell script due to its simplicity. Tested platforms include GNU/Linux only. For this script to properly publish information, you must have one (or more) of the following programs installed on the system: wget, lynx, or fortune. All of these programs come standard with most GNU/Linux distributions, and it's important to note that only one of them is required (i.e. not ALL are required). [ NOTE: Windows users must have something like the cygwin operating environment for this to work ]

Download the code: fortune_script.sh.

This file should be saved in your $GLOBUS_LOCATION/libexec directory, although if you feel more comfortable placing it somewhere else on your file system, it's ok to do so.

Download the RPProvider configuration file for customization: rp-provider-config.xml.

This file should be saved in your $GLOBUS_LOCATION/etc/globus_wsrf_mds_index directory.

4. Enabling The Provider

Now that we have the information provider written, the next step is to enable it so that we can test it. To do this you will need to do a few things. First, enable the RPProvider framework (if it's not already). Second, enable the Fortune Provider that we've just written, and finally restart your container to view the new information.

4.1. Enable the RPProvider framework

It's possible that your Globus Toolkit installation already has the RPProvider framework enabled. This section shows you how to verify if it is, and what to do if it is not. To do this, you will need to edit the $GLOBUS_LOCATION/etc/globus_wsrf_mds_index/server-config.wsdd file.

You should see an DefaultIndexService Handler section that looks something like this:

<service name="DefaultIndexService" provider="Handler"
     use="literal" style="document">
     <parameter name="providers"
                value="org.globus.wsrf.impl.servicegroup.ServiceGroupRegistrationProvider
                       org.globus.mds.usefulrp.rpprovider.ResourcePropertyProviderCollection
                       GetRPProvider
                       GetMRPProvider
                       QueryRPProvider
                       DestroyProvider
                       SetTerminationTimeProvider
                       SubscribeProvider
                       GetCurrentMessageProvider"/>

     <parameter name="handlerClass"
         value="org.globus.axis.providers.RPCProvider"/>
     <parameter name="scope" value="Application"/>
     <parameter name="allowedMethods" value="*"/>
     <parameter name="rpProviderConfigFile"
         value="/etc/globus_wsrf_mds_index/rp-provider-config.xml"/>
     <parameter name="className"
         value="org.globus.mds.index.impl.DefaultIndexService"/>
     <wsdlFile>share/schema/mds/index/index_service.wsdl</wsdlFile>
</service>

If the DefaultIndexService Handler section doesn't look like this, cut and paste the above and replace the existing Handler section for the DefaultIndexService. The two key distinctions are in the providers value section that has the line org.globus.mds.usefulrp.rpprovider.ResourcePropertyProviderCollection and the rpProviderConfigFile value. This latter value can be anything you want (relative to the system's $GLOBUS_LOCATION), but this document assumes the value that's specified above.

4.2. Enable the Fortune Provider

This step involves editing the $GLOBUS_LOCATION/etc/globus_wsrf_mds_index/rp-provider-config.xml file that was specified in the above step. It can be a different file, but you will have to adjust the value in the above step to change it here. For now, we're assuming that it's left as the default. If this file doesn't already exist, feel free to copy the sample file located at $GLOBUS_LOCATION/etc/globus_wsrf_mds_usefulrp/gluece-rpprovider-sample-config.xml to $GLOBUS_LOCATION/etc/globus_wsrf_mds_index/rp-provider-config.xml, or download the sample tailored for this HOWTO from here and copy it to $GLOBUS_LOCATION/etc/globus_wsrf_mds_index/rp-provider-config.xml, and start editing from there.

To enable the fortune provider, you will need to add a config block that looks like this (or see the rp-provider-config.xml file for downloading above):

<ns1:resourcePropertyProviderConfiguration xsi:type="ns1:resourcePropertyProviderConfig">
 <ns1:resourcePropertyName xsi:type="xsd:QName"
 xmlns:mds="http://my.ns.domain/fortuneProvider"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema">mds:FortuneRP</ns1:resourcePropertyName>
   <ns1:resourcePropertyImpl xsi:type="xsd:string"
   xmlns:xsd="http://www.w3.org/2001/XMLSchema">org.globus.mds.usefulrp.rpprovider.SingleValueResourcePropertyProvider</ns1:resourcePropertyImpl>
 <ns1:resourcePropertyElementProducers
 xsi:type="ns1:resourcePropertyElementProducerConfig">
 <ns1:className xsi:type="xsd:string"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema">org.globus.mds.usefulrp.rpprovider.producers.ExternalProcessElementProducer</ns1:className>
 <ns1:arguments xsi:type="xsd:string"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema">/MY/GLOBUS/LOCATION/libexec/fortune_script.sh</ns1:arguments>
 <ns1:arguments xsi:type="xsd:string"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema">dummyArgument</ns1:arguments>
 <ns1:period xsi:type="xsd:int"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema">300</ns1:period>
 </ns1:resourcePropertyElementProducers>
</ns1:resourcePropertyProviderConfiguration>

As you can see, there are a number of configurable parameters there such as the location of the fortune provider script, as well as the period at which it will be executed (in seconds). Feel free to edit those as necessary. NOTE: The argument line containing the dummyArgument is optional and is only provided as an example of how to pass command line arguments to your script. The fortune script will ignore that argument. If you need to add multiple arguments for your own custom scripts, just add another line similar to that for each of them and they will be received by the script in the same order that they appear in this file.

At this point, the fortune provider has been enabled for use with the RPProvider framework! As you can see, this framework simplifies much of the work of details of getting information into the IndexService. Simply restart the container and make sure there are no errors. If errors are reported, please check over all of the above steps and make sure that they were completed successfully. It's very easy to make unexpected typos!

5. An Example Query

neillm@glob bin $ ./wsrf-query -s \
https://127.0.0.1:8443/wsrf/services/DefaultIndexService \
"//*[local-name()='fortuneInformation']"

<fortuneInformation xmlns="">
<fortuneData>
You will remember, Watson, how the dreadful business of the Abernetty
family was first brought to my notice by the depth which the parsley
had sunk into the butter upon a hot day. -- Sherlock Holmes
</fortuneData>
<fortuneDateAndTime>
Tue Oct 27 12:07:16 PST 2006
</fortuneDateAndTime>
<fortuneSourceURL>
http://anduin.eldar.org/cgi-bin/fortune.pl?text_format=yes
</fortuneSourceURL>
</fortuneInformation>

This segment of the query output represents the fortune data we've just written and configured for use. As you can see the fortuneInformation block was properly published into the Index Service since it's now been properly configured!

6. Contact the author

Contact the author at neillm@mcs.anl.gov.

Prev		Next
Usage scenarios	Home	GT 4.2.0 Index Service: How to Write a File Element producer using the RPProvider Framework in WS MDS