JBoss.orgCommunity Documentation

JBoss Portlet Container

User Guide

Release 2.0


1. Introduction
1.1. Motivation
1.2. Audience
1.3. Simple Portal: showcasing JBoss Portlet Container
1.4. Resources
2. Installation
2.1. Downloading and installing
2.1.1. JBoss AS 4.2.x bundle
2.1.2. Tomcat 6.0.x bundle
2.2. Testing Portal Container's demonstration portal
3. Simple Portal
3.1. Motivation
3.2. Development
3.2.1. Portlet deployment
3.2.2. Simple Portal tag library
3.2.3. Extended tag library
3.3. Portlet debugging
3.4. Administration
3.4.1. Admin portlet
3.4.2. Logging configuration

Two bundled versions are provided to showcase Gatein Portlet Container in action with minimum effort. Theses bundles each include a servlet container configured with the Simple Portal demonstration portal along with some JSR-286 compliant portlets. You will need to have Java 5 configured on your machine to run the demonstration portal. You can download Java 5 at http://java.sun.com/javase/downloads/index_jdk5.jsp. Once you have Java installed, you are ready to download one of GateIn Portlet Container bundles. The following link has the list of downloads for Gatein Portlet Container: http://labs.jboss.com/portal/portletcontainer/download. Two bundles are currently provided: one with Tomcat 6.0 one with JBoss Application Server 4.2 and one with JBoss Application Server 5.1.

Once the servlet container is started, bring up your web browser and go to the following URL: http://localhost:8080/simple-portal. You should see the default page for Portlet Container's demonstration portal:

Default page for Portlet Container's demonstration portal.

Simple Portal relies on the JSP technology to build pages for several good reasons:

<page>If you need more advanced page creation capabilities, you should consider using a more advanced portal product such as JBoss Portal. </page>

Any JSP page can contain portlets, the only requirement to make this possible is to have the page located in Simple Portal's WAR file and to use the portal tag library.

Let's look at a minimal portal page using the portal tag library:


The portal tag library declaration enables the JSP compiler to know about the existence of the simple portal. It is declared by the JSP declaration <%@ taglib uri="/WEB-INF/portal.tld" prefix="portal" %> and it binds the portal tag library to the portal namespace.

The interesting part of the markup is the portal:page element and its children. The page tag defines a logical scope that is used by Simple Portal to generate markup:

  • It defines a container for a set of portlets.
  • It defines the page area that will be replaced entirely by a maximized portlet markup (when the maximized window state is requested).
  • It defines a scope for the coordination features.

Currently, only one portal page can be specified per JSP file but this should be extended to several portal pages per JSP file in future versions of JBoss Portlet Container.

Access to portlet information within a portal page is done by defining a reference to the portlet using the portlet tag. The mandatory attributes for this tag are name and applicationName that are used to locate the deployed portlet. The applicationName refers to the name of the WAR file containing your portlet application without the extension .war and the name attribute refers to the portlet name as declared by the portlet-name element in the portlet.xml file of your portlet application WAR file. Similarly to the page tag, the portlet tag does not produce any markup but rather makes your portlet available to Simple Portal.

The portlet markup is output using the portletmarkup tag. This tag is replaced by the referenced portlet markup (without any decoration) when the page is rendered.

Errors can be handled either during page rendering or when a portlet is interacted with. Simple Portal categorizes errors and associates each error type with a category name (string) that can be used to for programatic handling. The error categories are as follows:


Simple Portal can display the content of an alternative page if, for some reason, a portlet fails during the render phase. This is similar to JSP error pages.

Several request attributes are set by Simple Portal so that the markup of the error page can be customized appropriately. The following table sums up these request attributes and their meaning.


The errorPage attribute of the portlet tag is used to specify which error page to use for this specific portlet. The value of the attribute should be the path to the error page relative to the root of the WAR file for that portlet. Note that it could be a JSP or a plain file.


If a a failure occurs during an interaction with a portlet, Simple Portal will throw a servlet exception with a message set to one of the category names as specified in Table 3.1, “Error Categories”

The default error handling strategy is handled by a servlet filter that catches error messages and translates them into HTTP errors. This filter is called <className>ErrorHandlingFilter</className> and is declared in the web.xml file of Simple Portal WAR file. This allows developers to change the error handling behavior if desired.


The Portlet 2.0 specification provides a new eventing feature for coordinating several portlets. This long awaited feature is very powerful but can sometime lead to complex scenarios when multiple events are consumed and fired by multiple portlets on the same page.

The simple portal provides a visual debugger that can be used to understand what happens during the event phase orchestrated by the portal. It comes as a portlet that you can place on any page and it shows a tree of events that were produced and consumed during the event phase.

The event debugger displays a tree of events produced and consumed by portlets. The nodes of the tree don't represent events, they rather represent event routings from a source portlet to a destination portlet. By default it shows the name of the portlet that published the event, the event name and the destination of the event that was chosen by the simple portal during the event distribution phase. Hovering the mouse on a node shows more information.

When hovering the mouse on a node you can see the optional event payload represented by the string returned when invoked its toString() method and the state of the portlet after the event phase. The state of the portlet consist in its portlet mode, its window state and the set of its render parameters. Adding the event debugger to a page is easy.