Java Portlet Tools: Converting Java Web Applications into Adaptive Portlets

by Andrew Lorek


This article show how to convert existing Web applications designed to work outside a portal into adaptive portlets for use within AquaLogic User Interaction. It outlines the difficulties encountered when using existing Web application frameworks like Java Server Faces or Struts as well as a new tool to overcome these problems, the Java Portlet Toolkit. The article will also explore some of the tools that come with the Java Portlet Toolkit such as the PortletBean and portal-specific JSP tags.

Introduction: Java Web Applications vs. Java Portlet Applications

Since the advent of the Java servlets and Java Server Pages (JSP) specifications there have been several attempts to make Java Web applications easier to write, configure, and customize. Most often applications have followed the "Model 2" architecture whereby requests are routed to various JSP pages by a controlling servlet, displaying and modifying data in JavaBeans attached to servlet requests and sessions. This architecture follows the Smalltalk "Model-View-Controller" design pattern and drastically simplifies development of Web applications in Java. Several Web application frameworks, such as Struts and Java Server Faces, have been created to even further simplify Web application development by allowing developers to configure request routing, JavaBean management, validation, and other common Web application tasks as part of the framework, rather than hard-coding such functionality into the JSPs or Java classes.

Frameworks such as Struts and JSF are well suited to stand-alone Web applications in that they perform much of the work of request processing, validation, and navigation, leaving developers free to define the business logic required for the application. Unfortunately they are often structurally unsuited for use in portal applications due to their reliance on form posts and redirection to manage application navigation. In addition, most frameworks are difficult to convert to multi-portlet environments, where more than one instance of the same Web application may be visible on a page as a portlet, because they have no facility for uniquely identifying page elements beyond the scope of a single Web application.

Ideally, there would be a way to convert a Struts, JSF, or any JSP/servlet application so that it can be used both in a portlet and as a stand-alone Web application, without any change to the application code or configuration files. Fortunately, the development release of the Plumtree Java Portlet Tools library allows developers to do just that. In addition, the library provides JavaBean wrappers for EDK functionality. The EDK is a set of utility libraries that allow developers to access portlet information encoded in request headers as well as perform remote service tasks such as accessing data from portal applications such as Collaboration and Search. The Java Portlet Toolkit EDK wrapper beans allow developers to use the JSP 2.0 Expression Language to get and set portlet properties, settings, and preferences. Finally, a suite of custom tags is included that provides simplified access to adaptive portlets technology such as in-place-refresh and PCC event handling, allowing developers to perform complex DHTML operations without writing any JavaScript.

Readers of this article should be comfortable with Java, Java servlets, JSPs, and JSP tag library technologies. Developers wanting to convert a simple Java application into an adaptive portlet can read just the section Servlet Filters and the PTPortletFilter and skip the other sections, which discuss additional features that are packaged in the Java Portlet Tools library. Developers wanting to make full use of adaptive portlet technologies should read the entire article.

Servlet Filters and the PTPortletFilter

The Java Servlet 2.3 specification includes a new class called Filter. Filters are configured in the web.xml file of a Java servlet application and can intercept and modify servlet requests and responses both before and after they are sent to JSPs and servlet classes. Java Portlet Tools provides a special Servlet Filter, called the PTPortletFilter, that intercepts the HTML sent from a Web application and rewrites it so that it can be included in a Plumtree portlet. This rewriting will perform the following types of actions:

The PTPortletFilter is declared by adding the following XML to the Web application's web.xml configuration file:


  <filter-name>Adaptive Portlet Filter</filter-name>
























  <filter-name>Adaptive Portlet Filter</filter-name>



All the filter initialization parameters are optional, and if you do not want to perform any filter logging or custom operations, you can probably get away with just adding the filter class and URL mapping. For more complex portal configurations you may need to add alternate imageserver or logging initialization parameters. The initialization parameters recognized by PTPortletFilter are described below:

Parameter Description Default
filter.config.file Points to an XML file that defines a tree of nested operations that the PTPortletFilter can perform on the Web application's response HTML. The Java Portlet Tools filter provides a sample filter.xml file that has been tested for JSF applications. This sample file should work for most Java Web application frameworks; however it is configurable and allows developers to add new HTML rewriting operations should they be necessary. Instructions on how to customize this XML file are described in further detail in Appendix A: PTPortletFilter Configuration XML. This parameter should only be specified if custom filter operations are performed. The default filter.xml file contained in portlet-tools.jar.
filter.log.file This parameter specifies the absolute path to a file to which the filter will write logging information. stdout
filter.log.level The level of logging performed by the filter. Possible values are: debug, info, warning, severe, error, and off. warning
jsxml.version The version of the Plumtree JSXML JavaScript component that makes in-place-refresh possible in the Plumtree Portal. This value refers to the preferred version of the JSXML JavaScript library that the Web application will be using. JSXML is the AJAX framework underlying the G6 Scripting Framework. the latest version of JSXML
portal.imageserver.alternate Allows developers to use the specified URL to connect to the image server when including the JSXML JavaScript component. This is required if the portal's image server has security restrictions preventing the Web application from accessing it directly.
content.type Sets the content type of the HTTP response text/html;charset=UTF-8
character.encoding Sets the character set used in the HTTP response. UTF-8

For an example of how the PTPortletFilter rewrites the response HTML, look at a simple submit button in a form:

<form id="myform" action="next.jsp">

  <input type="submit" name="action" value="Submit"

                      onchange="alert('Saving info...')">



Left unchanged, this button would cause the entire page of a portal to submit and would return content only for the portlet whose button was clicked, effectively causing the portlet to take over all the content for a portal page. Instead, the PTPortletFilter rewrites the tag to use in-place refresh:

<form id="myform_203"


  <input type="button" name="action" value="Submit"

    onchange="alert('Saving info...');






Hypertext links that point to Web application resources (and are targeted to refresh the current page) will be rewritten so that they perform in-place refresh requests. For example, of the following links:

<a href="next.jsp">Link in this window</a>

<a href="next.jsp" target="new">Link in another window</a>

<a href="">Link to another site</a>

only the first link can cause problems for the portal. Like the form example above, clicking this link will cause the portlet to take over the content of the entire portal page. Only this link is rewritten to perform an in-place refresh request.

<a onclick="linkback_203('http://host/portal/',

             document.getElementById('pt-portlet-java-203'); return false;"

   href="#">Link in this window</a>

<a href="http://host/portal/"

    target="new">Link in another window</a>

<a href="">Link to another site</a>

Finally, any JavaScript that programmatically submits a form in the Web application is rewritten to perform an in-place refresh. Any JavaScript that references a form is rewritten to reference the form by its unique ID with the appended portlet ID.

The PTPortletFilter will be disabled when a Web application is viewed as a solitary Web application rather than as a remote Web service viewed in a portlet. If a page in the Web application is run through the portal's gateway and displayed inside a portlet, the PTPortletFilter will display the Web application's HTML content without any modification.

Pages: 1, 2, 3, 4, 5

Next Page »