Using the WebSphere plug-in with mod_alias and mod_rewrite

There are essentially 3 classes of operations one can perform with respect to changing requests and plug-in processing.
  1. Alter a request which would not be handled by the plug-in such that it will be handled by the plug-in
  2. Alter a request which would be handled by the plug-in such that it will not be handled by the plug-in
  3. Alter a request such that the URI passed to the plug-in is transformed

The recommended method for performing these tasks is with mod_rewrite. Use of the Alias directive is ineffective in all three cases.


Examples

In the following examples, the WebSphere plug-in is configured to only handle requests of the form *.do.

Note that the RewriteRule directives are kept as simple as possible, but in practice can contain regular expressions and backreferences to alter an entire class of URIs.

Alter a request which would not be handled by the plug-in such that it will be handled by the plug-in

For some unknown reason, the HTML link to a WebSphere resource doesn't include the *.do, so we need to alter the URI to include so the plug-in will recognize and handle the request.

WebSphere ResourceLink in HTML
/servlet/members/ProjectA/V3/SignIn.do /ProjectA/SignIn

The link as written won't be recognized by the WebSphere plug-in, and consequently has no hope of getting passed to WebSphere Application Server, so we add the following configuration:

 
RewriteEngine on
RewriteRule /ProjectA/SignIn /servlet/members/ProjectA/V3/SignIn.do [PT]

The PT flag is required, as this is what lets the WebSphere plug-in observe the results of the mod_rewrite processing.
The Alias directive isn't effective here, because that only maps a URI to a filename on the IHS system and doesn't change the URI in the request. If it was used, IHS would be trying to find /servlet/members/ProjectA/V3/SignIn.do under the Document Root.

Alter a request which would be handled by the plug-in such that it will not be handled by the plug-in

Consider a resource in the filesystem that matches the *.do pattern, but should be served as a static file. Because it's a URI already known to the outside world, he has to make some provision to ensure it's not passed to WebSphere.

Filesystem ResourceLink in HTML
htdocs/scooby_do.jpg /scooby.do

This link as written will be recognized by the WebSphere plug-in and passed to WebSphere Application Server, so we add the following directives to the IHS configuration to make sure it's served out of the filesystem:

 
RewriteEngine on
RewriteRule /scooby.do scooby_do.jpg [PT]

The PT flag is required, as this is what lets the WebSphere plug-in observe the results of the mod_rewrite processing.
The Alias directive is not effective here, because that only maps a URI to a filename on the IHS system and doesn't change the URI in the request.
During request processing, the plug-in will have no interest in the new URI of scooby_do.jpg. The Redirect directive would be effective here, which is somewhat slower but updates the users browser with the proper URI

Redirect /scooby.do /scooby_do.jpg

Alter a request such that the URI passed to the plug-in is transformed

Many users are receiving 404 errors from typographical errors on the same WebSphere resource, so we provide a mapping between the erroneous name and the actual name.

WebSphere ResourceTypo
/servlet/already.do /servlet/allready.do

We change the URI that will be seen by the WebSphere plug-in as follows:

 
RewriteEngine on
RewriteRule /servlet/allready.do /servlet/already.do [PT]

The PT flag is required, as this is what lets the WebSphere plug-in observe the results of the mod_rewrite processing.
The Alias directive is not effective here, because that only maps a URI to a filename on the IHS system and doesn't change the URI in the request. This would cause the WebSphere plug-in to handle the request but still operate on the original URI.
The Redirect directive would be effective here, which is somewhat slower but updates the users browser with the proper URI

Redirect /servlet/allready.do /servlet/already.do


Configuration Issues

Module Loading/Ordering

See this document on module ordering for instruction on how to be sure that mod_rewrite (or mod_alias for Redirects) has precedence over the WebSphere Plug-in.

Historical Issues

2.0 Alias directive causes plug-in to decline handling request

In WebSphere Plug-in versions prior to 5.0.2.6 / 5.1.0.4, the existence of an Alias for a URI would disable plug-in processing regardless of whether or not the result of the Alias matched or did not match a pattern in plugin-cfg.xml.

There may be some configurations which exploit this behavior to serve things such as images out of the filesystem instead of from WebSphere using an Alias directive -- upgraders will find they must replace this Alias directive with an equivalent RewriteRule directive.

Incorrect: Alias /servlet/images/ /images/
Correct  : RewriteRule /servlet/images/(.*) /images/$1 [PT]

1.3 Plugin crashes if mod_alias has higher priority then plug-in

Between versions 5.1.1 and 5.1.1.6 (inclusive) of the WebSphere plug-in for IHS 1.3, a crash can be encountered if mod_alias is higher priority then the plug-in and an Alias directive operates on a URI that will be handled by the plug-in.