----
h1. Creating Custom Web Pages for caGrid Services

When you point a web browser at a caGrid web service, the default response provided by AXIS 1.2 is:
{section}
{column}               
{column}
{column}
{panel:borderWidth=2|borderStyle=solid|bgColor=#F4F4F4}
Hi there, this is an AXIS service!

Perhaps there will be a form for invoking the service here...
{panel}
{column}
{column}                                          
{column}
{section}

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.

h2. Changing the Default Behavior

h3. 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:

{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;
{code}
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:

{code}
/**
* 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.");
}
}
{code}

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.

{code}
/**
* 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;
}
}
{code}

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.

h3. 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
{code}
<servlet-class>org.globus.wsrf.container.AxisServlet</servlet-class>
{code}

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

{code}
<servlet-class>org.cagrid.indexService.IndexAxisServlet</servlet-class>
{code}

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

{code:none}
redirectionURL=http://www.example.org:4321
{code}

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.

h3. 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:

{code:xml}
<!-- ============================================================== -->
<!-- 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>
{code}

Here is the content of *deploy-redirect.xml*:

{code: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>
{code}