Configure portlet filtering using IBM API

A portlet filter enables the administrator of a portal to intercept and modify the output of a portlet before it is aggregated to the entire portal page. Thus it is possible to support different languages and markups other than those for which the portlet was originally designed. Portlet filters are also used for adding additional information to the portlet output (for example, a copyright statement), deleting unimportant or restricted content, and for parsing destructive JavaScript.

To use portlet filters, portlet filtering must be enabled for the portal, the portlet filters must be defined and activated in a properties file, and the filters must be assigned to the portlet.

Using this portlet filter only applies to the IBM API. For portlets written against the JSR 286 specification, portlet filtering is already defined within the JSR 286 standard and is configured differently.

• Enable portlet filtering
• Register portlet filters
• Assign filters to a portlet
• Reference: Portlet filter life cycle
• Reference: Supported filter targets
• Reference: Programming tips

Enable portlet filtering

The usage of portlet filters is enabled by the legacy.portlet.enable.filtering property in the Portlet Container Service, as described in Set service configuration properties. To enable portlet filtering for the portal, set this property value to true:

legacy.portlet.enable.filtering = true

Default is true.

Register portlet filters

Before a filter can be used (assigned to a portlet), it must be registered in the PortletFilterService. The following example shows the declaration of a filter:

1: # Example:
2: filter.SampleFilter.class = com.example.SampleFilter
3: filter.SampleFilter.configValue = some configuration value
4: filter.SampleFilter.transcodeMarkup.1 = html->wml
5: # methods to be filtered
6: filter.SampleFilter.method.1 = service
7: filter.SampleFilter.method.2 = doTitle

In the example above the portlet filter SampleFilter is defined as follows:

• Line 2 defines the filter name to be SampleFilter. This name is later used in the portlet settings to attach the filter to the portlet. Line 2 also defines the class that implements the filter interface.

• Line 3 is a filter-specific setting that is given to the filter during initialization. The filter name is removed from the parameter name for later use. For example, the parameter defined in line 4 is later seen by the filter with the name configValue and the value some configuration value. Several settings of this type can exist.

• Line 4 declares this filter as a transcoding filter that can transcode from html to a wml markup. Several settings of this type can exist. If this filter is attached to a portlet that can render HTML, you can now also place this portlet on pages for WML devices. The filter is invoked to transcode the html output to wml as soon as a WML device connects to the portal.

• Line 6 specifies that the filter is called when the service method of the portlet is called.

• Line 7 specifies that the filter is called when the doTitle method of the portlet is called.

The information in lines 6 and 7 is used to call the filter only for the specified methods to improve the performance. The possible methods for the filter are the following: login, beginPage, service, endPage, doTitle, ActionEvent, MessageEvent, and WindowEvent. If the filter is to be called for every method, it does not need to define any method in the properties file.

Assign filters to a portlet

Once a portlet filter has been registered, it can be assigned to a portlet. You can assign multiple portlet filters to a portlet by defining the portlet setting FilterChain and delivering as a value a list of filters separated by comma or semicolon.

To add this setting to the relevant portlet during run time, use Modify Parameters in the Manage Portlets portlet.

The request will pass to the filters in the list from the left to the right and then proceed to the portlet. The portlet response will then traverse back through all filters from right to left. Refer to the following example:

FilterChain = MyTranscodingFilter, MyAdStripper

In this filter chain example, the filters do the following:

• MyTranscodingFilter is capable of transcoding HTML to WML.
• MyAdStripper removes the advertisement from the output of the portlet.

The following processing steps are taken:

1. MyTranscodingFilter is called first. This filter checks the requested markup and detects that WML is requested. Since the portlet supports only HTML, the client in the request is wrapped by this filter with a client-wrapper, which mimes an HTML client for the portlet. In addition, the response must be wrapped with a wrapper that intercepts the output of the following portlet or filters, in order to work on their output.

2. MyAdStripper does not have to modify the request because it only works on the output, but the response must be wrapped to store the output of the portlet.

3. The portlet generates its HTML output.

4. MyAdStripper works on the output of the portlet and will remove the advertisement.

5. MyTranscodingFilter then works on the output of the previous filter and transcodes this output to WML.

Multiple filters, which are capable of transcoding from one markup to another, are not allowed in a single filter chain.

You can also declare the filter chain or parts of the filter chain on a global level for all portlets written against the IBM API. To achieve this, you can edit/add a property FilterChain containing a comma-separated list of filters in the PortletFilterService.properties file, just like in the example above (FilterChain = MyTranscodingFilter, MyAdStripper). This global filter chain is merged with the one defined on a per-portlet basis, while the global ones are applied before the local ones.

Reference: Portlet filter life cycle

All filters have the following stages:

Init	The filter will be initialized. To get information about the specific filter settings and portal information, the FilterConfig is given to the init method of the filter. After the call of the init method, the filter will switch to the use mode.
Use	requests are handled by the doFilter method.
Destroy	filter is taken out of service and the doFilter method will not be called again. Thus system resources can be given back.

Reference: Supported filter targets

Calls to the portlet that do not have a request attached are not available to the portlet filter.

The following calls to the portlet are available to the filter:

• SERVICE
• DOTITLE
• ACTIONEVENT
• MESSAGEEVENT
• WINDOWEVENT
• LOGIN
• BEGINPAGE
• ENDPAGE

The following calls to the portlet are not available to the filter:

• Logout
• AttributeAdded
• AttributeReplaced
• AttributeRemoved
• Init
• InitConcrete
• Destroy
• DestroyConcrete

Reference: Programming tips

To quickly enable the usage of portlet filters, WebSphere Portal provides a predefined set of wrapping objects. These can be used to modify the standard behavior of the wrapped components. Wrappers are defined for the following objects:

Object	Predefined wrapper
PortletRequest	PortletRequestWrapper
PortletResponse	PortletResponseWrapper
Client	ClientWrapper

A transcoding filter for markups (for example, from HTML to WML ) will need to use all of these wrappers to emulate the HTML environment that an HTML portlet assumes.

Request flow of portlet filters

On server startup, all portlet filters that are registered in the PortletFilterService are initialized and are made available for filter registration. As soon as a portlet is dispatched, the portlet container gets the needed filters from the filter registration and calls these filters successively in the specified order. The portlet request and portlet response is forwarded through this chain of portlet filters before the portlet is rendered. Afterwards, the portlet container passes the request and response back through the chain of filters in the reverse order.

If a filter is to manipulate the output of a portlet, it must exchange the actual writer in the portlet response with one that stores data for later changes. This can be implemented using the wrapper classes delivered with the portal. After the portlet is called and the response is returned, the filter can then manipulate the output of the portlet and write the resulting output to the original writer.

Configure portal behavior

+

Search Tips   |   Advanced Search