Configure portlet filtering (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...

1. portlet filtering must be enabled for the portal
2. portlet filters must be defined and activated in a properties file
3. filters must be assigned to the portlet

Portlet filters only apply to the IBM API. For portlets written against the JSR 286 specification, portlet filtering is defined within the JSR 286 standard and is configured differently.

• Enable portlet filtering
• Registering portlet filters
• Assigning 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

Registering 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 this example 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 settinthat 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, we 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.

Assigning filters to a portlet

After a portlet filter has been registered, we can assign it to a portlet. We can assign multiple portlet filters to a portlet by defining the portlet setting FilterChain and specifying a list of filters separated by comma or semicolon as the value.

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

The request will pass to the filters in the list in sequential order and then proceed to the portlet. The portlet response will then traverse back through all filters in reverse order. Refer to the following example:

FilterChain = MyTranscodingFilter, MyAdStripper

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

• MyTranscodingFilter can transcode HTML to WML.

• MyAdStripper removes the advertisement from the output of the portlet.

The request processes the following steps:

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

We cannot use multiple filterm that can transcode from one markup to another in a single filter chain.

We 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, we can edit or add a property FilterChain containing a comma-separated list of filters in the PortletFilterService.properties file, just like in the example given previously (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

Filter requests are handled by the doFilter method.

Destroy

The 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 filterm 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.

Parent: Configure portal behavior