User's Guide Core Framework

Globus Toolkit 3.0 - Last Updated 09/03/2003

Contents

  1. Introduction
  2. Installation
  3. Samples
  4. Common Higher Level Base Services
  5. Configuration
  6. Logging and Debugging
  7. Security Support
  8. .Net Support
  9. Web Start Support
  10. EJB Services
  11. Command Line Clients
  12. Command Line Script Generation
  13. Setenv Scripts

1 Introduction

This User's Guide describes how to setup the toolkit, and how to run the samples. For a detailed description of how to write a Grid service please refer to the Programmer's Guide. The current implementation is based on the GGF Open Grid Services Infrastructure v1.0 specification ( Draft 29,  released on April 5, 2003). The toolkit comes both in a source-, and a binary distribution. The source distribution contains source for the core framework as well as all samples, whereas the binary distribution only has the source for the samples. When downloading the source you can easily build your own binary distribution to work with. The build and development environment is largely the same in both distributions. For consistency this guide assumes you have a binary distribution (either downloaded from the web, or created from a source cvs checkout) unless otherwise stated. The binary distribution does not require you to download any external tools to run the samples (apart from a Java VM), we however recommend that you also in this case download the build system we are using (ant), in order to make it easier to build, and deploy the samples, as well as writing your own services.

Document conventions:
<ogsa root> refers to the location where you unpacked the distribution
<ogsa java root> refers to the java root of the distribution. In the source distribution case this is <ogsa root>/impl/java and in the binary distribution it is the same as <ogsa root>
<source dir> this is the directory where the source resides, so in the binary distribution it will be 'samples', and in the source distribution it will be 'src'.

2 Installation

2.1 Required Tools

2.2 Optional Tools

  • Jakarta Tomcat 4.1.24 http://jakarta.apache.org/tomcat (4.0.6 has also been tested to work)
    • (We also provide a standalone web service container for testing purposes which is why tomcat is optional.)
  • Microsoft .NET Framework 1.1, and/or Visual Studio .NET 2003 (April 2003 release)
  • Junit 3.8.1 http://www.junit.org (if you want to run our tests in the source distribution)

2.3 Distributed Tools

Our framework ships with a number of external tools. They are automatically picked up, so in general you don't have to worry about these. We mention the tools here for reference purposes, it is not recommended to replace any of these tools by another version you may already have. Other jars we distribute are results of dependencies of the above tools. Please look at their respective license files or consult the parent tool homepage listed above.

Secondary Dependencies:
wsdl4j, commons-logging, commons-discovery, jaxrpc, saaj, distributed by Apache Axis
PureTLS, BouncyCastle, log4j, cryptix distributed by Java CoG Kit

2.4 Quick Start

If you have a binary distribution, and you just want to test and run the demo and samples quickly (without downloading any external tools) then you can do the following:
  1. Start the grid service container by typing: globus-start-container -p 8080 (Starts up a server on port 8080)
  2. Run the demo client by typing: globus-service-browser http://localhost:8080/ogsa/services/core/registry/ContainerRegistryService
For a guide on how to use the ServiceBrowser demo see section 3

2.5 Installing the Build System

In order to build the source distribution or the samples in the binary distribution you would need to download Jakarta Ant. We also use Ant as a scripting tool to simplify testing and deployment.
  1. Download Ant 1.5 distribution from http://jakarta.apache.org/ant
  2. Unzip ant into your preferred location and set the ANT_HOME environment to point to this location
  3. Put junit.jar (download from http://www.junit.org) into ANT_HOME/lib (only necessary if you want to run the tests in the source distribution)
  4. Add ANT_HOME/bin to your PATH environment

2.6 Creating a Binary Distribution from a Source Distribution

  1. Go to the <ogsa root>/impl/java directory
  2. type: ant dist
  3. A binary distribution will be placed in <ogsa root>/impl/java/build/ogsa-<version>

2.7 Running the Samples using Ant

  1. Run the standalone service container by typing: ant startContainer [-Dservice.port=<port>]
  2. Run the demo client by typing: ant gui [-Dservice.port=<port>]
Note, you can set the service.port property in the <ogsa java root>/ogsa.properties file to change the port the service container will listen on (default is 8080). Alternatively you can pass in -Dservice.port=<port> on the command line. To stop the container use ant stopContainer or send it a kill signal..

2.8 Tomcat Installation

You can run the entire framework and all the samples inside of the standalone service container we provide. However it was mainly designed for testing purposes, so the framework can  also be deployed in tomcat.
  1. Type ant -Dtomcat.dir=<tomcat root> deployTomcat
  2. Add .wsdl and .xsd MIME types to Tomcat server edit <tomcat root>/conf/web.xml file and add the following (anywhere in the web-app):
    <mime-mapping>
       <extension>gwsdl</extension>
       <mime-type>text/xml</mime-type>
    </mime-mapping>
    <mime-mapping>
       <extension>wsdl</extension>
       <mime-type>text/xml</mime-type>
    </mime-mapping>
    <mime-mapping>
        
<extension>xsd</extension>
        
<mime-type>text/xml</mime-type>
    </mime-mapping>
When using the Sun Java Hotspot VM you may also want to increase your heap space for the tomcat engine.
You can do this by setting the -Xmx flag to for instance -Xmx128m (128 MB max heap) in the CATALINA_OPTS environment.

Note, there is a known problem with the AxisServlet in Tomcat causing an empty document to be returned with a successful HTTP status if the tomcat configuration is broken. To debug it further please check the tomcat logs in <tomcat root>/logs/ or the log4j logs in the server (see section 7). The error returned to the client will be a SaxException and look something like: 'Line=1: The root element is required in a well-formed document'.

By default the ogsi servlet runs in the ogsa/services app, and the schemas are picked up from the ROOT context ("/"). In order to change this you can modify the WEB-INF/web.xml file, for example:  

<servlet>
  <servlet-name>OgsiServlet</servlet-name>
  <display-name>OGSI Container Servlet</display-name>
  <servlet-class>
    org.globus.ogsa.server.OgsiServlet
  </servlet-class>
  <init-param>
    <param-name>ogsiLocation</param-name>
    <param-value>ogsa-test/services/</param-value>
  </init-param>
  <init-param>
    <param-name>schemaContext</param-name>
    <param-value>ogsa-test</param-value>
  </init-param>
</servlet>
ogsiLocation specifies the new path to the web app, and schemaContext 
specifies what context should be used to pick up the schema files.

3 Samples

3.1 Sample Code

The sample WSDL and XML Schemas are located in <ogsa root>/schema/samples. The source code is located in <ogsa java root>/<source dir>/org/globus/ogsa/impl/samples. In the binary distribution source dir is 'samples', and in the source distribution it is 'src'. To build the samples type: ant samples. Many samples have simple command line client demos in <ogsa java root>/<source dir>/org/globus/ogsa/impl/samples/<sample>/client and gui clients in <ogsa java root>/<source dir>/org/globus/ogsa/gui.

3.2 Overview of  Samples

Counter
basic - a simple counter maintaining the calculated value as state
generate - same as basic counter but defines a java interface that is used to generate the wsdl for the service
delegation - implementation of basic counter using the delegation approach
logging - a basic counter making use of debug logging
notification - a counter demo showcasing use of notifications
secure - basic counter showcasing gsi enabled service
persistent - a counter that can recover after a server restart
routable - shows virtual hosting environment routing using our proxy and router framework (note to run this sample you have to start up the service container outside of ant as described in section 2.4)

Notification
This is a demo designed to showcase notification subscriptions in a gateway service

Weather
The weather demo shows 3rd party web service integration with a live temperature service. It also shows how to expose your service client GUI dynamically using service data.

Google
This demo shows a google integration, and also demonstrates how rpc/encoded services can be used within our framework

Chat
This demo illustrates the use of basic notification by providing a simple chat service.

Registry
This demo is a VORegistry service implementing the Registry Port Type and allows remote services to publish their GSHs and service data into a community repository of services

Guide (off root directory)
Samples discussed in Programmer's Guide.

Exception
Shows examples of how to use our chained WSDL amd Java exception framework

Array
Demo showing how custom java objects can be used inside of arrays

Any
Service showing the use of xsd:any extensibility elements from Java.

3.3 Service Browser GUI

The service browser gui is designed using the Web Browser metaphor. You can type in a URL (which is a GSH) to inspect and use a remote service, which will be rendered in the GUI. The GUI framework retrieves the WSDL document for the GSH (displayed in the WSDL tab) and maps Port Types exposed by this WSDL to GUI panes. If an appropriate GUI pane cannot be matched with a given Port Type, a dynamic pane can be used which shapes itself according to the methods exposed by the Port Type. Note in this case you will need to add type mappings explicitly to client-config.wsdd if you use complex types. The encoded counter sample can be used to showcase this with the dynamic gui if you enable client deployment in the build-samples.xml file.

Look for a ServiceGroup Inspection pane to get a list of services exposed by an ServiceGroup service. The entries in this list can be viewed as service links, and by double clicking on the entries you follow the link and render the target service interface in the GUI.

If a factory service is rendered, you can create new transient service instances that will be introspected the same way as described above.

4 Common Higher Level Base Services

We provide some common higher-level services that are deployed into the container by default.

ContainerRegistryService - This service exposes all services currently available in a local container (JVM), but doesn't allow remote registration.
AdminService - This service is used to stop and ping a running service container.

For a complete list and documentation on all higher level services provided with Globus Toolkit 3 please visit the online download page, or look in the directory <ogsa root>/docs/services.

5 Configuration

This sections described the OGSA extensions to the server-config.wsdd file used by Apache Axis.

Global Options are defined  in the <globalConfiguration> element. The configuration item (in bold) corresponds to the 'name' attribute in a parameter sub element, and the value is put as a 'value' attribute within the same parameter element.:
schemaRoot <url> :  you can use this option if you want the container to read it's schema from a remote server (this can be useful especially for clients so that you don't have to copy around the whole schema directory to the location where you run the client)
containerThreads <number of threads> : sets the number of threads used in the standalone container
<protocol>Port <port> : port used to expose services running a particular protocol, e.g httpPort or httpgPort. In general the port is determined dynamically but in certain cases it must be defined explicitly (e.g. when deploying to Tomcat)
logicalHost <hostname> : hostname to use instead of default local host, can be both FQDN and just hostname
publishHostName <true/false> : if true (case insensitive) the hostname will be published instead of the IP
domainName <domain name> : domain name to append to host name if publishHostName is set and logicalHost is not qualified by a domain
disableDNS <true/false> : if true (case insensitive) no DNS lookups will be attempted and the logicalHost or 'localhost' will be published

Persistent Services Options are defined in a <service> tag
persistent <true/false> : flag indicating whether to treat this service as a persistent grid service, i.e it will be instantiated at container start-up.
schemaPath <path> : path inside of http server where wsdl for the persistent service is defined
sweepDelay <delay in milliseconds> : delay between factory sweeps to destroy timed out service instances
handleProtocol <protocol> : protocol used to publish handles. Note, that if a non default (http is default) protocol is selected, it is recommended to accompany this configuration with a global configuration of <protocol>Port. See above. Only https and http are allowed in the current OGSA specification.
lifecycle <true/false> :  flag indicating whether instances are to be checkpointed into the deployment descriptor to maintain state between server lifecycles

If instance- is prepended to the property name it will configure the instances of the configured service (in case of a factory service) as opposed to the service itself. For a further discussion of configuration variables see the Programmer's Guide or look at the properties defined in org.globus.ogsa.ServiceProperties in the API documentation.

In the case of the standalone container some java System properties can be set to customize where the schemas will be picked up:
-Dorg.globus.ogsa.schema.root : tells the process what remote url can be used to fetch the schemas
-Dorg.globus.ogsa.server.webroot : tells the standalone http server where in the file system the HTTP GET requests should be redirected  (must be absolute path)

6 Logging and Debugging

Overview

Logging in the Globus Toolkit is based on the Jakarta Commons Logging architecture. Commons Logging provides a consistent interface for instrumenting source code while at the same time allowing the user to plug-in a different logging implementation. The Globus Toolkit implements the Commons Logging interface and provides the logging implementation.

In addition the Globus Toolkit provides a logging Grid Service with the following features:

  • Dynamically change the runtime logging characteristics of both the hosting environment and the services running in it.
  • Change the persistent logging configuration.
  • Query or subscribe to a rolling window of the log entries as service data.
  • Query transient and persistent attributes as service data.
  • Access to and management of logging as a Grid Service.

Logging Configuration

Basic logging is automatically configured and enabled during installation. No additional configuration is needed to enable logging. This section is provided so that administrators can change the logging configuration if needed.

This section describes only the static configuration of logging. The OgsiLogging service can be used to dynamically change the logging configuration and options at runtime. This can done using the service interface from a Grid Service client application. A panel is provided as part of the ServiceBrowser as an exmaple. For details see the logging service detailed specification.

The following files are used to configure logging:

  • commons-logging.properties
  • ogsilogging_parms.properties
  • ogsilogging.properties

commons-logging.properties

This file is used by Jakarta Commons to find the LogFactory to use when creating Loggers. It must be in the classpath. This is the entire content: org.apache.commons.logging.LogFactory=org.globus.ogsa.impl.core.logging.OGSALogFactory If the commons-logging.properties file is not found, and assuming a factory was not specified in the system properties, the behavior of commons LogFactory is to dynamically discover built-in supported loggers. If the log4j-core.jar file is found in the classpath, log4j will be used. See the commons Logging LogFactory javadoc for details regarding LogFactory implementation lookup.
 

ogsilogging_parm.properties

This file contains 2 parameters:

1. persistentAttributeLocation contains the name of the file which contains the detailed logging configuration. It can be fully qualified or relative to the current directory. In this example the file is located in the current directory.

persistentAttributeLocation=ogsilogging.properties

2. logDestinationBasePath contains the base path of log files for any logger with a file desination. The default setting is blank, which means the current working directory. In the default Globus Toolkit container, this defaults to the <ogsa root>/impl/java/ directory.

logDestinationBasePath=

ogsilogging.properties

This file contains the detailed logging settings for a Globus Toolkit installation.

There is one and only one default setting, which has the following format:

default=destination,level,group The "default" entry provides logging settings for any logger that is not explicitly defined elsewhere in the ogsilogging.properties file.

In addition to the default entry, there are configuration entries for individual loggers. Individual Logger entries have the following format:

logger_name=destination,level,group

Logger name
logger_name is a string that matches what the log generating application used to define it's logging entries. It is typically the class name of the application generating the log information, but it can be any name that binds a set of contributors to an identified log stream.

Level
The level is the key log-filtering item. There are two views of level: the application view, and the administrative view. From the standpoint of the log generating application, it selects one of the following levels indicating the log message priority:

  • DEBUG
  • TRACE
  • INFO
  • WARN
  • ERROR
  • FATAL
From the administrative view, the level attribute contained in this file is used for the hierarchical filtering of log message flows. Valid level attributes, in hierarchical order are:
  • ALL or DEBUG
  • TRACE
  • INFO
  • WARN
  • ERROR
  • FATAL
  • OFF
The administrator will set a level associated with a logger name from one of the above. The selection of a particular level enables all log filters below it. For example, setting level to ALL or DEBUG causes all messages to be logged. Setting the level to TRACE also causes INFO, WARN, ERROR, FATAL level messages to be logged. Setting level to INFO causes WARN, ERROR, FATAL level messages to be logged, and so on.

Setting level to "OFF" disables all log messages for this logger.

Destination
The destination field is either "CONSOLE" or filename. The filename is relative and will be pre-pended by the logDestinationBasePath.

Group
This is an unmanaged tag, which can be used in group wide operations. An attribute can only belong to one group. Group is useful when programmatically changing the logging settings for a group of loggers.
 

Configuring The Logging Service

The OgsiLogging Grid Service is defined in the server-config.wsdd. Following are the configurable parameters:

logBufferSize defines the number of entries in the log messages buffer. The log message buffer is a rolling (FIFO) list of the latest log messages.

<parameter name="logBufferSize" value="12"/>

logBufferSizeMax defines the maximum size of any change in log buffer size.

<parameter name="logBufferSizeMax" value="1000"/>

Underlying Log Engine

Ogsi Logging uses Log4j in it's implementation. The log4j-core.jar file should be in the classpath.

Any application using log4j directly instead of using commons APIs will NOT be supported from a logging management standpoint. Any discovered log4j.properties file will be in effect for direct users. Commons users will have OGSI Logging Management prevail and existing log4j.properties files will have no effect. For example, if a category logger is defined in log4j as DEBUG but is defaulted by an ogsilogging.properties as WARN, then WARN is the designated log level.

Logging in Tomcat

The deployTomcat target takes care of all the required logging setup in the Tomcat application server environment.

Tracing SOAP messages

Three methods for tracing SOAP messages are described.

1. To trace SOAP messages on the wire you can use TcpMon from Apache Axis. After setting the environment using setenv scripts you can run:

java org.apache.axis.utils.tcpmon [listenPort targetHost targetPort]

If no arguments are used, you have to fill out these values in the GUI.

2. One method for logging SOAP messages is to add the org.globus.ogsa.handlers.MessageLoggingHandler to the request or response chain in the server-config.wsdd or client-config.wsdd files. For example: 

<requestFlow>
  ...
  <handler type="java:org.globus.ogsa.handlers.MessageLoggingHandler"/>
  ...
<requestFlow>

3. Another method for tracing SOAP messages is to enable logging for selected Axis classes. Add the following lines to the ogsilogging.properties file:

org.apache.client.Call=console,debug org.apache.axis.transport.http.HTTPSender=console,debug This will cause axis client side calls and Axis HTTP messages to be logged.

7 Security Support

We support both transport level and message level security based on GSI, and WS-Security. For more details look at a description of the current security support. 

8 .NET Support

The .NET code is only available in the source distribution, and it only supports OGSA clients. It makes use of the exact same WSDL and XML Schemas as the Java implementation for all the samples and core infrastructure components. The wsdl.exe tool is used for proxy generation and the xsd.exe tool is used to compile the XML Schemas into C# types.

In <ogsa root>/impl/dotnet/client there are some experimental .NET SDK Framework clients. When building the clients, WSDL is inspected from a web server pointed to by the OGSA_SERVER environment variable (run setenv.bat to get default value). Type nmake to build the clients, and nmake test to run some tests against a server running an OGSA container.

<ogsa root>/impl/dotnet/client/gui also contains a simple ServiceBrowser developed in Visual Studio .NET. Note, you have to build the client dlls described in the previous step before building the gui.

The Grid Computing Group at the University of Virginia provides GSI extension to our code and a technology preview of an OGSI hosting environment for the .NET platform. Please visit: http://www.cs.virginia.edu/~humphrey/GCG/ogsi.net.html for more details

9 Web Start Support

You can create a Java Web Start enabled proof of concept distribution of ogsa core and samples by doing the following:

1.Using the source distribution compile using the "ant webstart" command.
2. Copy the directory "ogsaweb" to the web server you wish to host the implementation. (if you use our standalone server you can skip this step and go directly to step 4)
3. Ensure the the mime type "application/x-java-jnlp-file jnlp" exists in your target web server configuration (on Apache - /etc/mime.types)
4. Edit the ogsa.jnlp file to include the web server host address and the address where you have deployed the ContainerRegistryService (this is the last host configuration in the file).
5. Edit the bc.jnlp file to include the web server host address.

Before running the container startup script you need to set  -Dorg.globus.ogsa.server.webstart=enable in your OPTIONS shell environment variable (see section 11 command line clients for details).

You should now be able to point your browser at <web server host>/ogsaweb/ogsa.jnlp to start the ServiceBrowser GUI client from a remote machine not configured to use OGSA.. We have tested the web start sample with JDK 1.3.1, and WebStart 1.0.1.

10 EJB Services

We provide a code generator that allows you to expose already existing Enterprise Java Beans, EJBs (both Session Beans and Entity Beans), as Grid services inside of an EJB container in a J2EE Application server. For more details on how to use the code generator see [ejb code gen].
 

11 Command Line Clients

We provide a minimal set of generic command line clients that can be used to test your grid services. The command line clients for core are implemented in the org.globus.ogsa.client package.

To generate the command-line scripts for your target platform, type ant setup. The scripts are generated in the bin/ directory. For a given command-line tool, the corresponding script takes care of setting the classpath and specifying the Java class name. You need to set the GLOBUS_LOCATION variable in your shell. Note for Windows users it may happen that you run out of environment variable character length. If you do you can use the subst command to map the actual GLOBUS_LOCATION to a volume (e.g. subst f: <your globus location>). On Unix/Linux you can use similar workarounds using ln -s, if the problem occurs.

Globus Specific Scripts

globus-start-container
Starts up our standalone hosting environment container

globus-stop-container
Stops our standalone hosting environment container

globus-service-browser
Starts sample service browser gui

Scripts to Perform OGSI Operations

ogsi-create-service
Creates a service and prints out the GSR

ogsi-destroy-service
Destroys a service instance

ogsi-find-service-data-by-name
Searches for Service Data Element values in a service by name.

ogsi-find-service-data-by-xpath
Searches for Service Data Element values in a service using an xpath expression.

ogsi-set-service-data-by-name
Adds Service Data Element values to a service.

ogsi-delete-service-data-by-name
Deletes Service Data Elements in a service..

ogsi-get-gwsdl-port-types
Parses WSDL file and prints out gwsdl port types and contained service data

ogsi-request-termination
Sets a new timeout on a service instance.

ogsi-add-service
Adds a service to a Service Group Registration service supporting remote registration.

ogsi-remove-service
Removes a service from a Service Group Registration service supporting remote registration.

ogsi-resolve-handle
Resolves a handle (GSH) to a reference (GSR)

ogsi-notification-sink
Starts up a standalone notification sink, and logs the handle of the sink that can be used to send it messages. Messages are logged to stdout.

ogsi-notification-sink-notifyer
Sends a test message to a notification sink

ogsi-notification-topic-listener
Starts up a sink and subscribes it to a service data element (topic) in a source service. Messages are logged to stdout.

For detailed help on allowed arguments use the -help option. All clients take a handle to its target service, which it resolves. All services can also be invoked using all the security features described in the security guide.

12 Command Line Script Generation

It is sometimes needed to launch a Java class from the command-line. Bourne Shell and Windows batch scripts can be automatically generated in order to hide from the user the setting of the classpath and the specification of the Java class. An example of this is the generation of the command-line clients provided with the platform.

To provide automatic generation of a client script, write an ant target that calls the generateLauncher ant target in build-client.xml. The following properties/parameters must be specified:

  • ${launcher-name}: base name of script to generate.
  • ${class-name}: name of Java class the script must call.

For instance: 

    <ant antfile="build-client.xml" target="generateLauncher"
         dir="${ogsa.root}">
        <property name="launcher-name" value="myClient"/>
        <property name="class-name" value="org.mypackage.MyClient"/>
    </ant>
It is also possible to specify defaults JVM options and command-line using the ${default.jvm.options} and ${default.cmd.line} ant properties.

13 Setenv Scripts

The setenv scripts can be used to set the proper classpath environment variable in order to launch a Java class from the command-line. To run the setenv script you must first set the GLOBUS_LOCATION environment variable. The GLOBUS_LOCATION should be set to the location of the GT3 distribution. To set the classpath on Windows execute "%GLOBUS_LOCATION%\setenv.bat". On Unix/Linux machines execute ". $GLOBUS_LOCATION/setenv.sh" (for bash/sh) or "source $GLOBUS_LOCATION/setenv.csh" (for csh/tcsh).