Skip to main content

By clicking Submit, you agree to the developerWorks terms of use.

The first time you sign into developerWorks, a profile is created for you. Select information in your profile (name, country/region, and company) is displayed to the public and will accompany any content you post. You may update your IBM account at any time.

All information submitted is secure.

  • Close [x]

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerworks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

By clicking Submit, you agree to the developerWorks terms of use.

All information submitted is secure.

  • Close [x]

developerWorks Community:

  • Close [x]

Exploiting the WebSphere Application Server V6.1 portlet container: Part 1: Introducing the portlet container

Stephan Hesmer (stephan.hesmer@de.ibm.com), Performance Chief Developer, IBM
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 (brick@de.ibm.com), Portlet Runtime Technical Lead, IBM
Author photo
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.

Summary: 

This article series examines the JSR 168 portlet container available in IBM WebSphere Application Server V6.1 and differentiates its use from WebSphere Portal.

This first part in the series provides an introduction to the portlet container. Specifically, you learn how to install a portlet, how to access it, and how to use URLAddressability. You can download an example portlet and use it to see the features of the WebSphere Application Server V6.1 portlet container.

This article is for Java™ portlet programmers who are already familiar with the Java Portlet API. See Resources for links to information that can help you gain those skills.

View more content in this series

Date:  05 Jul 2006
Level:  Intermediate
Also available in:   Chinese  Korean  Japanese

Activity:  21757 views
Comments:  

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.


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.


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) .


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.


Table 1: Key portlet container features
Main Topic / FeatureDescriptionExplained in …
Addressability
URLAddressabilityURLAddressability enables directly accessing and rendering of a portlet in a browser page, without decorations, by a simple URL request. You can invoke a portlet by its context root and name, exactly the same way that you can invoke servlets. Example: http://localhost:9080/portlets/StdWorldClockPart 1
AggregationAggregation is supported through a Java Server Page tag library. The tag library provides basic capabilities which can be easily applied and used to aggregate multiple portlets on a page.Part 2
Manageability
Portlet Install / wsadminYou can easily install a portlet using existing mechanisms in Application Server. You can configure the portlet container using either wsadmin or the Administrative Console.Part 1
Portlet MBean APIThrough the Portlet MBean API an application has access to the data of all portlets & portlet applications. It is an essential ingredient for managing applications or portals.Part 3
Extended Deployment DescriptorAdditional features beyond the JSR 168 Java Portlet Specification are stored and configured in the extended deployment descriptor. For example, you could access this configuration to switch the URLAddressability feature on and off.Part 3
CachingThe Application Server dynacache infrastructure has been enhanced to support portlet fragment caching. This support is an extension of the servlet fragment caching with a few additional options.Part 3
Performance MetricsYou can enable the portlet container to emit performance measurements on currently running portlets that are viewable within the Performance Viewer. This includes Performance Measurement Instrumentation (PMI) and Request Metrics.Part 3
Extensibility
PortletDocumentFiltersIn order to support markups other than HTML, or to decorate a portlet fragment, you can extend the portlet container with PortletDocumentFilters, a Servlet Filter based API which enables easy development and deployment.Part 2

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


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.


Figure 2. The world clock portlet in View mode

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.


Table 2: Differences in installing portlets
TopicWebSphere Application ServerWebSphere Portal
Administrative ConsoleWeb interface based on servlets. Use to install portlet EAR and WAR files.Web interface based on portlets. Use to install portlet WAR files only.
Scripting InterfaceSupports direct interaction using a command line or scripts written in JACL and Python. Use to install EAR and WAR files.XML based scripting environment. Use to install WAR files or pre-deployed EAR files. Another scripting interface of WebSphere Portal, called wpscript is very similar to wsadmin but it does not support installation of portlets.

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.


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:


Listing 6. A 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.


Table 3: Differences in addressing portlets
TopicWebSphere Application ServerWebSphere Portal
Addressing portletsEach portlet is directly accessible using URLAddressability.A portlet can only indirectly be accessed by putting it on a page using the page customizer. Therefore it provides many aggregation capabilities on top.

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.


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


Figure 3. The world clock portlet in Edit mode
The world clock portlet in Edit mode

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.


Figure 4. The world clock portlet in View mode using portlet preferences
The world clock portlet in View mode using portlet preferences

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.



Download

DescriptionNameSizeDownload method
World clock portletStdWorldClock.war75 KBFTP|HTTP

Information about download methods


Resources

About the authors

Stephan Hesmer

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.

Author photo

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.

Report abuse help

Report abuse

Thank you. This entry has been flagged for moderator attention.


Report abuse help

Report abuse

Report abuse submission failed. Please try again later.


developerWorks: Sign in


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Select information in your profile (name, country/region, and company) is displayed to the public and will accompany any content you post. You may update your IBM account at any time.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


Rate this article

Comments

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=144081
ArticleTitle=Exploiting the WebSphere Application Server V6.1 portlet container: Part 1: Introducing the portlet container
publish-date=07052006
author1-email=stephan.hesmer@de.ibm.com
author1-email-cc=
author2-email=brick@de.ibm.com
author2-email-cc=