Java Portlet Tools: Converting Java Web Applications into Adaptive Portlets
Pages: 1, 2, 3, 4, 5

Appendix C: Frequently Asked Questions

  1. I just want my Java webapp to work as a portlet. Do I need to use all the Java Portlet Tools functionality?
  2. I don't want to filter all of my pages. I have some pages that pop up in separate windows. What do I do?
  3. Which Web application framework should I use with Java Portlet Tools?
  4. Will running my Web application through the PTPortletFilter prevent me from testing it outside the Plumtree portal?
  5. How do I access the PortletBean object in my JSP?
  6. Why are my expression language statements using the PortletBean not getting translated?
  7. When should I use a tag, scriptlet, or expression language statement when trying to do something with the PortletBean?
  8. Why should I use the <portlet:onEvent> tag instead of just writing and registering my own PCC event handler?
  9. How do I install Java Portlet Tools?
  10. Why am I getting JavaScript errors when I click a button or link?
  11. Are there any examples I can look at?

I just want my Java webapp to work as a portlet. Do I need to use all the Java Portlet Tools functionality?

No, you don't. Depending on how simple your webapp is, you may not even need to use the Java Portlet Tools at all. The PTPortletFilter is most useful when filtering Web application frameworks like Struts and JSF, which have trouble functioning as portlets without it. If a portlet requires form submission or complex navigation, you may want use the filter. The rest of the features in Java Portlet Tools, the PortletBean, tags, and adaptive portlets technology, are there only to help developers utilize much of the cool features of adaptive portlets.

I don't want to filter all of my pages. I have some pages that pop up in separate windows. What do I do?

The Java Filter definition in the web.xml file allows you to specify a path pattern that the PTPortletFilter will operate on. For example, if you only wanted to filter JSPs, you could specify a "*.jsp" path pattern to filter. Any pages you don't want filtered should not match this path pattern.

Which Web application framework should I use with Java Portlet Tools?

The short answer is any or none. Although Java Portlet Tools was tested on JSF and Struts applications, in theory any Java Web application will be converted to a portlet application with in-place refresh, provided that navigation is performed by hypertext links or form posts.

Will running my Web application through the PTPortletFilter prevent me from testing it outside the Plumtree portal?

No. Java Portlet Tools is designed so that its tags, beans, and servlet filters all disengage when a HTTP request is not being gatewayed. This is not to say that the Web application will look exactly as it does in the portal; image server references will break, PCC events will not fire, and other portal specific functionality will not work. However, simple navigation and form submission should function as it does when the application is run as a portlet.

How do I access the PortletBean object in my JSP?

The PortletBean is attached as an attribute to every HttpServletRequest object that passes through the PTPortletFilter or handles a JSP page using the <portlet:adaptivePortlet> tag. The bean is attached using the attribute name "portlet". Depending on the Web application framework you are using, and the manner in which you are using it, there are several ways of accessing the PortletBean. For JSF applications, the PortletBean is always present in expression language statements as an Object called "portlet".

<h:graphicImage url="#{portlet.imageServerURI}/plumtree/common/img/help.gif"/>

Other frameworks may require you to declare the bean first before accessing it.

<jsp:useBean name="portlet" scope="request" class="com.plumtree.remote.filter.bean.PortletBean"/>
<html:image src="${portlet.imageServerURI}/plumtree/common/img/help.gif"/>

Finally, if the bean is used in scriptlets you can use a static helper method in PTPortletFilter to retrieve it from the HttpServletRequest.

<%
    PortletBean portlet = PTPortletFilter.getPortlet(request);
%>
<img src="<%= portlet.getImageServerURI() %>/plumtree/common/img/help.gif">

Why are my expression language statements using the PortletBean not getting translated?

You may be using a JSP implementation that is using an older version of the JSP specification. Only JSP 2.0 supports the expression language. Another possibility is that your expression language syntax is incorrect. Please read the J2EE Tutorial for more information on using the JSP expression language.

When should I use a tag, scriptlet, or expression language statement when trying to do something with the PortletBean?

Expression language statements are most effective in attribute values of custom tags. If your JSP implementation does not support the expression language, then you can use the portlet bean in a scriptlet for custom tags. Alternately, if you don't want to use scriptlets, you can insert a custom tag into a regular HTML tag as an attribute value. Different Web application frameworks require different usage of the PortletBean. For example, JSF makes heavy use of the expression language, and therefore it is recommended that developers use the PortletBean from within expression language statements. Other frameworks are less structured, and developers may want to rely on custom tags or scriptlets.

Why should I use the <portlet:onEvent> tag instead of just writing and registering my own PCC event handler?

The use of in-place refresh to navigate back and forth in a portlet application can cause a bug where a PCC event handler can be registered multiple times. When this occurs the same handler will fire more than once for a single event, and this can cause bugs in the portlet application. The <portlet:onEvent>, <portlet:refreshOnEvent>, <portlet:formRefreshOnEvent>, and <portlet:clickOnEvent> tags track registrations and prevent multiple registrations from occurring. This bug will be fixed in all future versions of the portal.

How do I install Java Portlet Tools?

Read the installation guide.

Why am getting JavaScript errors when I click a button or link?

You may not be using the correct version of JSXML to perform in-place refresh. Read the installation guide for details on how to install JSXML on the portal imageserver for use by Java Portlet Tools.

Are there any examples I can look at?

The Java Portlet Tools distribution comes with a sample JSF appliction war file. This is a demonstration application provided by Sun that was converted to a portlet application by adding the Java Portlet Tools jars to the Web archive and adding the PTPortletFilter declaration to the web.xml. This application was tested on Tomcat 5.0.28.

Andrew Lorek is a Senior Software Engineer in BEA's AquaLogic Interaction division. He has worked on user-interface frameworks and controls for a variety of ALUI products, and is currently working on the OpenControls project developing AJAX-enabled UI controls for JSF and ASP.NET.