Portal Guide

CHAPTER 15

Asynchronous Portlet Processing

This chapter describes exteNd Director support for asynchronous portlet processing. The following topics are covered:

• About asynchronous processing

• Who should use asynchronous processing?

• Setting up your environment for asynchronous processing

• Configuring the application server for asynchronous portlet rendering

• Properties that control asynchronous portlet rendering

• Enabling asynchronous portlet rendering in the portal

• Synchronous versus asynchronous processing

• Fine-tuning request timeout behavior

About asynchronous processing

When portlets run asynchronously, they render their content in parallel. When a portal administrator enables asynchronous processing for the portal, exteNd Director manages asynchronous portlet render requests as shown in this diagram:

By default, the exteNd Director portal assigns each asynchronous render request to its own thread in the portlet thread pool. When all threads in the pool have been assigned, incoming asynchronous render requests are delegated to the main request thread, as described in The main request thread.

Asynchronous threads become available when the portlets assigned to them finish execution. At that time, the portal transfers pending asynchronous render requests out of the main thread to the next available individual thread in the pool, beginning with the oldest request.

Synchronous render requests are processed sequentially in the main request thread by default. However, portal administrators can configure the portal to allocate a separate thread for processing synchronous render requests, thereby preventing bottlenecks in the main request thread. See Properties that control asynchronous portlet rendering.

The portal waits for each portlet on a page to complete its render operation or to time out (whichever comes first), then aggregates the rendered output onto the page.

The main request thread   The main request thread is the application server thread that processes client requests. The following portlet requests execute in the main thread by default:

• All portlet action requests

• Synchronous portlet render requests

In addition, asynchronous render requests may be delegated to the main request thread if no threads are available in the portlet thread pool, as described in About asynchronous processing.

Who should use asynchronous processing?

Asynchronous portlet processing is an advanced feature that should be used only by portlet developers and administrators who are experienced in the following areas:

• Servlet containers and portlet containers

• J2EE

• Transaction processing

• Multithreaded programming

Setting up your environment for asynchronous processing

To set up the runtime environment for asynchronous portlet rendering, the following tasks must be completed:

1. Portlet administrator configures the application server for asynchronous portlet rendering, as described in Configuring the application server for asynchronous portlet rendering.

2. Portlet administrator enables asynchronous rendering for the portal, as described in Properties that control asynchronous portlet rendering.

3. Portlet developer determines whether individual portlets should render content synchronously or asynchronously, as described in Synchronous versus asynchronous processing.

4. Portlet administrator fine-tunes request timeout behavior, as described in Fine-tuning request timeout behavior.

Configuring the application server for asynchronous portlet rendering

exteNd Director provides varying levels of support for asynchronous portlet rendering on the following servers when they are configured appropriately

Configuring the Novell exteNd Application Server for asynchronous portlet rendering

To configure the Novell exteNd Application Server for asynchronous portlet rendering:

1. Open your portal application project.

2. Open the deployment plan for your portal application project.

3. If prompted to build your project, you can select No don't build now and click OK.

4. Search for the <warJar> element.

   TIP:   It may be easier to find the <warJar> element if you switch from Descriptor view to XML view.

5. After the <warJar> descriptor (under </warJar>, add an element called <backgroundThreadMax> and set it to the maximum number of threads each Web application can use from the application server's thread pool.

   For example, if you want to enable up to 15 threads, enter the following descriptor:

     <backgroundThreadMax>15</backgroundThreadMax>
   

   NOTE:   If you do not add the <backgroundThreadMax> element,

6. Save the deployment plan.

7. Redeploy the portal application.

Now you are ready to turn on asynchronous portlet rendering in the portal. See Properties that control asynchronous portlet rendering.

Configuring the IBM WebSphere server for asynchronous portlet rendering

To configure the IBM WebSphere server for asynchronous portlet rendering:

1. Create a new Work Manager for your server and give it a name for the portal application.

   Consult your WebSphere documentation for the correct procedure.

2. Open your portal application project.

3. Open the Portal subsystem configuration file.

4. Add the following property:

     com.novell.afw.portal.aggregation.work.workmanager
   

5. Set the value of the property to the JNDI name of the Work Manager you created in Step 1.

   For example if the JNDI name of the Work Manager is PortalWorkManager, you should add the following property to the Portal configuration file:

     <property>
        <key>com.novell.afw.portal.aggregation.work.workmanager</key>
        <value>PortalWorkManager</value>
     </property>
   

6. Save the Portal subsystem configuration file.

7. Redeploy the portal application.

Now you are ready to turn on asynchronous portlet rendering in the portal. See Properties that control asynchronous portlet rendering.

Configuring BEA WebLogic and Apache Tomcat servers for asynchronous portlet rendering

To configure BEA WebLogic or Apache Tomcat servers for asynchronous portlet rendering:

1. Open your portal application project.

2. Open the Framework subsystem configuration file.

3. Assign values for the following thread pool properties:

   Property	Description	What to specify
   com.sssw.fw.api.threadpool.buffersize	Defines how many portlet render requests should be buffered if the pool is busy. Once this limit is reached, the pool will no longer accept new render requests until it frees up again. Incoming requests will be diverted to the calling thread. In the case of the exteNd Application Server, this is the server's client thread.	Integer
   com.sssw.fw.api.threadpool.maxthreads	The maximum number of threads to which the thread pool can grow.	Integer
   com.sssw.fw.api.threadpool.minthreads	The minimum number of threads that will always be kept in the pool.	Integer
   com.sssw.fw.api.threadpool.initialthreads	The number of threads immediately available in the pool after the pool has been started.	Integer
   com.sssw.fw.api.threadpool.keepalifetime	The time (in milliseconds) a thread will be kept alive when it is idle.	Integer number of milliseconds
   com.sssw.fw.api.threadpool.enabled_at_startup	Determines whether the thread pool is enabled. This property must set to true if you want the thread pool to be enabled. If the thread pool is disabled, all parallel processing defaults to synchronous processing	true

   For example, here are the default values for these properties in the Framework subsystem configuration file:

     <!-- thread pool settings -->
     	 <property>
     	 	 <key>com.sssw.fw.api.threadpool.buffersize</key>
     	 	 <value>10</value>
     	 </property>
     	 <property>
     	 	 <key>com.sssw.fw.api.threadpool.maxthreads</key>
     	 	 <value>100</value>
     	 </property>
     	 <property>
     	 	 <key>com.sssw.fw.api.threadpool.minthreads</key>
     	 	 <value>4</value>
     	 </property>
     	 <property>
     	 	 <key>com.sssw.fw.api.threadpool.initialthreads</key>
     	 	 <value>10</value>
     	 </property>
     	 <property>
     	 	 <key>com.sssw.fw.api.threadpool.keepalifetime</key>
     	 	 <value>300000</value>
     	 </property>
     	 <property>
     	 	 <key>com.sssw.fw.api.threadpool.enabled_at_startup</key>
     	 	 <value>true</value>
     	 </property>
   

4. Save the Framework subsystem configuration file.

5. Redeploy the portal application.

Now you are ready to turn on asynchronous portlet rendering in the portal. See Properties that control asynchronous portlet rendering.

Properties that control asynchronous portlet rendering

The portal uses the following properties to manage asynchronous portlet rendering:

Scenarios for asynchronous portlet rendering

This section describes the effects of each configuration of property values. Note that Parallel portlet render enabled must be enabled in order for the other properties to have any effect..

Enabling asynchronous portlet rendering in the portal

Portal administrators must enable asynchronous portlet rendering in the portal in order for individual portlets to render content in parallel. Otherwise all portlets render content synchronously in the main request thread.

Portal administrators can enable asynchronous processing for the duration of a server session or permanently across server sessions.

Enabling asynchronous portlet rendering for a server session

The portal administrator uses the Director Administration Console (DAC) to turn on asynchronous portlet rendering for the duration of the server session. This means that the settings remain in effect until you restart the server or redeploy the application. Then, asynchronous rendering defaults back to the disabled state.

To persist asynchronous render settings across server sessions, see Enabling asynchronous portlet rendering across server sessions.

To enable asynchronous portlet rendering for the duration of a server session:

1. Start the DAC, as described in accessing the DAC.

2. Click the Portal Management button:

   

   A list of portal settings appears in your browser.

3. Select the check box Parallel portlet render enabled.

   IMPORTANT:   The portal administrator must enable this property to turn on asynchronous rendering in the portal. If this property is disabled, portlets will not render content in parallel, even if portal developers enable asynchronous rendering for individual portlets, as described in Enabling portlets to render content synchronously.

4. Enable or disable Force portlet render timeout and force synchronous portlet serial rendering as described in Properties that control asynchronous portlet rendering.

5. Click Save.

Enabling asynchronous portlet rendering across server sessions

To persist asynchronous portlet render settings across server sessions, the portal administrator must add and set the following properties to the Portal subsystem configuration file:

    For a description of these properties, see Properties that control asynchronous portlet rendering.

To persist asynchronous portlet rendering across server sessions

1. Open your portal application project.

2. Open the Portal subsystem configuration file.

3. Enable asynchronous portlet rending by adding and setting the parallel_enabled property descriptor as follows:

     <property>
        <key>com.novell.afw.portal.aggregation.parallel_enabled</key>
        <value>true</value>
     </property>
   

4. Add and set the <force_render_timeout> and <serial_synch_render> elements as described in Properties that control asynchronous portlet rendering.

   In this example, both properties are disabled:

     <property>
        <key>com.novell.afw.portal.aggregation.force_render_timeout</key>
        <value>false</value>
     </property>
     <property>
        <key>com.novell.afw.portal.aggregation.serial_synch_render</key>
        <value>false</value>
     </property>
   

5. Save the Portal subsystem configuration file.

6. Redeploy the portal application.

Synchronous versus asynchronous processing

Portlet developers can set individual portlets to render content synchronously or asynchronously.

To determine the appropriate mode for rendering content, portal developers should consider the characteristics of each portlet. If a portlet does not use a lot of CPU time and does not call external sources, it should be configured to render content in synchronous mode.

To configure the individual portlets to run synchronously, see Enabling portlets to render content synchronously.

Enabling portlets to render content asynchronously

When developers create portlets using the exteNd Director Portlet Wizard, the portlets are configured for asynchronous content rendering by default. However, portlets render content asynchronously at runtime only if a portal administrator has enabled parallel portlet rendering in the portal, as described in Enabling asynchronous portlet rendering in the portal.

Enabling portlets to render content synchronously

exteNd Director defines a property called synchronous for configuring individual portlets to render content serially. The portlet developer turns on serial rendering by adding and enabling the synchronous property in the portlet descriptor

To enable synchronous content rendering for individual portlets:

1. Open the project that contains the portlet of interest.

2. Open the project's novell-portlet.xml or its portlet fragment deployment descriptor.

3. Find the descriptor for the portlet of interest.

4. Add the <synchronous> element to the portlet descriptor and set it to a value of 1 to enable synchronous processing. The entry should look like this:

     <synchronous>1</synchronous>
   

   TIP:   If you want to re-enable asynchronous processing, either remove the synchronous element or set it to 0, as follows:

     <synchronous>0</synchronous>
   

5. Save novell-portlet.xml or the portlet fragment deployment descriptor.

       For more information about the <synchronous> element, see A look inside novell-portlet.xml.

Fine-tuning request timeout behavior

In certain runtime situations, portlets may time out before they have a chance to render their content. For example, an asynchronous portlet may time out while waiting for an individual request thread to become available.

To optimize the performance of your portal application, exteNd Director provides a number of properties for fine-tuning portlet request timeout behavior. The request timeout is governed by an interaction between settings in the portal and settings for individual portlets, as described in How the request timeout is determined.

Request timeout settings in the portal

The Portal subsystem configuration file includes several properties that control request timeout behavior for the portal as a whole:

Portlet max-timeout setting

The novell-portlet.xml file includes a property called max-timeout that determines the maximum timeout interval for each portlet, as in this example:

  <portlet name="StockQuotePortlet">
   <style>
    <name>StockQuotePortletDefault</name>
    <display-name>Default StockQuote Portlet Style</display-name>
    <user-agent>
     <device-name>Generic_HTML</device-name>
     <file-name>$RESOURCE_SET$/portlet-style/StockQuote.xsl
     </file-name>
    </user-agent>
   </style>
    <requires-authentication>0</requires-authentication>
    <auto-register enabled="true">
     <category>General Portlets</category>
    </auto-register>
    <max-timeout>1000</max-timeout>
  </portlet>

The max-timeout property sets the maximum time (in milliseconds) that the Portal should wait for a portlet's render request to finish.

NOTE:   A value of 0 is interpreted as -1, which indicates that this portlet does not have a timeout value and the default request timeout will be applied.

How the request timeout is determined

The timeout of a request is determined as follows:

1. The timeout of each asynchronous portlet is read and the greatest value is determined.

2. If the value from Step 1 is between the default_request_timeout and the max_request_timeout, it will be used as this request's maximum timeout.

3. If the value from Step 1 is below the default_request_timeout, the timeout for this request will be set to the default_request_timeout.

4. If the value from Step 1 is above the max_request_timeout value, the max_request_timeout value will be used as the timeout value for the current request.

The max_request_timeout setting applies to synchronous portlets, as well as asynchronous portlets. Since synchronous portlets are processed sequentially, the timeout is checked after each portlet returns. If the max_request_timeout value is reached, no new render process is started and the default timeout message is used as the portlet's content for all remaining, unprocessed synchronous portlets.

NOTE:   You should not confuse the request timeout settings with the expiration cache setting in the portlet.xml file. The expiration cache setting is used for content caching.

Copyright © 2004 Novell, Inc. All rights reserved. Copyright © 1997, 1998, 1999, 2000, 2001, 2002, 2003 SilverStream Software, LLC. All rights reserved.  more ...