Introduction to the Java Portlet Specification

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.