drew | 07/04/07

Today I wrapped up some work I had been preparing for the uPortal 2.6 release: a new Portlet Application deployment tool. Readers who attended my talk at the JA-SIG conference in Denver last week on Cernunnos may recognize it. It works just like the old deployment tool except it clears up a few issues -- some documented, some not.

One issue that is documented -- in the JA-SIG JIRA tool -- is UP-1241. This issue states that uPortal 2.6.0 RC2 and previous cannot properly support portlets that use JSTL 1.1 and describes the cause of this discrepancy. In a nutshell, JSTL 1.1 requires version 2.4 of the Java Servlet Specification, but the portlet deployment tool was hard-coding the following DOCTYPE declaration and <web-app> element in each of the web.xml files it would create:


<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
                            "http://java.sun.com/dtd/web-app_2_3.dtd">
<web-app>

[...]

</web-app>

There was no way to reference Java Servlet 2.4 effectively because the deployment tool overwrites your web.xml file, specifying version 2.3 every time.

Adjusting web.xml files in portlet applications is the most significant work performed by the deployment tool, and it does it for very good reasons. The Pluto portlet container, which uPortal leverages for its portlet support, requires some configured J2EE components over-and-above what the Java Portlet Specification outlines.

Here is a list of what the portlet deployment tools -- both old and new -- contribute to the web.xml in a portlet application:

  1. A <servlet> element for each portlet definition in portlet.xml
  2. A <servlet-mapping> element for each servlet defined in step #1
  3. A <taglib> element referencing the JSP tag library for portlets

Both tools create these elements, but they differ significantly in how they treat the existing web.xml. Whereas the new tool adds these elements to the web.xml provided by the portlet application, the old tool creates an entirely new web.xml document and attempts to "pull forward" any meaningful elements that were present in the original document. But the old tool only transfers content it's been specifically told to transfer; some things were left off the list.

The UP-1241 issue (described above) is a particularly painful symptom of this problem. No attributes from the DOCTYPE declaration or the <web-app> element are read forward into the new web.xml, and the result is that support for Java Servlets 2.4 is removed from portlet applications that include it.

There are other issues stemming from this difference, though none that cause problems of this magnitude that I'm aware of. For example, the old deployment tool creates a <description> element that applies to the whole application from the XPath expression //description. This tactic works as intended as long as the original web.xml contains an element at /web-app/description. If not, than the text of the <description> element for the first servlet definition that contains one will be taken as a description for the entire application.

This change in tactic is the primary reason for adopting a new deployment tool instead of simply trying to fix the known issues in the existing one. It's attractive to suppose that the web.xml document provided by the portlet application knows its own business, and the only details that the deployment tool needs to keep track of are the additional definitions required by Pluto. But, as often happens, this shift in approach partly just exchanges one set of problems for another.

Certainly a number of corner cases and unexpected inputs came to light quickly as I worked to integrate the solution with the existing uPortal 2.6 codebase. Out-of-the-box, uPortal comes with five sample portlet applications that deploy when the initportal Ant task is invoked. Just within these five, I discovered that one doesn't include a web.xml file at all, and another one already has the Pluto servlet mappings in its web.xml. I had to swell up the new deployment tool with specific instructions that apply to these cases. The old deployment tool handles both of these irregularities in a more straightforward way.

Nevertheless on the whole I believe the shift in tactic is appropriate, and I expect that the new tool is a step in the right direction. Before I contributed the new tool, I tested it with an extensive battery of pre-packaged portlet applications, including some that were known to fail under the old tool.

I'll be watching the uportal-dev list attentively for any reaction.