Introduction to the Java Portlet Specification

Thursday Sep 8th 2005 by David DeWolf

Start working with the Java Portlet Specification (JSR-168). Gain a solid understanding of the basics of portals and portlets then try your hand at developing compliant portlets.

The Java Portlet Specification (originally created through JSR-168) provides a standard for developing portal components with the Java programming language. This specification, originally released in October 2003, is gaining popularity as not only a standard for traditional portals, but also as a framework for deploying 'plugins' for standard Web applications. This introduction to the Java Portlet Specification will introduce the basics of portals and portlets.It will provide the essentials needed to understand that Java Portlet API and to begin developing compliant portlets.

Portals, Portlets, and the Java Portlet Specification

A portal is a Web application that presents content from multiple sources. Portlets are Web components that generate content fragments (typically pieces of markup such as HTML, XML, or WML). By aggregating the content generated by many portlets, a portal is able to generate a single user interface which integrates many disparate sources. In addition to aggregation services, enterprise portals often provide additional services such as personalization or single sign on; however, the availability and implementation of these services vary.

A portal interacts with clients, typically Web browsers, through a series of requests and responses. When a portal receives a request, it translates it into a series of requests targeted for specific portlets. These individual requests are then forwarded to individual portlets for processing.

A portal utilizes a portlet container to manage the lifecycle of portlets. A portlet container is responsible for the initialization, request processing, and destruction of portlets. The Java Portlet Specification defines the contract between a compliant portlet container and portlets. This standardization allows for portability of portlets between portal implementations.

The Java Portlet Specification is very similar to the Java Servlet Specification by design. In fact, the Java Portlet Specification is built on top of the Java Servlet Specification 2.3 and Java Server Pages version 1.2 and leverages its objects whenever possible. Because a portlet container must execute within a compliant servlet container (or implement all of the functionality provided by a compliant container), portlets have the ability to dispatch requests to servlets, JSPs, and other standard Web resources. Portlets, servlets, JSPs, and other Web resources are bundled into a specialized Web application called a portlet application.

Portlet Basics

The basics of portlet development are very similar to the basics of servlet development. In addition to ensuring that all portlets execute within a standard servlet environment, the portlet specification's API is modeled after the servlet paradigm. The Portlet, PortletConfig, PortletRequest, and PortletResponse interfaces are very similar to their Servlet counterparts. As with servlets, a portlet will service multiple client requests (often concurrently) while in service. Because of this, portlets are not thread safe and must not utilize instance members.

Because the content generated by a portlet is arggregated with the content from other portlets and the portal itself, it is essential that portlets limit the markup that they generate. A fragment is a small piece of markup that is contained within a document. Each portlet must take care to only include markup fragments and not entire markup documents.

Portlet Requests, Responses, and Sessions

The portlet API takes special care to separate the processing of requests and rendering of requests. This separation is critical. Because portals aggregate fragments from multiple portlets, each portal request will require those portlets that are not targeted in an action to be rerendered. If portlet processing and rendering were combined, this rerendering would require reprocessing. This could lead to anything from data duplication to unnecessary execution of processing logic.

The ActionRequest and ActionResponse interfaces are utilized by a portlet to process actions—typically form submissions. The ActionRequest provides the ability to the binary data sent from the client. The ActionResponse enables the portlet to respond and manipulate the request by setting the PortletMode (discussed below), WindowState (discussed below), and render parameters. Portlet developers can also redirect the request through the ActionResponse.

A RenderRequest is utilized to communicate render parameters to a portlet. A RenderRequest does not have access to the original parameters sent to the ActionRequest by the client. Instead, render parameters are utilized to pass information from the action phase to the render phase. The RenderResponse interface provides the portlet a mechanism for communicating the generated content to the client (often through the portal).

The PortletSession is available through both any PortletRequest. The PortletSession contains two different scopes—application scope and portlet scope. Application-scoped attributes are available globally to all Web resources within the portlet application. Attributes scoped at the portlet level are only required to be made available to the preclude that initially added them to the session. The Portlet Specification does not proclude portlet scoped attributes from being available to global resources. Instead, the specification states that "Attributes stored in the (portlet scope) are not protected from other Web components of the portlet application. They are just conveniently namespaced."

Note: The Java Servlet Specification requires that two contexts may never share the same session instance. Because of this, it is impossible to share session information between two portlet applications (or a portlet application and the portal).

Portlet Modes and Window States

Portlet Modes and Window States are used to communicate to the portlet visibility state. Window States expand and contract the relative size granted to the portlet for rendering. The Portlet Specification provides three mandatory window states. Portlets that are minimized should render very little content. Portlets that are maximized are assumed to be either the only or the predominately displayed portlet. Portlets that have a 'normal' WindowState typically share the rendering area with multiple portlets.

Portlet Modes specify the current view of the portlets. Default portlet modes include VIEW, EDIT, and HELP. Portlets should generate relevant information to each for each of these modes. Typically, the edit mode provides the user the ability to customize the behavior of the portlet, the help mode provides instructions and other helpful information regarding the portlet, and the view mode provides content regarding the current state of the portlet.

Portlets have the ability to modify their own view state by changing their own Portlet Mode and Window State during an ActionRequest. This is done by invoking the ActionResponse's setWindowState and setPortletMode methods. Custom modes also may be provided.

Portlet Preferences

Portlet Preferences provide portlet developers a mechanism for persisting configuration, customization, and personalization settings for individual users. The PortletPreferences interface provides the methods necessary for reading, writing, and resetting preferences. Preferences may only be updated during ActionRequests; however, they are made available to all PortletRequests.

Putting It All Together

Tying Up Loose Ends

The GenericPortlet class provides a default implementation of the Portlet interface. By extending GenericPortlet, portlet developers can take advantage of built-in interpretation of Portlet Modes and default implementations of the lifecycle methods. The Hello World example below leverages the GenericPortlet implementation.

Portlet Tag Libraries

The portlet specification defines tag libraries that are used to develop JSPs that render portlet fragments. This library contains tags that can be used to define portlet objects within a page, generate portlet urls, and generate unique portlet namespaces. The example below utilizes these tag libraries to generate the edit page of the portlet (see example code download).

Hello World!, Portlet Style

In the attached Hello World! example, simple rendering and action processing is demonstrated. When first rendered, doView is invoked by the render method of GenericPortlet. This method will render the default greeting.

public void doView(RenderRequest req, RenderResponse res)
throws IOException {
   PrintWriter out = res.getWriter();
   out.println(getGreeting(req) + " World!");

When the portal's controls are used to switch the portlet mode to edit, the portlet will render the edit screen that allows the user to change their greeting. doEdit is invoked by GenericPortlet's implementation of render. In this method, you utilize a request dispatcher to forward the request to a JSP that will generate this content fragment.

public void doEdit(RenderRequest req, RenderResponse res)
   throws PortletException, IOException {
      PortletRequestDispatcher dispatcher =
      dispatcher.include(req, res);

The JSP page utilizes several portlet tags to generate the action URL that will be used to process this page.

<%@ taglib uri="" prefix="portlet"%>
<portlet:actionURL var="url" portletMode="view"/>
<FORM method="POST" action="<%= url %>">
   <TD><INPUT type="text" name="greeting"
              value="<%= renderRequest.getParameter("greeting") %>"/>
   <TD colspan="2"><INPUT type="submit" value="Save"/></TD>

Finally, upon submission, the container calls the portlet's processAction method. This method sets a render parameter that can be utilized while rendering the portlet.

public void processAction(ActionRequest req, ActionResponse res)
throws PortletException {
   String greeting = getGreeting(req);
   res.setRenderParameter("greeting", greeting);

The full source of the example portlet above is available for download.


The basics of portlet development are very similar to those of servlet development. Web application developers who are aware of the basics of portlet development, including the generation of fragments and the separation of action and render requests, should find portlet development fairly familiar. In my next article, I will address the deployment of portlets within Apache Pluto (the reference implementation of the Java Portlet Specification) and show how using Pluto as a lightweight development environment can increase productivity.


  • The Java Portlet Specification
  • The Java Portlet API

About the Author

David DeWolf has been developing Web applications, portals, and portlet applications for six years. He is a member of the Apache Portals Project Management Committee and an active committer to Apache Pluto, the reference implementation of the Portlet Specification. David currently works at Digital Focus, which provides software development, agile coaching, and IT consulting services to Fortune 1000 and medium-sized businesses. Contact David at

Mobile Site | Full Site
Copyright 2017 © QuinStreet Inc. All Rights Reserved