Introduction

The JSR 168 Portlet API is a well-accepted and adopted standard for portlet development. Portlet containers supporting the JSR 168 Portlet API have been available for a long time in open source projects such as Pluto and in enterprise products such as WebSphere Portal. The JSR 168 portlet container is an integral part of WebSphere Application Server V6.1; it is a common component for both WebSphere Portal and WebSphere Application Server (hereafter called Application Server). WebSphere Portal leverages the portlet contain, and extends its capabilities. By providing the portlet container in the application server, IBM is encouraging the portlet programming model over the server user interface (UI) for Web applications. Programmers can easily develop portlets using any Application Server installation, and they can re-use these portlets with WebSphere Portal.

This article introduces you to the JSR 168 portlet container in Application Server. First, you get an overview of the container's capabilities, and then you see how to install and access your first portlet. Finally, you see one of the corner stones of the portlet container in Application Server, called URL Addressability. You also see how these features compare to similar features in WebSphere Portal.

This article series is intended for several audiences, including developers and architects who would like to use the portlet container in Application Server as a development platform, and do not already know (or don’t require) WebSphere Portal for development. It is also for developers and architects already skilled with WebSphere Portal, who would like to understand how portlet development is made easier for them by the placement of the container into the application server.

Back to top

When to use the Application Server portlet container

With the new portlet container in Application Server, you have two portlet containers from which to choose:

• The portlet container in Application Server provides base capabilities such as the JSR 168 Portlet API.
• The portlet container in WebSphere Portal extends these capabilities with additional features such as property broker events, portlet services events, and other capabilities.

Therefore, if you develop a portlet on top of Application Server, it will run on WebSphere Portal. The converse is not necessarily true; if you create a portlet which uses features of WebSphere Portal not supported by the Application Server portlet container, then it will not run on Application Server. However, you can write the code in such a way that it allows for a seamless degradation of functionality.

Because portlets are user facing applications, it is best to use the portlet container in Application Server when your application requirements fit the features provided with the platform. For Application Server, this is mostly the case if you need only one user interfacing component to be displayed on the page, without feature rich aggregation. On the other hand, use the portlet container in WebSphere Portal if you need a feature-rich aggregation with an extended programming model.

Back to top

About the sample portlet

You can download the sample portlet for the World Clock example, and refer to it as you read the this article series. For a detailed description of the sample, see this article Converting the WorldClock portlet from the IBM Portlet API to the JSR 168 portlet API (see Resources) .

Back to top

Portlet container features summary

This section summarizes the feature set provided with the JSR 168 portlet container, categorized into three main topics: addressability, manageability, and extensibility (for better accessibility). Table 1 includes these descriptions and indicates which part of this article series contains the corresponding information.

Now that you are familiar with the portlet container features, let's see how to install a portlet application.

Back to top

Installing a portlet

The JSR 168 Java Portlet Specification defines the portlet application deployment package as an extension of the Web application. It is packaged as a Web ARchive (WAR) file; therefore, installing a portlet is the same as installing a servlet, from a user perspective.

You can install a portlet by using either the administrative console or the scripting interface, called wsadmin. The following paragraphs illustrate both ways using the world clock portlet as an example.

Using the WebSphere Administrative Console

1. Open the WebSphere Administrative Console. For example, if your server is local, open in a browser:

   http://localhost:9060/ibm/console

   
   
2. Log in and access the Install New Application section.
3. Enter the path name to the world clock portlet as shown in Figure 1.
   
   Figure 1. Install New Application section in the Administrative Console
   
   
   
4. Click Next on each page until you get to the page with the Install button.
5. Click the Install button. The deployment should proceed normally as known from a servlet and finish with a success message.
6. Save the changes.
7. Start the application by opening the following in your browser:

   http://localhost:9080/worldclock/StdWorldClock

   
   

   You see the portlet as shown in Figure 2.

Considerations when deploying a portlet

You need to consider the following cases when deploying a portlet application WAR file.

• A portlet and a servlet can never have the same name. See Listing 1 for an example how not to do it.
  
  
  Listing 1. A Portlet and a servlet with the same name.
  

  <servlet> <servlet-name>BookmarkPortlet</servlet-name> ... </servlet> <portlet> <portlet-name>BookmarkPortlet</portlet-name> ... </portlet>

  
  
• The url pattern of a servlet mapping can never be the same as any /<portlet-name>/* or /portlet/<portlet-name>/*. See Listing 2 for an example how not to do it.
  
  
  Listing 2. A Portlet and a servlet with the same mapping.
  

  <servlet-mapping> <servlet-name>BookmarkPortlet</servlet-name> <url-pattern>/BookmarkPortlet/*</url-pattern> </servlet-mapping> <portlet> <portlet-name>BookmarkPortlet</portlet-name> ... </portlet>

  
  

Using the scripting interface (wsadmin)

Another way you can install a portlet is by using the scripting interface, wsadmin.

1. First, start wsadmin so that is connects to the server. You see the message in Listing 3:
   
   Listing 3. Message seen after connecting to the server.
   

   C:\WebSphere\bin>wsadmin WASX7209I: Connected to process "server1" on node HESMERT40Node02 using SOAP connector; The type of process is: UnManagedProcess

   
   
2. In the command prompt, you enter a command to install the portlet, as in Listing 4.
   Important: Always use forward slashes, even on a Windows system.
   
   Listing 4. Installing the portlet.
   

   wsadmin> $AdminApp installInteractive D:/portlets/StdWorldClock.war {-contextroot /worldclock} ... ADMA5013I: Application StdWorldClock.war10af6ae88f7 installed successfully.

   
   
3. Save the configuration, as in Listing 5.
   
   Listing 5. Saving the configuration.
   

   wsadmin> $AdminConfig save

   
   

To see the portlet, open the application in a browser using this URL:
http://localhost:9080/worldclock/StdWorldClock

You see the portlet shown in Figure 2.

Comparing the portlet container to WebSphere Portal

With WebSphere Portal, you can install portlets in similar ways, using the WebSphere Portal administrative interface or the scripting interface called XMLAccess.

The administrative interface is divided into a couple of sections reflecting the various areas of portal. You use the portlet area to administer all aspects of portlets; it includes the Manage WebModules portlet which you can use to install portlets. To locate this feature, in WebSphere Portal, open Administration => Portlets => Manage WebModules. Unlike Application Server, the portal administrative interface accepts WAR files only; it does not accept EAR files.

You can also use the scripting interface, XMLAccess, to install a portlet in WebSphere Portal. For more information see the WebSphere Portal Information Center listed in Resources. You can use XMLAccess to install pre-deployed EAR files as well as WAR files.

After installing a portlet, you access it using the browser, as you saw in the simple example using a very simple URL in Installing a portlet. The next section reveals more about addressing portlets, including special portlet features such as edit mode.

Back to top

Accessing and addressing portlets

The JSR 168 Java Portlet Specification defines a Java API with a corresponding deployment descriptor very similar to the Servlet Specification. The Servlet Specification defines how servlets can be accessed from a browser using url mappings and context roots, so that we are able to view servlets.

Portlets, on the other hand, are designed to run in an aggregated fashion and not to consume the whole response or view; therefore, they always share the page with other portlets. This is one reason why the JSR 168 Java Portlet Specification does not include any direct access to portlets (such as using a URL); instead, access is left to the portal application and its aggregation framework.

Application Server is a developer platform which provides easy and direct access to resources to enable fast development. A new feature has been introduced to directly address portlets from within a browser; this feature is called URLAddressability.

URLAddressability enhances the concept of portlets as defined in the JSR 168 Java Portlet Specification. It adds the concept of url mappings for portlets.

To see how URLAddressability works in detail, consider our example above. You can access the World Clock portlet by entering the following line into the browsers address bar:

http://localhost:9080/worldclock/StdWorldClock

This is a standard URL with a hostname, a port, a context root, and a path. Because portlets are packaged in WAR files, we deployed it with a context root like any other servlet WAR file (in this case /worldclock). The path of the URL is based off the portlet name as defined in the portlet deployment descriptor, the portlet.xml file. In this case the portlet name is StdWorldClock. Listing 6 is a corresponding portlet.xml snippet:

			
<portlet>
	<portlet-name>StdWorldClock</portlet-name>
	...
</portlet>

Now that you have seen how this works with a concrete example you can access every portlet installed in the system by looking at the general pattern.

The following URL pattern shows the most basic URLAddressability definition that renders the portlet in View mode.

http://<host>:<port>/<context root>/<portlet name>

Comparing to WebSphere Portal

Addressing portlets is currently very different between WebSphere Portal and Application Server.

In WebSphere Portal, you cannot directly access a portlet through a URL; you must first place it on a page. After deployment, one has to use the page customizer to put the portlet on an existing page or on a newly created one. Then the portlet can be directly accessed through programmatic means such as the Portlet State API.

In Application Server, it is simpler to address a portlet, using URLAddressability. After installation it, the portlet is available right away. However, on the other hand, it provides fewer aggregation capabilities. In WebSphere Portal, many more aggregation capabilities can apply to the portlet, including dynamically changing the page layout, applying fine-grained access control, rule-based aggregation, and many more.

Now that you have learned the basics of addressing portlets, let's dive into the details of URLAddressability. You see how to call portlets in different portlet modes or windows states, and you discover where portlet preferences are stored in this scenario.

Back to top

Exploring URLAddressability

URLAddressability can be seen as a mapping of portlet features to existing HTTP and Servlet features. The window identifier, action flag, portlet modes, window states, and render parameters are defined through the URL pattern. Portlet preferences are mapped to cookies stored in the browser. In this section you learn about both in detail.

First, take a look at the complete feature set of URLAddressability. This is the general URL pattern:

http://<host>:<port>/<context>/<portlet-name> 
   [/portletwindow[/ver [/action] [/mode] [/state] [rparam]]]

We assume you are already familiar with basic addressing (beginning portion of the pattern).

• You can provide a portletwindow identifier which becomes useful as soon as multiple portlets are displayed on one page. The portletwindow can contain any arbitrary string.
• The version is always 1 (ver=1.0) because the only version currently supported is 1.0.
• The action flag defines whether the portlet action should be triggered. It appears in the URL with no additional parameter, for example: http://localhost:9080/somecontext/MyPortletName/MyWindowIdentifier/ver=1.0/action.
• The mode and state define the portlet mode and window state of the addressed portlet. Both parameters have the format mode=<mode> or state=<state>.
• Render parameters (rparam) are represented in the URL as rparam=<name>=<value>. You can code as many rparams as required (/rparam=hello=world/rparam=hello2=world2).
• The order of the parameters is defined through the url pattern as shown above and cannot be mixed.

In the previous section you saw how to access the world clock portlet in View mode.

Figure 3 shows the portlet accessed in Edit mode using this URL which applies the URLAddressibility syntax described above:

http://localhost:9080/worldclock/StdWorldClock/window/ver=1.0/mode=edit

The Edit mode lets users personalize a portlet using portlet preferences. URLAddressability stores the portlet preferences in a cookie scoped by the window identifier so that you can store the preferences with any HTTP client that supports cookies. For more information about the preferences cookie, see the WebSphere Application Server Information Center (listed in Resources).

After the user returns to the View mode, the world clock portlet looks like Figure 4.

Back to top

Conclusion

In this first part of the series, you saw a brief introduction to the portlet container in Application Server. You learned about the feature set available in the portlet container and saw where in the series we will cover these different features. You learned two ways to install portlets and how to access portlets in Application Server. You saw how you to perform similar tasks in WebSphere Portal. Finally, you examined URLAddressability in detail, which you use in Application Server to address portlets through a URL. You saw a demonstration of how URLAddressability provides a very easy and comfortable way to render and develop portlets.

In Part 2 you see advanced features of the JSR 168 portlet container in Application Server. You learn how to aggregate multiple portlets on a page, acquire information about previously deployed portlets, and change default portlet behavior.

Back to top

Download

Description	Name	Size	Download method
World clock portlet	StdWorldClock.war	75 KB	FTP|HTTP

Information about download methods

Resources

• Participate in the discussion forum.
  
  
• Best practices: Developing portlets using JSR 168 and WebSphere Portal V5.02
  
  
• Comparing the Java Portlet Specification JSR 168 with the IBM Portlet API
  
  
• Converting the WorldClock portlet from the IBM Portlet API to the JSR 168 portlet API
  
  
• Java Portlet Specification V 1.0, JSR 168
  
  
• Pluto
  
  
• Portlet development guide
  
  
• WebSphere Application Server Information Center
  
  
• WebSphere Application Server Zone
  
  
• WebSphere Portal product documentation, including the Information Center
  
  
• WebSphere Portal zone
  
  

About the authors

Stephan Hesmer is currently working as Performance Chief Developer. In his previous role he worked as Portlet Runtime architect in WebSphere Portal and WebSphere Application Server. He is responsible for integrating the JSR 168 portlet container into WebSphere Application Server. Stephan worked on the JSR 168 Java™ Portlet Specification, and designed and implemented the initial version of the JSR 168 Reference Implementation, Pluto. Stephan received a Diploma of Information Technology from the University of Cooperative Education Stuttgart, Germany, in 2000. After graduating, he joined the IBM Böblingen Development Laboratory to work in the WebSphere Portal Team.

Birga Rick is Technical Lead for WebSphere Application Server Portlet Runtime at the IBM Boeblingen Lab in Germany. In 2003, she was part of the team implementing the JSR168 Reference Implementation, Pluto. Following her work on JSR 168 within the WebSphere Portal development team, she integrated the Portlet Runtime into WebSphere Portal and WebSphere Application Server.

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• When to use the Application Server portlet container
• About the sample portlet
• Portlet container features summary
• Installing a portlet
• Accessing and addressing portlets
• Exploring URLAddressability
• Conclusion
• Download
• Resources
• About the authors
• Comments

Local resources

• IBM Innovation Center - Austin, TX
• IBM Innovation Center - Chicago, IL
• IBM Innovation Center - Dallas, TX
• IBM Innovation Center - San Mateo, CA
• IBM Innovation Center - Waltham, MA
• Technical Briefings in North America

My developerWorks community

Dig deeper into WebSphere on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers