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

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

Part 1 introduced the portlet container and described how to install and access a portlet, and how to use URL Addressability.

Part 2 illustrated some extended capabilities of the container including how to render a portlet within a window frame, display multiple portlets, get information about deployed portlets, and change the default portlet behaviour.

In this part, you learn how to administer the JSR 168 portlet container in WebSphere Application Server. You see how to configure and use portlet caching capabilities, performance metrics, and the extended deployment descriptor. You can download example code that accompanies this series and illustrates many of features of the WebSphere Application Server V6.1 portlet container.

This series is for Java™ programmers, portlet programmers, and Web administrators who are familiar with the Java Portlet API. See Resources for links to information that can help you gain those skills.

Stephan Hesmer (stephan.hesmer@de.ibm.com), Performance Chief Developer, IBM

Stephan HesmerStephan 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 photoBirga 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.



30 August 2006

Also available in Japanese

Introduction

IBM WebSphere Application Server V6.1 provides a feature-rich systems management and administration framework which supports a scripting interface ( wsadmin), MBeans, performance metrics, and so on. The portlet container in WebSphere Application Server is embedded into this framework, and you can manage it using the same, standard techniques you use for other WebSphere components.

This article shows you how to administer the portlet container and installed portlets. You examine the extended portlet deployment descriptor features and learn how to modify it using the scripting interface. Next, you dive into the caching capabilities of the portlet container and individual portlets. You see how to configure portlet-specific cache values using cachespec.xml and so on. Finally, you learn about performance techniques, and how to enable and use them. And, throughout this article you see how each feature discussed compares to similar functionality in WebSphere Portal so that you are aware of the differences and will know how to achieve the same end result in both products.

This article series is for developers and architects who would like to use the portlet container in WebSphere Application Server as a development platform and don’t know WebSphere Portal. 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 move of the container down the stack.


About the sample

You can download the sample code for the world clock example, and refer to it as you read the this article.


Caching

Caching is a important technique for improving the performance of a system. The portlet and web containers in WebSphere Application Server both support server-side caching. With server-side caching, the content of a servlet or portlet is stored in a local cache on the server so that further requests do not need to run the servlet or portlet.

Portlet caching is more complex than servlet caching because portlet fragments contain links pointing to the full page. However, in order to be cachable fragments, they must only contain artifacts with the scope of the fragment. The challenge for portal frameworks is to only cache the fragment without any dependencies on artifacts outside of the fragment.

With WebSphere Portal, the fragments are assembled later using its aggregation framework. The portlet container in WebSphere Application Server also takes care of such complexities; it factors out content which has a scope that is different from the fragment, and then re-assembles the complete content whenever cached content is requested again.

This section shows how you can turn on portlet fragment caching using the administrative console or with the scripting interface. At the end of this section, you how to use the WebSphere Application Server cache monitor with an example portlet in a demonstration of the cache infrastructure.

Using the 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 navigate to your server, such as server1, and then to the Portlet container.
  3. Select the check box for enabling portlet fragment caching as shown in Figure 1.
  4. Restart the server to activate the caching.
Figure 1. Enabling portlet fragment caching in the Administrative Console
Figure 1. Enabling portlet fragment caching in the Administrative Console

Using the scripting interface

Another way you can turn on portlet fragment caching is by using the scripting interface, wsadmin.

  1. First, start wsadmin so that is connects to the server. You see this message: C:\WebSphere\bin>wsadminWASX7209I: Connected to process "server1" on node HESMERT40Node02 using SOAP connector;The type of process is: UnManagedProcess
  2. In the command prompt, you enter the following commands to enable portlet fragment caching. Important: Always use forward slashes, even on a Windows system. wsadmin>set server [$AdminConfig getid /Server:server1/]

wsadmin>set pc [$AdminConfig list PortletContainer $server]wsadmin>$AdminConfig modify $pc {{enablePortletCaching true}}

  1. Save the configuration. wsadmin>$AdminConfig save
  2. Restart the server to activate the caching.

Using the cache monitor

WebSphere Application Server provides a cache monitor application along with its binaries. It enables administrators and developers to look more closely at the caches used within the system. Statistics such as the cache size, used entries, cache hits and misses, and many more provide a good overview of their usage patterns.

In the previous sections, you learned how to enable portlet fragment caching. Now, to see how it works, you install two applications to use in an example scenario that follows. You install:

  • The StdWorldClockCache.war, available as a download with this article
  • The CacheMonitor.ear, in the <WAS-HOME>/installableApps directory

The example application, StdWorldClockCache.war, differs from ordinary portlet applications; it includes an additional element in the portlet.xml and it includes a cachespec.xml file.

Within the portlet.xml, an optional element, expiration-cache, helps to improve performance. The expiration-cache element specifies the duration, in seconds, that a cache considers the portlet fragment to be "fresh". As long as the fragment is considered fresh, it is returned out of the cache; otherwise, the portlet is called again to retrieve a new fragment.

The following snippet shows the expiration-cacheelement and where to place it within portlet.xml.

<portlet-name>StdWorldClock</portlet-name>
<portlet-class>com.ibm.wps.portlets.worldclock.WorldClockController</portlet-class>
<expiration-cache>130</expiration-cache>
<supports>

The second cache component is the cachespec.xml, a file which is specific to WebSphere Application Server and is not used in WebSphere Portal. In Version 6.1 of WebSphere Application Server this file must be in the WEB-INF directory to turn on caching. If this file is not available, the portlet fragment will not be cached.

In addition to specifying the cache expiration in portlet.xml, the cachespec.xml file lets you define additional cache settings for a given portlet, such as caching by portlet mode. See the WebSphere Application Server Information Center for more information.

The following snippet shows a simple cachespec.xml. For more information about the specific elements used within the xml file, see the WebSphere Application Server Information Center.

<cache>
 <cache-entry>
      <class>portlet</class>
      <name>StdWorldClock</name>      
      <property name="consume-subfragments">true</property>
      <cache-id/>
  </cache-entry></cache>

After both applications have been successfully installed and started, you can use the Cache Monitor to look at statistics for the World Clock portlet.

  1. Open the Cache Monitor web interface. For example, if your server is local, open in a browser: http://localhost:9060/cachmonitor
  2. Select Cache Statistics on the left, and you see a window as shown in Figure 2.
    Figure 2. Cache Monitor Application showing cache statistics of the selected cache
    Figure 2. Cache Monitor Application showing cache statistics of the selected cache
  3. Next, access the WorldClock portlet by opening the following URL in a browser: http://localhost:9080/worldclock/StdWorldClock
  4. Figure 3 shows a clip of the resulting picture being rendered. Note the time on the screenshot; you will need to know it to compare to some data you see later.
    Figure 3. Clip of the World Clock portlet showing the current time
    Figure 3. Clip of the World Clock portlet showing the current time
  5. Switching to the cache monitor, you see the new cache statistics as shown in Figure 4. Because you have accessed the portlet only once, you had a "cache miss"; therefore, the cache was then filled with the fragment and is ready to serve any future requests.
    Figure 4. The new cache statistics after accessing the portlet the first time.
    Figure 4. The new cache statistics after accessing the portlet the first time.
  6. Now, go back to the World Cock portlet, and click Reload in its browser window. You need to do this within 130 seconds; otherwise, the cache will expire. To tell whether the caching worked, look at the time stamp shown in the markup; it should be the same as what you observed earlier.
  7. Again, switch to the cache monitor, and you see the new cache statistics as shown in Figure 5. Because you accessed the portlet within 130 seconds, the system still had a valid cache entry ("cache hit"), and so it serves the portlet fragment out of the cache.
    Figure 5. The new cache statistics after accessing the portlet the second time
    Figure 5. The new cache statistics after accessing the portlet the second time
    Figure 6. The new cache statistics if you access the portlet twice within 130 seconds
    Figure 6. The new cache statistics if you access the portlet twice within 130 seconds
  8. After 130 seconds, go back to the World Cock portlet, and click Reload in its browser window. This time the cache should not be fresh anymore, and must, therefore re-render the portlet. As shown in Figure 7, a new time stamp is rendered. Also, in Figure 8, you see a new "cache miss" show up.
    Figure 7. Clip of the World Clock portlet showing the new current time
    Figure 7. Clip of the World Clock portlet showing the new current time
    Figure 8. The new cache statistics if we access the portlet multiple times within 130 seconds
    Figure 8. The new cache statistics if we access the portlet multiple times within 130 seconds

WebSphere Application Server and WebSphere Portal both provide portlet fragment caching capability. Both environments take care of the fact that multiple portlets are usually aggregated on a page, and they take special precautions as explained above. The extended cache id generation through the cachespec.xml in WebSphere Application Server is not yet available in WebSphere Portal. The built-in cache id generation in WebSphere Portal cannot yet be changed by a developer or the portlet. On the other hand, WebSphere Portal supports a feature-rich, page-level caching capability, where the aggregation framework considers the cache settings, such as expiration, of every fragment on the page and aggregates that information into page cache settings. As a result, the page can be cached in reverse proxies and browser caches with the maximum time possible.

Comparing to WebSphere Portal
TopicWebSphere Application ServerWebSphere Portal
Portlet fragment caching Available Available
Cache ID generation Customizable by the developer Not customizable
Page level caching Not available. Can be developed on top of portlet container. Available out-of-the-box

Performance Monitoring Infrastructure

A performance problem with a system is often very hard to solve. In many cases, you can only find a solution by analyzing measurements of the system (such as response time or errors that might have occurred). The Performance Monitoring Infrastructure, or PMI, is a very handy tool within WebSphere Application Server that can help in exactly this kind of situation. It lets you take various performance metrics and then observe over time to find performance problems.

The portlet container provides a couple of additional performance metrics very similar to the servlet metrics. These are:

  • Number of portlet request
  • Number of current portlet requests
  • Response times of portlet render requests
  • Response times of portlet action requests
  • Number of portlet errors

Fo more information about the metrics and their meaning see the WebSphere Application Server Information Center.

You can enable and leverage PMI using the administrative console and the scripting interface. Let's use the example portlet to see how to use PMI.

Using the 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, navigate to Monitoring and Tuning => Performance Monitoring Infrastructure (PMI) , and then select your server; in this example, we select server1.
  3. Next, if it is not already checked, select the check box for enabling performance monitoring infrastructure, and then restart the server to activate PMI.
  4. After you have enabled PMI, you can enable portlet metrics. For now, you must do so on the Runtime tab, as shown in Figure 9. This means that the information is not stored persistently and will be lost after server restart. This will be fixed in one of the service releases.
    Figure 9. Enabling portlet metrics in the Administrative Console can only be done on the Runtime tab
    Figure 9. Enabling portlet metrics in the Administrative Console can only be done on the Runtime tab
  5. On the Runtime tab, select Custom for fine-grained control, which lets you selectively enable statistics.
  6. On the Custom monitoring level page, select the metrics you would like to enable. The Status column shows whether a metric is enabled or not. Figure 10 depicts how the table looks when all metrics for portlets are enabled.
    Figure 10. All portlet metrics are enabled
    Figure 10. All portlet metrics are enabled
  7. Now, you can use the Performance Viewer. Navigate to Monitoring and Tuning => Performance Viewer => Current Activity, and then select your server; for example, server1.
  8. A window with two frames displays. On the left, a tree lets you navigate through different reports and modules. To measure and observe the portlet metrics, you first need to tell the PMI which portlet you are interested in. Therefore, select Performance Modules => Web Applicationsin the tree. Below Web Applications, you find the installed web applications, including portlets. Select any portlet you wish to monitor. In the example shown in Figure 11, we've selected to monitor the World Clock portlet.
    Figure 11. Enabled Performance Modules for the standard world clock portlet
    Figure 11. Enabled Performance Modules for the standard world clock portlet
  9. You can see the metrics displaying in the Performance Viewer. (If they do not yet show up, click the View Module(s) at the top of the screen.) You see a graph and a table in the right frame of the Performance Viewer, as shown in Figure 12. To see some real values, open another browser window and work with the monitored portlet.
    Figure 12. Performance Viewer showing the current measurements of the portlet metrics
    Figure 12. Performance Viewer showing the current measurements of the portlet metrics

Comparing to WebSphere Portal

Because of the high complexity of portal setups and environments, WebSphere Portal delegates performance monitoring, reporting, and diagnosis to other products such as IBM Tivoli Composite Application Management (ITCAM) for WebSphere. It includes both WebSphere Application Server and specific WebSphere Portal monitoring features.

In contrast to WebSphere Application Server, which provides a simple and easy monitoring infrastructure out-of-the-box, Tivoli Composite Application Management goes beyond the basics and supports many more performance metrics, reports, and ways to diagnose your system.


Request Metrics

Request Metrics is a measurement and diagnosis tool which is similar to the WebSphere Application Server Performance Monitoring Infrastructure (PMI). It is based on Application Response Measurement (ARM) and helps you analyze a single request in detail. PMI lets you diagnose and monitor different system entities (such as servlets or portlets); the Request Metrics tool provides a detailed view of a single request and how it travels through all affected components of the system. While the request moves through the system, the Request Metrics tool records the times and certain attributes for each component. You get a very good overview of how much processing and elapsed time a certain component takes during the request. For more information about the metrics and their meaning, see the WebSphere Application Server Information Center.

Now you see how to enable and leverage the Request Metrics tool using the administrative console and the scripting interface. We use an example portlet to demonstrate how you can use Request Metrics.

Using the administrative console

  1. Open the WebSphere Administrative Console.
  2. Log in and navigate to Monitoring and Tuning => Request Metrics (PMI).
  3. If it is not already checked, select the check box for enabling Request Metrics, and restart the server to activate the Request Metrics tool.
  4. After you have enabled Request Metrics, to enable portlet metrics, select Custom=> Portlet. For the Request Metrics Destination, select Standard Logs to an easy first glance at the metrics.
Figure 13. Enabled Portlet Metrics in the administrative console
Figure 13. Enabled Portlet Metrics in the administrative console

In order to see a few request mMetrics in the standard log, use the World Clock portlet again. The following listing shows the corresponding Request Metrics logs after we hit the portlet action method and render method of the World Clock portlet.

SRVE0180I: [StdWorldClock_war#StdWorldClock.war] [/worldclock] [Servlet.LOG]:
  WorldClockController(processAction): entering processAction()...
SRVE0180I: [StdWorldClock_war#StdWorldClock.war] [/worldclock] [Servlet.LOG]:
  WorldClockController(processAction): saving changes ...
PMRM0003I:  parent:ver=1,ip=192.168.0.102,time=1148825019859,pid=2084,reqid=8211,event=1
  - current:ver=1,ip=192.168.0.102,time=1148825019859,pid=2084,reqid=8211,event=1 
  type=Portlet detail=action elapsed=60
						
SRVE0180I: [StdWorldClock_war#StdWorldClock.war] [/worldclock] [Servlet.LOG]:
  WorldClockController(doView): entering doView()...
PMRM0003I:  parent:ver=1,ip=192.168.0.102,time=1148825019859,pid=2084,reqid=8214,event=1
  - current:ver=1,ip=192.168.0.102,time=1148825019859,pid=2084,reqid=8214,event=1 
  type=Portlet detail=render elapsed=50

Every Request Metrics message contains the IP address, timestamp, process id, request id, event type, and elapsed time. The portlet related data is marked in bold in the listing above; it consists of the method type (detail) and the elapsed time in milliseconds. If one of the methods had taken considerably longer in elapsed time, You might look at this particular portlet and scenario as a potential performance problem.

Using the scripting interface (wsadmin)

Another way to install a portlet is to use the scripting interface, wsadmin.

  1. First, start wsadmin so that is connects to the server. You see this message:

    Click to see code listing

    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, enter the following command to install the portlet.

    Important: Always use forward slashes, even on a Windows system

    wsadmin>set pmi [$AdminConfig list PMIRequestMetrics]

    wsadmin>$AdminConfig modify $pmi {{enabledComponents {}}}
    wsadmin>$AdminConfig modify $pmi {{enable true} {enableLog true} {enabledComponents Portlet}}
  3. Save the configuration.
    wsadmin> $AdminConfig save

After saving the configuration, you might need to restart the server before you can use the portlet metrics. Then, you can access the World Clock portlet which produces the Request Metrics logs, as shown in the previous section.

Comparing to WebSphere Portal

Because of the complexity of portal setups and environments, WebSphere Portal delegates response measurement, reporting, and diagnosis to additional feature-rich products such as ITCAM.

In contrast to WebSphere Application Server, which provides a simple and easy measurement infrastructure out-of-the-box, ITCAM goes beyond the basics and supports many more performance metrics, reports, and ways to diagnose your system.


Extended deployment descriptor

In Part 1 of this article series, you learned about URLAddressability and its ability to serve portlets directly to the browser. In a few instances, you would like to turn this feature off. For example, you might have security reasons that require you only allow access to the portlet through a portal framework such as the Integrated System Console (ISC) and WebSphere Portal.

To turn off URLAddressability, you need to put a new file, ibm-portlet-ext.xmi, into the WEB-INF directory and redeploy the portlet application. The following snippet demonstrates how such a file looks. You set the attribute portletServingEnabled to false to turn off portlet serving.

<?xml version="1.0" encoding="UTF-8"?>
<portletappext:PortletApplicationExtension xmi:version="1.0"
    xmlns:xmi="http://www.omg.org/XMI"
    xmlns:portletappext="portletapplicationext.xmi"
    xmlns:portletapplication="portletapplication.xmi"
    xmi:id="PortletApp_ID_Ext"
    portletServingEnabled="false">
  <portletappext:portletApplication href="WEB-INF/portlet.xml#worldclock_app_id"/>
</portletappext:PortletApplicationExtension>

Extended deployment descriptors are used in various products to extend standard or existing deployment descriptors. WebSphere Portal defines various extensions to the portlet deployment descriptor in a similar fashion to WebSphere Application Server. The extensions are defined in the file ibm-portal-portlet-ext.xmi within the WEB-INF directory and provide a means to control the behavior of WebSphere Portal with regards to portlets. Both files, from WebSphere Portal and WebSphere Application Server, can co-exist at the same time because they do not collide in name or in functionality.

Comparing to WebSphere Portal
TopicWebSphere Application ServerWebSphere Portal
File name ibm-portlet-ext.xmi ibm-portal-portlet-ext.xmi
Features URLAddressability, on/off Extended caching, shared caching anonymous session, turn on/off

Conclusion

In this part of the series, you learned about performance relevant topics that are available when you use the portlet container in WebSphere Application Server. You looked at portlet caching in detail, and saw how portlet caching can be leveraged and applied to portlets. You used performance monitoring and measurement techniques to understand performance bottlenecks better, and you learned how to configure them using either the Administrative Console or the scripting interface.

In the next part of the series, you see how the extended portlet programming model of WebSphere Portal compares to WebSphere Application Server. We'll use an example to demonstrate which portlets can be deployed and run on both platforms, and which ones run only on one platform.


Download

DescriptionNameSize
World clock portletStdWorldClock.war75 KB

Resources

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


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. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

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.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

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

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=156819
ArticleTitle=Exploiting the WebSphere Application Server V6.1 portlet container: Part 3: Administering the portlet container
publish-date=08302006