Introducing the Portlet Specification, Part 1

Get your feet wet with the specification's underlying terms and concepts

With the emergence of an increasing number of enterprise portals, various vendors have created different APIs for portal components, called portlets. This variety of incompatible interfaces generates problems for application providers, portal customers, and portal server vendors. To overcome these problems, JSR (Java Specification Request) 168, the Portlet Specification, was started to provide interoperability between portlets and portals.

JSR 168 defines portlets as Java-based Web components, managed by a portlet container, that process requests and generate dynamic content. Portals use portlets as pluggable user interface components that provide a presentation layer to information systems.

JSR 168's goals are the following:

  • Define the runtime environment, or the portlet container, for portlets
  • Define the API between portlet container and portlets
  • Provide mechanisms to store transient and persistent data for portlets
  • Provide a mechanism that allows portlets to include servlets and JSP (JavaServer Pages)
  • Define a packaging of portlets to allow easy deployment
  • Allow binary portlet portability among JSR 168 portals
  • Run JSR 168 portlets as remote portlets using the Web Services for Remote Portlets (WSRP) protocol

The IT industry has broadly accepted JSR 168. All major companies in the portal space are part of the JSR 168 expert group: Apache, ATG, BEA, Boeing, Borland, Broadvision, Citrix, EDS, Fujitsu, Hitachi, IBM, Novell, Oracle, SAP, SAS Institute, Sun Microsystems, Sybase, TIBCO, and Vignette. The list of official supporters is even longer.

Currently, JSR 168 is in public review and the final version is planned for September 2003.

In this article, we first define portals and portlets, then explain the concepts JSR 168 introduces, including the API's basic objects. Next, we dive into the JSR's more advanced functions, such as user information, localization, and caching. We then cover the extension points that allow portal vendors to extend the currently defined functionality in the portlet specification. The article concludes with the description of portlet application packaging and deployment.

Read the whole series on the Portlet Specification:

Basic definitions

In this section, we explain the basic definitions used in the portlet specification, including a portal's basic architecture, the portlet container, and a portal page.


A portal is a Web-based application that provides personalization, single sign-on, and content aggregation from different sources, and hosts the presentation layer of information systems. Aggregation is the process of integrating content from different sources within a Webpage. A portal may have sophisticated personalization features to provide customized content to users. Portal pages may have different sets of portlets creating content for different users.

Figure 1 depicts a portal's basic architecture. The portal Web application processes the client request, retrieves the portlets on the user's current page, and then calls the portlet container to retrieve each portlet's content. The portlet container provides the runtime environment for the portlets and calls the portlets via the Portlet API. The portlet container is called from the portal via the Portlet Invoker API; the container retrieves information about the portal using the Portlet Provider SPI (Service Provider Interface).

Figure 1. Portal architecture. Click on thumbnail to view full-size image.


Figure 2 depicts the basic portal page components. The portal page itself represents a complete markup document and aggregates several portlet windows. In addition to the portlets, the page may also consist of navigation areas and banners. A portlet window consists of a title bar with the portlet's title, decorations, and the content produced by the portlet. The decorations can include buttons to change the portlet's window state and mode (we explain these concepts later).

Figure 2. Portal page. Click on thumbnail to view full-size image.


As mentioned above, a portlet is a Java-based Web component that processes requests and generates dynamic content. The content generated by a portlet is called a fragment, a piece of markup (e.g., HTML, XHTML, or WML (Wireless Markup Language)) adhering to certain rules. A fragment can be aggregated with other fragments to form a complete document, as shown in Figure 3. A portlet's content normally aggregates with the content of other portlets to form the portal page. A portlet container manages a portlet's life cycle.

Figure 3. Different portlet markups: on the left side, HTML markup in a desktop browser; on the right side, WML markup on a mobile phone. Click on thumbnail to view full-size image.

Web clients interact with portlets via a request/response paradigm implemented by the portal. Usually, users interact with content produced by portlets by, for example, following links or submitting forms, resulting in portlet actions being received by the portal, which then forward to the portlets targeted by the user's interactions.

The content generated by a portlet may vary from one user to another depending on the portlet's user configuration.

Portlet container

A portlet container runs portlets and provides them with the required runtime environment. A portlet container contains portlets and manages their life cycles. It also provides persistent storage mechanisms for the portlet preferences. A portlet container receives requests from the portal to execute requests on the portlets hosted by it. A portlet container is not responsible for aggregating the content produced by the portlets; the portal itself handles aggregation.

A portal and a portlet container can be built together as a single component of an application suite or as two separate components of a portal application.


This section explains the basic programming concepts in JSR 168, such as a portlet's life cycle, interface, and modes and window states, as well as session access, persistent storage access, and how to include servlets and JSP pages.

Portlet life cycle

The basic portlet life cycle of a JSR 168 portlet is:

  • Init: initialize the portlet and put the portlet into service
  • Handle requests: process different kinds of action- and render-requests
  • Destroy: put portlet out of service

The portlet container manages the portlet life cycle and calls the corresponding methods on the portlet interface.

Portlet interface

Every portlet must implement the portlet interface, or extend a class that implements the portlet interface. The portlet interface consists of the following methods:

  • init(PortletConfig config): to initialize the portlet. This method is called only once after instantiating the portlet. This method can be used to create expensive objects/resources used by the portlet.
  • processAction(ActionRequest request, ActionResponse response): to notify the portlet that the user has triggered an action on this portlet. Only one action per client request is triggered. In an action, a portlet can issue a redirect, change its portlet mode or window state, modify its persistent state, or set render parameters.
  • render(RenderRequest request, RenderResponse response): to generate the markup. For each portlet on the current page, the render method is called, and the portlet can produce markup that may depend on the portlet mode or window state, render parameters, request attributes, persistent state, session data, or backend data.
  • destroy(): to indicate to the portlet the life cycle's end. This method allows the portlet to free up resources and update any persistent data that belongs to this portlet.

Portlet modes

A portlet mode indicates the function a portlet performs. Usually, portlets execute different tasks and create different content depending on the functions they currently perform. A portlet mode advises the portlet what task it should perform and what content it should generate. When invoking a portlet, the portlet container provides the current portlet mode to the portlet. Portlets can programmatically change their mode when processing an action request.

JSR 168 splits portlet modes into three categories:

  1. Required modes: Every portal must support the modes Edit, Help, and View. A portlet must at least support the View mode used to render markup for a page. The Edit mode is used to change per-user settings to customize the portlet markup, and the Help mode is used to show a help screen.
  2. Optional custom modes: These are modes that a portal may support; while in an optional mode, a portlet might not be called. The optional modes include the About mode to display an "about" message; the Config mode to let administrators configure the portlet; Edit_defaults mode to let an administrator preset the Edit mode's values; the Preview mode to show the portlet's preview; and the Print mode to render a view that can easily print.
  3. Portal vendor-specific modes: These modes are not defined in the specification and are therefore vendor specific.

Window states

A window state indicates the amount of portal page space that will be assigned to the content generated by a portlet. When invoking a portlet, the portlet container provides the current window state to the portlet. The portlet may use the window state to decide how much information it should render. Portlets can programmatically change their window state when processing an action request.

JSR 168 defines the following window states:

  • Normal: Indicates that a portlet may share the page with other portlets. This is the default window state.
  • Maximized: Indicates that a portlet may be the only portlet on the portal page or that the portlet has more space compared to other portlets in the portal page, and can therefore produce richer content than in a normal window state.
  • Minimized: Indicates that the portlet should only render minimal output or no output at all.

In addition to these window states, JSR 168 allows the portal to define vendor-specific window states.

A portlet can be called in any of these three window states, but is free to produce the same markup for all three states.

Persistent store

The portlet can store persistent data for a specific user by using the PortletPreferences object. Preferences can be read and written in the action phase, and read in the render phase. The preferred mode to write preferences is the Edit mode, which provides the user with a customization screen. The preferences can be either strings or string array values associated with a key of type string. Preferences can be preset with default values in the deployment descriptor.

Preferences and the portlet's definition in the deployment descriptor together define a portlet, sometimes called a portlet entity.


JSR 168's session concept is based on the HttpSession defined for Web applications. As portlet applications are Web applications, they use the same session as servlets. To allow portlets to store temporary data private to a portlet, the default session scope is the portlet scope. In this scope, the portlet can store information needed across user requests and specific to a portlet entity. Attributes stored with this scope are prefixed in the session by the portlet container to avoid two portlets (or two entities of the same portlet definition) overwriting each other's settings.

In addition to the portlet session scope, JSR 168 supports the Web application session scope. In this scope, every component of the Web application can access the information. The information can be used to share transient state among different components of the same Web application (e.g., between portlets, or between a portlet and a servlet).

Including servlets/JSP pages

To support the Model-View-Controller pattern, the portlet must be able to include content generated from servlets and JSP pages. This way, the portlet can act as controller, fill a bean with data, and include a JSP page to render the output.

In JSR 168, the include mechanism for servlets and JSP pages is the same for the Servlet API. Via the portlet context, a request dispatcher is retrieved for a given path; the include() method is then called on this request-dispatcher object:

   PortletRequestDispatcher rd = getPortletContext().getRequestDispatcher(editJSP);
   rd.include(portletRequest, portletResponse);

Alignment with WSRP

WSRP aggregates content produced by portlets running on remote machines that use different programming environments, like J2EE (Java 2 Platform, Enterprise Edition) and .Net. WSRP services are presentation-oriented, user-facing Web services that plug and play with portals or other applications. They let businesses provide content or applications without requiring any manual content- or application-specific adaptation by consuming portals; portals can easily aggregate WSRP services without programming effort.

The JSR 168 expert group carefully aligned the concepts between JSR 168 and WSRP. The following list overviews how much the major concepts have been aligned between both standards:

1 2 Page 1
Page 1 of 2
How to choose a low-code development platform