Introducing the Portlet Specification, Part 1

Get your feet wet with the specification‘s underlying terms and concepts
 
Summary
Portlets are 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. The next step, after servlets in Web application programming, portlets enable modular and user-centric Web applications. The goal of JSR (Java Specification Request) 168, the Portlet Specification, is to enable interoperability between portlets and portals. This specification defines the contract between portlet and portlet container, and a set of portlet APIs that address personalization, presentation, and security. The specification also defines how to package portlets in portlet applications. Part 1 of this two-part series describes the Portlet Specification and explains its underlying concepts. In Part 2, the authors explain the specification‘s reference implementation and show some portlet examples. (3,300 words; August 1, 2003) By Stefan Hepper and Stephan Hesmer

ith 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:
Part 1: Get your feet wet with the specification‘s underlying terms and conceptsPart 2: The Portlet API‘s reference implementation reveals its secrets
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.
Portal
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.
 
Page
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.
 
Portlet
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.
Concepts
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:
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.
 
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.
 
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.
Sessions
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:
Portlet modes and window states are fully aligned.
 
URL encoding and creating URLs pointing to the portlet are fully aligned.
 
Both standards have user-to-portlet interaction, with the action and render phases.
 
State that allows the current portlet fragment to correctly display in subsequent render calls is supported in WSRP under the term navigational state and in JSR 168, with the render parameters, which can map to WSRP‘s navigational state.
 
Both standards store transient state across requests with a session. The WSRP sessionID references JSR 168‘s session when mapping WSRP calls to JSR 168 portlets and vice versa.
 
Storing persistent state to personalize a portlet‘s rendering is realized in WSRP through properties of arbitrary types, whereas JSR 168 supports only preferences of type string or string array. This means that WSRP producers based on JSR 168 use only a subset of the WSRP functionality.
 
Information about the portal calling the portlet is called RegistrationData in WSRP and is represented as a PortalContext object in JSR 168. All data represented through the PortalContext to a JSR 168 portlet is available in WSRP‘s RegistrationData, therefore allowing mapping between PortalContext and RegistrationData.
As evident from this list, all these concepts map between JSR 168 and WSRP. Thus, you can implement JSR 168 portlet containers that can be accessed via WSRP and expose JSR 168 portlets as WSRP services.
Advanced Portlet API items
This section covers more advanced topics of the Portlet API, such as accessing user information, the calling portal‘s context, localization, and caching.
User information
Some portlets may want to personalize the produced markup depending on personal user information. Such information is called user profile information and contains details such as a user‘s name, address, email, and so on. For example, employing a user‘s profile, a weather portlet can present the weather for the city the current user lives in.
The Portlet API supports access to user profile information via the request attribute USER_INFO as a map. The Portlet Specification recommends using theP3P (Platform for Privacy Preferences) user attribute names. A portlet can define in the deployment descriptor which user information attributes it would like to access via this map in the request. The portal can then either map these attributes at deployment time to the attributes in its user datastore or ignore them if they are not supported.
The user information is always about the user triggering the current action and may differ from the J2EE principal, as the portlet could be called as a remote portlet. If the portlet is called as remote (a WSRP producer), the J2EE principal represents the calling WSRP consumer and not the user triggering the request.
Portal context
To let portlets adapt to the portal that calls them, the Portlet API provides the PortalContext, which can be retrieved from the request. This portal context provides information such as the portal vendor, the portal version, and specific portal properties. The information allows the portlet to use specific vendor extensions when being called by a portal that supports these extensions and, when being called by other portals, to return to some simpler default behavior. As the portal context is attached to the request, it may change from request to request. This can be the case in the remote scenario, where one portlet (WSRP provider) may be called from different portals (WSRP consumers).
Localization
The Portlet Specification provides localization on two levels: deployment descriptor and portlet. On the deployment descriptor level, all settings intended to be viewed or changed by the Web server administrator (portlet description, init parameters, display name, and so on) consist of an xml:lang attribute, like the Servlet 2.4 deployment descriptor. The xml:lang tag provides the same tag with descriptions in different languages (e.g., a display name in English, German, and Japanese).
On the portlet level, the specification sets a resource bundle class in the deployment descriptor that contains the portlet title‘s localized versions, the short title for graphically restricted devices, and keywords describing the portlets‘ functionalities. In addition to this information, the specification also recommends a notation for localizing the preference attribute display names, values, and descriptions. The portlet can access the resource bundle via the PortletContext‘s getResourceBundle() method.
Caching
JSR 168 defines support for expiration-based caching, both declaratively and programmatically. In the deployment descriptor, the portlet response‘s expiration time can be defined per portlet. During runtime, the portlet can set an expiration time for the render response using the EXPIRATION_CACHE property.
Any request targeted to this portlet automatically expires the cached content. This means that when a user clicks on this portlet‘s action or render link, the portlet gets called independently of the remaining cache expiration time.
Extensibility
The Portlet Specification has several mechanisms that allow portal vendors to include their specific extensions. This section explains the most important mechanisms: vendor-specific properties, custom portlet modes, and custom window states. As explained in the "Portal Context" section, the portlet can obtain information about a portal‘s supported extensions via the portal context.
Properties
Properties communicate vendor-specific settings between the portlet and portlet container, and between the portlet and the portal.
These properties show up in several places in JSR 168. The portlet can read String properties with getProperty() from:
ActionRequest, to receive properties that are action-request specific RenderRequest, to receive properties that are render-request specific PortalContext, to receive properties that are portal specific and do not change for different requests
The portlet can write String properties with setProperty() to:
ActionResponse, to set properties in response to an action request RenderResponse, to set properties in response to a render request
Custom portlet modes and window states
If a portlet application uses additional portlet modes or window states than the ones defined by the Portlet Specification, the portlet application can declare them in the deployment descriptor. At deployment time, the defined custom portlet modes and window states are either mapped to vendor-specific portlet modes and window states the current portal supports, or ignored. A portlet can use only portlet modes or window states supported by the portal running the portlet. The portlet can use the PortalContext‘s getSupportedPortletModes() and getSupportedWindowStates() methods to retrieve the portlet modes and window states the portal supports.
The portlet can define custom portlet modes and window states in the deployment descriptor by using the custom-portlet-mode and custom-window-state tags.
Packaging and deployment
A portlet application‘s resources, portlets, and deployment descriptors are packaged together in one Web application archive (war file). In contrast to servlet-only Web applications, portlet applications consist of two deployment descriptors: one to specify the Web application resources (web.xml) and one to specify the portlet resources (portlet.xml). All Web resources that are not portlets must be specified in the web.xml deployment descriptor. All portlets and portlet-related settings must be specified in an additional file called portlet.xml. There are three exceptions to this rule, which are all defined in the web.xml, as they are valid for the whole Web application:
The portlet application description The portlet application name The portlet application security role mapping
As result of the two deployment descriptor files, portlet application deployment is a two-step deployment that deploys the Web application into the application server and the portlets into the portal server.
A portlet.xml file always describes only one specific portlet application. To create a copy of a portlet application with slightly different settings, a new portlet application must be created. Figures 4 and 5 depict the portlet.xml file‘s complete schema definition. Figure 4 shows the settings that can be applied on the application level, whereas Figure 5 depicts the settings on the portlet level.

Figure 4. First part of the deployment descriptor schema. Click on thumbnail to view full-size image.
 

Figure 5. Second part of the deployment descriptor schema. Click on thumbnail to view full-size image.
 
Round one
The first version of the Portlet Specification has defined a comprehensive and powerful portlet API that should address the needs of most of the simpler portlet applications. Wherever possible, the Portlet Specification leverages concepts of J2EE and the Servlet Specification to reuse existing infrastructure and tools.
Future versions of the Portlet Specification will address the needs of the more complex portlet applications that need more interaction between portlets.
In Part 2, we will explain the architecture of the reference implementation Pluto, show some example code, and present how to deploy these examples under the reference implementation.
About the author
Stefan Hepper received a Diploma of Computer Science from the University of Karlsruhe. After working for three years in the Research Center Karlsruhe in medical robotics and component-based software architectures for real-time systems, he joined the IBM Pervasive Computing division. He is now an architect for the WebSphere Portal team, responsible for Java standards. Stefan has been working with Java since 1997 and is one of the two specification leads for JSR 168.
Stephan Hesmer received a Diploma of Information Technology from the University of Cooperative Education Stuttgart in 2000. After graduating, he joined the IBM Boeblingen Development Laboratory to work with the WebSphere Portal team. Currently he is the architect and team lead of the Portlet Environment in WebSphere Portal and of the JSR 168 reference implementation. Stephan has worked with C++ and Java for many years. Outside work, he enjoys hiking, squash, and skiing.
Resources
Pluto reference implementation:
http://jakarta.apache.org/pluto
Read the whole series, "Introducing the Portlet Specification," Stefan Hepper and Stephan Hesmer (JavaWorld):Part 1: Get your feet wet with the specification‘s underlying terms and concepts (August 2003)Part 2: The Portlet API‘s reference implementation reveals its secrets (September 2003)
JSR 168:
http://www.jcp.org/en/jsr/detail?id=168
Information about WSRP:
http://www.oasis-open.org/committees/wsrp/
Information about the user profile attributes in P3P:
http://www.w3c.org/TR/P3P
For more on portals and portlets, read the following JavaWorld articles: "Go With the Flow," Brian Pontarelli and Grant Zemont (February 2003) "Develop Java Portlets," Carl Vieregger (February 2003) "Build Portals with Jetspeed," Jeff Linwood (July 2001)
Browse the JavaServer Pages section of JavaWorld‘s Topical Index:
http://www.javaworld.com/channel_content/jw-jsp-index.shtml
Browse the Java and Web Services section of JavaWorld‘s Topical Index:
http://www.javaworld.com/channel_content/jw-webserv-index.shtml
Browse the Java 2 Platform, Enterprise Edition (J2EE) section of JavaWorld‘s Topical Index:
http://www.javaworld.com/channel_content/jw-j2ee-index.shtml
Browse the Servlets section of JavaWorld‘s Topical Index:
http://www.javaworld.com/channel_content/jw-servlets-index.shtml
Browse the Java Community Process of JavaWorld‘s Topical Index:
http://www.javaworld.com/channel_content/jw-jcp-index.shtml
Browse the APIs section of JavaWorld‘s Topical Index:
http://www.javaworld.com/channel_content/jw-apis-index.shtml
Visit JavaWorld‘s Enterprise Java discussion:
http://www.javaworld.com/javaforums/postlist.php?Cat=&Board=Enterprisejava
Sign up for JavaWorld‘s free weekly Enterprise Java email newsletter:
http://www.javaworld.com/subscribe
_xyz