Creating Custom Web Pages for caGrid Services


	Contents Overview Changing the Default Behavior Subclassing the AXIS Servlet Installing and Configuring the Custom Servlet Class Writing an Ant Task for Deployment

Overview

When you point a web browser at a caGrid web service, the default response provided by AXIS 1.2 is:

Hi there, this is an AXIS service!

Perhaps there will be a form for invoking the service here...

Overriding this behavior to actually provide the suggested form can be complicated. However overriding this in a way that either changes the message or redirects the browser to a different URL is relatively simple. The rest of this page is a description of how to change the message or redirect the browser.

Changing the Default Behavior

Subclassing the AXIS Servlet

By default caGrid services use the AXIS servlet class org.globus.wsrf.container.AxisServlet. When an instance of this servlet class receives an http GET from your browser, it calls its reportServiceInfo method which generates the "Hi there,..." response. The reportServiceInfo method has protected scope, so you can override it to have different behavior. The details of how to do this are presented below through an example.

In this example, we will create a subclass of org.globus.wsrf.container.AxisServlet whose reportServiceInfo method redirects the browser to a URL that is configured in a properties file. If it cannot get the URL from the properties file, it will send a message to the browser telling the user that the redirection is misconfigured.

We name the subclass org.cagrid.indexService.IndexAxisServlet. Here is the beginning of its source code:

package org.cagrid.indexService;

import java.io.BufferedInputStream;
import java.io.File;
import java.io.FileInputStream;
import java.io.IOException;
import java.io.InputStream;
import java.io.PrintWriter;
import java.util.Properties;

import javax.servlet.http.HttpServletResponse;

import org.apache.axis.handlers.soap.SOAPService;
import org.globus.wsrf.config.ContainerConfig;
import org.globus.wsrf.container.AxisServlet;

All but the last group of imports are from the standard Java API:

org.apache.axis.handlers.soap.SOAPService
is needed to declare one of the arguments for the reportServiceInfo method. We will not need to make any other use of it.

org.globus.wsrf.config.ContainerConfig
is a class used to describe the configuration of wsrf, the layer of software that sits between the web container (tomcat, JBoss, ...) and the grid service.

org.globus.wsrf.container.AxisServlet
is the class we are subclassing.

Here is the actual override of the reportServiceInfo method:

/**
 * Override the usual servlet class to redirect GETs.
 * 
 * @author mgrand
 */
public class IndexAxisServlet extends AxisServlet {
  /**
   * Hash code for serialization
   */
  private static final long serialVersionUID = 2084415505816625308L;
  private static Properties redirectionProperties = null;
 
  @Override
  protected void reportServiceInfo(HttpServletResponse response,
                                   PrintWriter writer,
                                   SOAPService service,
                                   String serviceName) {
    try {
      Properties properties = getRedirectionProperties();
      String redirectionURL = properties.getProperty("redirectionURL");
      if (redirectionURL == null) {
	throw new IOException();
      }
      response.sendRedirect(redirectionURL);
    } catch (IOException e) {
      // There should be some logging here
      writer.write("Redirection is enabled, but not properly configured.");
    }
  }

The above code gets a URL to redirect the browser to from a Properties object and then calls response.sendRedirect to send the redirection to the browser. If there is an error in getting thr URL or sending the redirection, the fallback strategy is to write some explanatory text to the browser.

The rest of the IndexAxisServlet appears below.

  /**
   * Get the properties object for the configuration of the redirection.
   * 
   * @return the properties object
   * @throws IOException
   *             if there is a problem.
   */
  private Properties getRedirectionProperties() throws IOException {
    synchronized (this.getClass()) {
      if (redirectionProperties == null) {
        String baseDirectoryPath = ContainerConfig.getBaseDirectory();
        File etcDirectory = new File(baseDirectoryPath, "etc");
        File redirectionPropertiesFile = new File(etcDirectory,
                                                  "redirection.properties");
        FileInputStream fis = new FileInputStream(redirectionPropertiesFile);
        InputStream inStream = new BufferedInputStream(fis);
        try {
          redirectionProperties = new Properties();
          redirectionProperties.load(inStream);
        } finally {
          inStream.close();
        }
      }
    }
    return redirectionProperties;
  }
}

The getRedirectionProperties method in the above code returns a Properties object that is loaded with the contents of the file redirection.properties in the deployed service's WEB-INF/etc directory. The location of this and other configuration details are described in the next section of this page.

Installing and Configuring the Custom Servlet Class

Under the previous section of this page, we described how to write a class that will override a grid service's default "Hi there..." behavior. In this section, we describe what need to be done to install the class into a grid service. In the next section we show how to automate that installation steps as an ant script.

There are three things that the installation needs accomplish:

Put the new class where it will be on the grid service's class path.
Arrange for the new class to be used in place of the usual servlet class.
Put the redirection.properties file where the new class expects to find it.

All of the installation steps involve files that are or will be under a particular directory in the gird service's container. We will refer to this directory as DEPLOY_DIR.

If you are using tomcat, then DEPLOY_DIR is $CATALINA_HOME/webapps/wsrf/WEB-INF.
If you are using JBoss, then DEPLOY_DIR is $JBOSS_HOME/server/default/deploy/WEB-INF.

To put the new class on the service's class path, we copy it to a directory that is based on the name of the package it belongs to. If the new class belongs to a package named org.cagrid.indexService then copy it to DEPLOY_DIR/classes/org/cagrid/indexService

To arrange for the new class to be used in place of the usual servlet class, edit the file DEPLOY_DIR/web.xml. It contains an xml element that looks like

    <servlet-class>org.globus.wsrf.container.AxisServlet</servlet-class>

This xml element identifies the servlet class to be used for the web service. If the fully qualified name of the new class is org.cagrid.indexService.IndexAxisServlet, then we need to change the xml element to look like

    <servlet-class>org.cagrid.indexService.IndexAxisServlet</servlet-class>

We need to create a redirection.properties file that contains a redirectionURL property whose value is the URL to redirect to. This would look like

redirectionURL=http://www.example.org:4321

We then copy this properties file to DEPLOY_DIR/etc/redirection.properties

When all of these things are done, the new custom servlet class is installed and configured.

It is strongly recommended that you create an ant script to automate these steps. An ant script to perform this automation is described in the next section of this page.

Writing an Ant Task for Deployment

In this section of this page we present a self-contained ant script that is called from your main ant script to install and configure a customized servlet class for redirection of browsers.

We assume that your grid service has the standard ant xml files generated by introduce. We also assume that deploy-redirect.xml is the name of the new self-contained script that installs and configures the redirection.

Before we look at at contents of redirection.properties, we take a look at the changes you should make to the dev-build-deploy.xml to integrate it with deploy-redirect.xml.

Add tasks like the ones shown to the preDeployTomcat and preDeployJBoss targets:

  <!-- ============================================================== -->
  <!-- Pre Deploy JBoss                                              -->
  <!-- ============================================================== -->
  <target name="preDeployJBoss">
    <fail unless="env.JBOSS_HOME" >
      Cannot deploy to JBOSS unless environment variable JBOSS_HOME is defined
    </fail>
    <ant antfile="${basedir}/deploy-redirect.xml" target="deployRedirect">
      <property name="deploy.dir"
                value="${env.JBOSS_HOME}/server/default/deploy/wsrf.war/WEB-INF"/>
    </ant>
  </target> 

  <!-- ============================================================== -->
  <!-- Pre Deploy Tomcat                                              -->
  <!-- ============================================================== -->
  <target name="preDeployTomcat">
    <fail unless="env.CATALINA_HOME">
      Cannot deploy to tomcat unless environment variable CATALINA_HOME is defined
    </fail>
    <ant antfile="${basedir}/deploy-redirect.xml" target="deployRedirect">
      <property name="deploy.dir" value="${env.CATALINA_HOME}/webapps/wsrf/WEB-INF"/>
    </ant>
  </target>

Here is the content of deploy-redirect.xml:

<?xml version="1.0"?>
<project name="deploy-utilities file" basedir="." default="deployRedirect">
  <fail unless="deploy.dir"
        message="This ant script is supposed to be called from build.xml"/>
	
  <taskdef name="xmltask"
           classname="com.oopsconsultancy.xmltask.ant.XmlTask"
           classpath="${basedir}/ant/xmltask.jar" />

  <!-- ================================= 
       target: deployRedirect              
       ================================= -->
  <target name="deployRedirect" 
          description="Deploy code to handle redirection to the monitoring service">
    <property name="class.dir" location="${deploy.dir}/classes"/>
    <property name="indexService.dir"
              location="${class.dir}/org/cagrid/indexService"/>
    <property name="etc.dir" location="${deploy.dir}/etc"/>

    <property name="web.xml" location="${deploy.dir}/web.xml"/>
    <property name="web.xml.original" location="${web.xml}.original"/>

    <property name="redirection.properties.dest"
              location="${etc.dir}/redirection.properties"/>
    <property name="redirection.properties.src"
              location="${basedir}/redirection.properties/" />
    
    <!-- Verify that the redirection properties file exists
         and defines the required property -->
    <available property="redirection.properties.exists"
               file="${redirection.properties.src}" type="file" />
    <fail unless="redirection.properties.exists">
      Redirection properties file does not exist.
      Please create ${redirection.properties.src}
    </fail>
    <property file="${redirection.properties.src}" prefix="xxyyzz321"/>
    <fail unless="xxyyzz321.redirectionURL" >
      Property file ${redirection.properties.src} must 
      define a property named redirectionURL whose value 
      is the URL that GET request should be redirected to.
    </fail>
    	
    <!-- copy the class file for redirection to the container -->
    <mkdir dir="${indexService.dir}" />
    <copy file="${build.dest}/org/cagrid/indexService/IndexAxisServlet.class"
          todir="${indexService.dir}" />
    	
    <!-- copy the redirection configuration file -->
    <copy file="${redirection.properties.src}"
          tofile="${redirection.properties.dest}"/>
    	
    <!-- Edit wsrf web.xml to use the redirecting version of the servlet class -->
    <copy file="${web.xml}" tofile="${web.xml.original}" overwrite="no"/>
    <xmltask source="${web.xml.original}"
             dest="${web.xml}" failwithoutmatch="true" indent="yes">
      <replace path="/web-app/servlet/servlet-class/text()"
               withText="org.cagrid.indexService.IndexAxisServlet" />
    </xmltask>
  </target>
</project>