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'.
Secondary Dependencies:
wsdl4j, commons-logging, commons-discovery, jaxrpc, saaj,
distributed by Apache Axis
PureTLS, BouncyCastle, log4j, cryptix distributed by Java CoG Kit
<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.
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.
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.
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.
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.
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)
In addition the Globus Toolkit provides a logging Grid Service with the following features:
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:
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.
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.
There is one and only one default setting, which has the following format:
In addition to the default entry, there are configuration entries for individual loggers. Individual Logger entries have the following format:
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:
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.
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.
logBufferSizeMax defines the maximum size of any change in log buffer size.
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.
The deployTomcat target takes care of all the required logging setup in the Tomcat application server environment.
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:
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:
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.
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
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.
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-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
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.
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:
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.