GT 3.9.5 Component Guide to Public Interfaces: WS MDS WebMDS (Tech Preview)

Semantics and syntax of APIs

Programming Model Overview

There is no "client" API for accessing WebMDS; WebMDS is a servlet that is accessed via web forms.

WebMDS uses a WebMDS plugin (a Java class that implements the WebmdsXmlSource interface) to acquire XML documents (which can be used either as raw information sources or as XSL transformations). WebMDS comes with two WebMDS plugins: FileXmlSource, which reads XML from a file (and is primarily used to acquire XSL transformations), and NodeXmlSource. NodeXmlSource in turn calls a node source plugin (a Java class that implements the WebmdsNodeSource interface) to acquire an XML DOM document. acquires XML information using a WebMDS XML source, a Java class that implements the WebmdsXmlSource interface. To summarize:

  • WebMDS is a servlet that uses plugins to acquire XML documents containing raw data and XSL transformations, and then applies the acquired XSL transformation on the acquired data.
    • The plugins used by WebMDS implement the org.globus.mds.webmds.WebmdsXmlSource interface.
    • WebMDS plugins include:
      • org.globus.mds.webmds.xmlSources.file.FileXmlSource, which reads XML from a file, and
      • org.globus.mds.webmds.xmlSources.xmlDomNode.NodeXmlSource, which uses its own plugin interface to acquire XML DOM documents.
        • The plugins used by NodeXmlSource implement the org.globus.mds.webmds.xmlSources.xmlDomNode.WebmdsNodeSource interface
        • Node source plugins include org.globus.mds.webmds.xmlSources.resourceProperties.ResourcePropertyNodeSource and org.globus.mds.webmds.xmlSources.resourceProperties.ResourcePropertyQueryNodeSource, which acquire resource property information.
  • The raw XML data acquired by WebMDS is processed by XSL transformations; see the W3C XSLT Documentation for more information on creating XSL transforms.

Component API

Semantics and syntax of the WSDL

Protocol overview

WebMDS is not a Web service and does not have any associated WSDL. For information on the web form-based protocol used by WebMDS, see the documentation on the WebMDS Graphical User Interface.

Command-line tools

There is no end-user command-line tool for WebMDS.

Tool description

The command-line tool webmds-create-context-file is used to create Tomcat configuration files needed to deploy WebMDS.

Command syntax

webmds-create-context-file [-f] tomcat_context_file

The tomcat_context_file argument is the location of the Tomcat configuration file defining the WebMDS context; in a default Tomcat installation, the location of this file will be $CATALINA_HOME/conf/Catalina/localhost.

By default, webmds-create-context-file will not overwrite an existing context file; the -f option is used to force webmds-create-context-file to overwrite an existing file.

Note: webmds-create-context-file is found in $GLOBUS_LOCATION/lib/webmds/bin

Example 
    $GLOBUS_LOCATION/lib/webmds/bin/webmds-create-context-file -f \
         $CATALINA_HOME/conf/Catalina/localhost

Limitations

Changes to the Tomcat context do not take effect until Tomcat is restarted or reloaded.

Overview of Graphical User Interface

Overview of the purpose and functionality of the GUI

The WebMDS GUI is a web-based interface for browsing formatted XML data, such as the results of resource property queries on a grid service.

Command and options

WebMDS can be accessed using any web browser. In a default WebMDS installation, the URL http://hostname:port/webmds corresponds to the top-level WebMDS web page. This page includes a link to a WebMDS invocation that provides summary information (with links to detailed information) about a locally-running MDS Index server. It also contains a link to a page of sample web forms demonstrating other uses of WebMDS.

Customizing the web forms used to access WebMDS

The WebMDS servlet is located at http://your-tomcat-host:your-tomcat-port/webmds/webmds. It takes the following arguments:
info The name of the XML source that will be used to collect the raw XML data. XML sources are defined by files in $GLOBUS_LOCATION/lib/webmds/conf. This argument must be specified.
xsl The name of the XML source that will provide the XSL transform. XML sources are defined by files in $GLOBUS_LOCATION/lib/webmds/conf. If this argument is not specified, the WebMDS servlet will display raw, untransformed XML.
xmlSource.info_name.param.source_specific_options Any additional options recognized by the info_name XML source (info_name must be the value of the info argument for this request). Source-specific options are discussed in the next section.
xmlSource.xsl_name.param.source_specific_options Any additional options recognized by the xsl_name XML source (xsl_name must be the value of the xsl argument for this request). Source-specific options are discussed in the next section.

Limitations

Error conditions (such as typographical errors in resource property names) are presented as stack traces, rather than user-friendly error messages.

Semantics and syntax of domain-specific interface

Interface introduction

WebMDS uses a web form interface to specify parameters such as where to find raw data and what XSLT transformations to apply to that data.

Syntax of the interface

The web form interface is described in the WebMDS User's Guide

Configuration interface

Configuration overview

WebMDS can be configured to get information from any of various sources and to filter it through any XSL transform. WebMDS uses configuration files to specify the location of (and to name) sources of information and xsl and web form arguments to select among these configured information sources and xsl transforms.

By default, WebMDS comes configured to report information about an index server using transaction-level security on the default port (8443) on the local system. If you are running the Globus Toolkit in this default configuration, then you can use WebMDS to query your local index service without any configuration changes.

If you wish to monitor a different index server, you will need to edit the file $GLOBUS_LOCATION/lib/webmds/conf/indexinfo to change the URL in the line: 

    https://127.0.0.1:8443/wsrf/services/DefaultIndexService
to match the URL of your default index service. Changes to WebMDS configuration files take effect the next time that Tomcat is restarted.

For other configuration changes (e.g., monitoring different kinds of services), see the detailed configuration information below.

Syntax of the interface

Each configuration file in $GLOBUS_LOCATION/lib/webmds/conf defines a source of XML, which can be used in an HTML form to specify sources of information and XSL transforms. The distribution contains some standard configuration files in this directory, including:

indexinfo all resource properties from an index server running with transaction-level security on port 8443 on the local host
indexinfo_nosec all resource properties from an index server running with no security on port 8080 on the local host
openEndedQuery all resource properties from a user-specified grid service
openEndedRP a user-specified resource property from a user-specified grid service
servicegroupxsl an xsl transform that presents summary information about a service group
sgedetail an xsl transform that presents detailed information about a service group entry

Each configuration file defines a WebmdsConfig object. A WebmdsConfig object consists of:

  • A description: a textual description of the XML source being defined.
  • A className: the name of the Java class that will be used to acquire the XML data.
  • Zero or more parameter objects, each of which consists of the name of some parameter recognized by the Java class specified by className, and the string value of that parameter.
For example, this is $GLOBUS_LOCATION/lib/webmds/conf/servicegroupxsl, which defines the servicegroupxsl XML source: 
    <WebmdsConfig>
      <description>
         XSL file to show service group summary information
      </description>
      <className>org.globus.mds.webmds.xmlSources.file.FileXmlSource</className>
      <parameter>
        <name>file</name>
        <value>xslfiles/servicegrouptable.xsl</value>
      </parameter>
    </WebmdsConfig>
This file tells WebMDS to use the org.globus.mds.webmds.xmlSources.file.FileXmlSource Java class (a class which reads XML from a local file) to collect XML data and to pass a file parameter (which that Java class interprets as the name of the file to open, relative to the WebMDS base directory).

Tomcat must be restarted (or one of the more advanced Tomcat administrative mechanisms must be used) for changes to these configuration files to take effect.

XML Sources included with WebMDS

FileXMLSource

The class org.globus.mds.webmds.xmlSources.file.FileXmlSource reads XML from a file, and recognizes a single parameter:
file The name of the file to read. Relative path names are interpreted relative to the WebMDS base directory ($GLOBUS_LOCATION/lib/webmds).

NodeXMLSource

This XML source class uses a WebmdsNodeSource object to fetch an XML document and return it in a form that is usable by WebMDS. It recognizes the following options:
class The name of a class that implements the WebmdsNodeSource interface. An instance of this class will be used to get an XML document.
parameters Additional parameters are passed to an instance of the class specified by the class argument.

Classes That Implement WebmdsNodeSource

The following classes implement the NodeXMLSource interfaces and can be used in conjunction with NodeXMLSource

ResourcePropertyQueryNodeSource

This class performs a resource property query to get all the resource properties for some web service. It recognizes the following configuration parameters:
endpoint The endpoint name to be used in a resource property query.
endpointKeyName and endpointKeyValue An optional key/value pair to use as reference properties for the endpoint specified with the endpoint parameter.
allowUserEndpoints If true, values for xmlSource.sourceName.param.endpoint, xmlSource.sourceName.param.endpointKeyName, and xmlSource.sourceName.param.endpointKeyValue specified in the request will override the configured endpoint value.
endpointFile The name of a file from which the endpoint information (in XML) will be read. This configuration parameter can never be overridden by request arguments.

ResourcePropertyNodeSource

This class queries a web service for a single resource property. It recognizes the following parameters:
endpoint The endpoint name to be used in a resource property query.
endpointKeyName and endpointKeyValue An optional key/value pair to use as reference properties for the endpoint specified with the endpoint parameter.
allowUserEndpoints If true, values for xmlSource.sourceName.param.endpoint, xmlSource.sourceName.param.endpointKeyName, and xmlSource.sourceName.param.endpointKeyValue specified in the request will override the configured endpoint value.
endpointFile The name of a file from which the endpoint information (in XML) will be read. This configuration parameter can never be overridden by request arguments.
rpNamespace The namespace part of the QName of the resource property to be queried for.
rpName The local name part of the QName of the resource property to be queried for.
allowUserResourceProperties If true, values of xmlSource.sourceName.param.rpNamespace and xmlSource.sourceName.param.rpNames specified in the request will override the configured resource property namespace and name.

Environment variable interface

WebMDS does not require that any environment variables be set by the client or by the Tomcat server.