A portlet is a Web component that generates fragments - pieces of markup (e.g., HTML, XML) adhering to certain specifications. Fragments are aggregated to form a complete document.

This article introduces the Java Specification Request (JSR) 168 on Java Portlets. It illustrates the creation of Java Portlets using BEA WebLogic Workshop 8.1 SP2 and the deployment of these portlets on BEA WebLogic Portal 8.1 SP2. I'll look at essential concepts such as portal, desktop, and portlets and describe in detail the various portlet modes and window states. I'll also look at designing, implementing, configuring, and executing portlets with Workshop.

JSR 168 defines the specification for Java Portlets. A portal is a Web application and an aggregation of portlets. A portlet container runs portlets and manages their life cycle. JSR 168 defines the contract between a portlet and portlet container. It does not define the contract between a portlet container and a portal. The implementation of the portal is left up to the portal vendors.

BEA WebLogic Portal

The current version of BEA WebLogic Portal (8.1 SP2) supports different types of portlets: JSP/HTML portlets, Java PageFlow portlets, Struts portlets, and Java portlets. In the future, other portlets, such as Web Services for Remote Portlets (WSRP) will be supported. Our focus will be on Java portlets.

WebLogic Portal provides portal capabilities above and beyond those described in JSR 168 including, but not limited to, the organization of portlets in books and pages; multichannel support; and customization using skins, skeletons, and shells.

In order to follow along here, before proceeding to the next section please complete the following:

• Using the WebLogic Domain Configuration Wizard, create a portal domain (e.g., JSR168PortalDomain).
• Using WebLogic Workshop create a portal application (e.g., JSR168PortalApp) that uses the above-created domain.
• Create a portal Web project (e.g., JSR168PortalWebProject) inside the portal application.
• Create a WebLogic Portal .portal file (e.g., JSR168.portal) inside the portal Web project.
• Start the server instance.

Creating Your First Java Portlet

The following steps describe creating your first JSR 168 portlet.

• Using WebLogic Workshop, create a new folder for the portlet (e.g., FirstPortlet) inside a portal Web project (e.g., JSR168PortalWebProject).
• Create a new portlet by creating the corresponding .portlet file (e.g., First.portlet) using the Wizard inside the new folder.
• Choose Java Portlet as the portlet type.
• Specify the title (e.g., First).
• Specify the definition label (e.g., first).
• Specify the class name (e.g., com.malani.examples.portlets.jsr168.FirstPortlet).
• Open the portal (e.g., JSR168.portal).
• Drag-and-drop the portlet (e.g., First.portlet) onto a page in the portal (e.g,. JSR168.portal).
• Run the .portal file to test it.

Your first JSR 168 portlet is running successfully! But what does the wizard do underneath the covers?

• It creates a WebLogic Workshop and WebLogic Portal-specific .portlet file. The .portlet file forms the contract with the Workshop and WebLogic Portal-specific .portal file.
• The wizard creates a .java file (e.g,. com.malani.examples.portlets.jsr168.FirstPortlet.java) that is placed in the WEB-INF/src directory.
• The wizard creates a WEB-INF/portlet.xml configuration file and inserts an entry for the portlet into the file. The entry for the portlet looks something like:

  <portlet>
  <description>Description goes here</description>
  <portlet-name>first</portlet-name>
  <portlet-class>com.malani.examples.portlets.jsr168.FirstPortlet
  </portlet-class>
  <portlet-info>
  <title>First</title>
  </portlet-info>
  </portlet>

Java Portlet Class

The Portlet Java file generated by the wizard in this example extends the javax.portlet.GenericPortlet class. The GenericPortlet class implements the javax.portlet.Portlet interface. Figure 1 is a Unified Modeling Language (UML) class diagram depicting these relationships. A portlet can be written by directly implementing the portlet interface. However, GenericPortlet is a more convenient way of creating a portlet. First, let's look at the portlet life cycle, portlet modes, and window states.

Portlet Life Cycle
To successfully create portlets, you have to follow the portlet life cycle. The methods in the javax.portlet.Portlet interface define that life cycle. The life-cycle methods are init(), render(), processAction(), and destroy(). The init() method is called when an instance of the portlet is deployed. It is used to obtain any needed expensive resources, such as back-end connections, and perform other one-time activities. The destroy() method is used to release those resources when an instance of the portlet is undeployed.

The portlet specification makes a clear distinction between render requests and action requests. Figure 2 depicts a UML class diagram of portlet requests and responses. A render request on the portal page results in the calling of the render() method on each portlet on the displayed page. When a user invokes an action on a particular portlet, typically an HTML form submission, the processAction() method of that portlet is invoked. The render() methods of all portlets on the same page are also invoked. Thus, an action request by the user translates into one invocation of a processAction() method and multiple invocations of render() methods. Figure 3 is a sequence diagram depicting the effect of invoking processAction() method and subsequent invocations of render() methods for the portlets on the same page. For further information, refer to the section on Processing Actions.

There are two overloaded init() methods, one with no-arguments and the other with an instance of javax.portlet.PortletConfig class. Note: There is a peculiar caveat about the init(PortletConfig) method. Failure to invoke super.init(aPortletConfig) results in a NullPointerException. The Init portlet in the included source code example illustrates this behavior (the source code is online at www.sys-con.com/weblogic/source.cfm).

Portlet Mode
JSR 168 defines three Portlet Modes: VIEW, EDIT, and HELP. A portlet instance can be in exactly one portlet mode at any time. Other custom portlet modes, such as config and source, are possible. The VIEW mode is the default mode. The portlet specification recommends that the EDIT mode allow the user of the portlet to customize the portlet instance and the HELP mode display the usage information about the portlet. A portlet must support the VIEW mode but the support of the EDIT mode and HELP mode in a portlet is optional. For example, the First portlet example does not support the EDIT mode or HELP mode.

Window State
JSR 168 defines three Window States: NORMAL, MINIMIZED, and MAXIMIZED. The portlet instance can be in exactly one window state at any time. Other custom window states, such as half-page, are also possible. In the NORMAL state, the portlet occupies a small part of the screen real estate. The screen real estate is shared with other portlets. In the MINIMIZED state, the contents of the portlet are hidden. In the MAXIMIZED state, the contents of the portlet occupy most of the screen real estate. Other portlets sharing the same page are hidden in the MAXIMIZED state. For example, the First portlet example supports all three Window States.

GenericPortlet Class
Most of the portlets you create will extend the javax.portlet.GenericPortlet class instead of directly implementing the javax.portlet.Portlet interface. The GenericPortlet class implements the render() method. If the portlet's window state is minimized, then the render() method doesn't do anything. If the portlet's window state is other than minimized, then the render() method sets the title specified in the portlet.xml file and invokes the doDispatch() method. Depending upon the Portlet Mode, the doDispatch() method invokes doView(), doEdit(), and doHelp() methods appropriately. Thus, the GenericPortlet class is more convenient to extend than the Portlet interface is to implement because the GenericPortlet class helpfully implements the render() method and provides easy doView(), doEdit(), and doHelp() methods to override.

Consider the First portlet example. The FirstPortlet class extends GenericPortlet. FirstPortlet overrides the doView() method:

  public void doView(RenderRequest request, RenderResponse response)
    throws PortletException, IOException
  {
    response.setContentType("text/html");
    response.getWriter().write("<p>Hello World</p>");
  }

Note: Calling the getWriter() method before calling setContentType() method results in a java.lang.IllegalStateException.

Implementing Portlet Modes
The VIEW mode is mandatory but the EDIT and HELP modes are optional. In order to implement the EDIT and HELP portlet modes, implement the appropriate doEdit() and doHelp() methods in the portlet class. Refer to Mode portlet included in the source code example (source code for this article is online at www.sys-con.com/wldj/sourcec.cfm). In addition, you must configure the modes in the portlet.xml as follows:

<supports>
<mime-type>text/html</mime-type>
<portlet-mode>edit</portlet-mode>
<portlet-mode>help</portlet-mode>
</supports>

Note: Changing the portlet.xml configuration file, but not implementing the corresponding methods in the portlet class, results in a javax.portlet.PortletException.

Implementing Window States
JSR 168 does not describe a way to disable support for Window States. However, WebLogic Portal implements the disabling of them. To disable a portlet's support for Window states, exclude the Window states in the weblogic-portlet.xml:

<portlet>
<portlet-name>state</portlet-name>
<supports>
<mime-type>text/html</mime-type>
<excluded-window-state>minimized</excluded-window-state>
<excluded-window-state>maximized</excluded-window-state>
</supports>
</portlet>

Refer to the State portlet included in the source code example.

Including JavaServer Pages (JSPs)
Consider the doView() method of the First portlet. This method gets the instance of the Writer and directly outputs HTML fragments. Outputting direct HTML fragments is usually not recommended for various reasons, such as trying to achieve a separation between Java logic and HTML view presentation. The recommended way is to display the view using a JSP. The methods in the portlet class execute business logic, set the render parameters, and include the JSP. To include a particular JSP, first get the PortletContext. From the PortletContext instance, get an instance of PortletRequestDispatcher by calling the getRequestDispatcher() method. Include the JSP by invoking the include() method. For example:

// execute the necessary logic here...
PortletRequestDispatcher aDispatcher =
getPortletContext().getRequestDispatcher(
"/IncludePortlet/includeView.jsp"
);
aDispatcher.include(aRequest, aResponse);

Note: A portlet may use a PortletRequestDispatcher object only when executing the render() method.

Refer to the Include portlet in the source code. A JSP page, such as includeView.jsp, does not contain root HTML tags such as <html>, <title>, and <body> since the tags are provided by the portal framework. The JSP page contains only the HTML fragments necessary to display the portlet.

Processing Actions

In a standard Web application an HTML form submission results in executing some business logic. The results of business processing are either set in the request or session as attributes and forwarded or included to the next JSP.

In a JSR 168 portlet, what should the action URL for an HTML form be? JSR 168 defines a JSP tag library, known as portlet taglib. The action URL for an HTML form is generated using the actionURL portlet tag. For example (refer to favoriteColorEdit.jsp file):

<form action="<portlet:actionURL/>" method="post">
...
</form>

Submitting the HTML form results in invoking the processAction(ActionRequest aRequest, ActionResponse aResponse) method of the portlet. As usual, form parameters can be obtained by invoking getParameter() method of the request object. Note: Invoking the action by submitting the form, but not having the processAction() method in the portlet, results in a javax.portlet.PortletException.

The processAction() method sets the values in the response object. Do not use the setAttribute() method of the ActionRequest or ActionResponse object. The values will not be propagated from the processAction() to the render() method and will not be available in the JSP. Instead, use the setRenderParameter() method of the ActionResponse object. These render parameters will be available for all subsequent render requests and are quite different from typical Web application request attributes. The typical Web application request attributes are only valid for a request. On the other hand, the render parameters are valid for many subsequent render requests. The render parameters remain valid until the value is explicitly changed or removed by re-execution of the action.

Consider the FavoriteColor portlet. It displays a user's favorite color in the VIEW mode, but can be changed in the EDIT mode. Submitting the favorite color choice in the EDIT mode invokes the processAction() method. This method gets the favorite color request parameter and sets it as the render parameter. Thus, the favorite color render parameter is available in all subsequent render requests.

How are the rendered parameters displayed on the JSP? Use the defineObjects tag from the portlet taglib to define portlet objects. This tag makes renderRequest, renderResponse, and portletConfig portlet objects available in the page. A parameter is displayed by invoking the getParameter() method of the renderRequest object. Refer to favoriteColorView.jsp in the included source code example.

The FavoriteColor portlet demonstrates other concepts as well. The first is how to programmatically change the portlet mode in the processAction() method. Invoke the setPortletMode() method of the ActionResponse object to change the portlet mode. The second concept is how to change the portlet mode using an HTML link. The link URL is generated using the renderURL tag from the portlet taglib. The value for the portletMode attribute is specified as the desired portlet mode. Refer to FavoriteColorPortlet class and favoriteColorView.jsp page included in the source code example.

Portlet Preferences

Portlet preferences are the basic configuration data for portlets. A preference is a name and value pair. The type of name is a string, whereas the type of value is either a string or an array of strings. A portlet preference is not suited for storing arbitrary data. The portlet container provides persistence for portlet preferences. In WebLogic Portal, the persistence for preferences works only when both of the following conditions are true:

• The portal is running in the desktop instead of DOT portal mode.
• A user is logged in.

Desktop Versus DOT Portal Mode
When a .portal file is created in WebLogic Workshop, items such as books, pages, and portlets are dragged-and-dropped into the .portal file and the .portal file can be run directly from within Workshop. However, certain features, like storing of preferences, are not available when running in this DOT portal mode. (DOT portal mode is also known as Single File Mode.)

The other mode is known as desktop mode. Using the Portal Administrator a portal is created. Within the portal, a desktop is created. Items such as books, pages, and portlets are created and placed within the desktop. In this mode, certain features, like storing of preferences, are available. (The desktop mode is also known as Streamed Mode.)

Before we go on, create a desktop:

• Launch Portal Administration (e.g., http://localhost:7001/JSR168PortalAppAdmin/). One way to launch Portal Administration is directly from Workshop. Select the Portal menu and Portal Administration menu item.
• Log in to the Portal Administration.
• Create a new portal (e.g., JSR168).
• Inside the portal, create a new desktop (e.g., d1).
• Add the LoginPortlet to one of the pages of the desktop.
• Add the ContactPortlet to one of the pages of the desktop.

Portlet Preferences Example
The Contact portlet demonstrates Portlet Preferences. Portlet Preferences can be static or dynamic. Static preferences are specified in the portlet.xml file together with the portlet. For example, the ContactPortlet has a preference named contact-preference. The default value of the contact-preference is also specified:

<portlet-preferences>
<preference>
<name>contact-preference</name>
<value>Email</value>
</preference>
</portlet-preferences>

Dynamic preferences are not predefined in the portlet.xml configuration file. These preferences are stored and retrieved as the portlet is running. At runtime, an instance of the javax.portlet.PortletPreferences interface contains the preferences. The instance is obtained by invoking the getPreferences() method on the PortletRequest object. The value of a particular preference is obtained by invoking the getValue() method on the preferences instance.

Invoking the setValue() method of the preferences instance updates a preference value. However, an additional step is required to commit the changes. The store() method of the preferences instance is invoked to persist the preferences. Preferences can only be modified in the processAction() method. Any changes made to the preferences instance are discarded if the store() method is not invoked in the processAction() method. Note: As I mentioned earlier, if the user is not logged in or the portal is in the DOT portal mode, calling the store() method results in a runtime exception.

There are quite a few similarities between portlets and servlets. However, there are crucial differences as well. The portlet specification builds upon the servlet specification. The portlet container resides within the servlet container. Just as servlets are deployed within a Web application, so are portlets. Servlets and Web applications are configured using the web.xml. Portlets are configured using the portlet.xml file. A servlet has an explicit life cycle: init(), doGet(), doPost(), etc. Similarly, a portlet has an explicit life cycle: doView(), doEdit(), processAction(), etc. Methods of servlet and portlet classes must be coded in a thread-safe manner.

However, there are crucial differences as well. Servlets are allowed to do include, forward, and redirect, whereas portlets are only allowed to include. Servlets can render a complete page, whereas portlets render only page fragments. Portlets have well-defined portlet modes and Window states, unlike servlets. Portlets have more formal request handling with render requests and action requests and they have preferences. A portlet is not a servlet!

Conclusion

I started this article by describing the creation of portlets with a simple wizard. I illustrated the life cycle of the portlet and the inner workings of the portlet class implementation and described the structure and semantics of the portlet.xml configuration file and the corresponding weblogic-portlet.xml configuration file. I explained various concepts such as portlet modes and window states. I demonstrated the usage of portlet taglib and form processing in the portlet. Finally, I explained how to leverage and work with portlet preferences. Armed with the knowledge and concepts described in this article you're on your way to creating and deploying your own powerful portlets.

Acknowledgments

I want to thank Subbu Allamaraju, Max Cooper, Steve Ditlinger, David Lu, Roshni Malani and Alex Toussaint for reviewing this article and providing invaluable feedback.

References