Portlet filters

This section provides information on portlet filters in WebSphere Portal. 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.

• Enabling portlet filtering

• Registering portlet filters

• Assigning filters to a portlet

• Reference: Portlet filter life cycle

• Reference: Supported filter targets

• Reference: Programming tips

Enabling portlet filtering

The usage of portlet filters is enabled by the legacy.portlet.enable.filtering property in the PortletContainerService.properties file. To enable portlet filtering for the portal, set this property to true:

legacy.portlet.enable.filtering = true

The default value is true.

Registering portlet filters

Before a filter can be used (assigned to a portlet), it must be registered in the PortletFilterService.properties file. The following example shows the declaration of a sample filter, MonitorFilter. This is a sample implementation and it is contained in the classes of WebSphere Portal. The line numbers shown are for explanation purposes only; they are not used in an actual definition.

1: # Example:
2: filtername1 = MonitorFilter
3: MonitorFilter.classname = com.ibm.wps.portletcontainer.portletfilter.PortletMonitorFilter
4: MonitorFilter.heading = Start Monitor
5: MonitorFilter.ending = End Monitor
6: MonitorFilter.doFilter = false
7: # methods to be filtered
8: MonitorFilter.method.1 = service
9: MonitorFilter.method.2 = doTitle
10: # FromMarkup:ToMarkup
11: MonitorFilter.transcodeMarkup.1 = html->vxml
12: MonitorFilter.transcodeMarkup.2 = html->wml

The portlet filter MonitorFilter is defined as follows:

• Line 2 defines the filter name to be MonitorFilter. This name is later used in the portlet settings to attach the filter to the portlet.

• Line 3 defines the class implementing the filter interface.

• Line 4 - Line 12 are filter-specific settings, which are 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 would be seen by the filter with the name "heading" and the value "Start Monitor".

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

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

• Line 11 specifies that this filter is able to transcode HTML to VXML.

• Line 12 specifies that this filter is able to transcode HTML to WML.

The information in lines 8 and 9 is used to call the filter only for the specified methods to improve the performance. The possible methods for the filter are: 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.

The information in lines 11 and 12 is used to check if the portlet with the filter is able to support the requested markup. If the requested markup cannot be generated by the filter or is not supported by the portlet natively, the portlet will not be rendered. WebSphere Portal supports HTML, WML, iMode, and VXML (to manage supported markups, use the administration portlet for markups management).

The following are examples of a portlet in the context of different markups and the sample filter. If filtering is enabled, the filter will be called even if the portlet could not generate the requested markup (see Example 2). It is the task of the filter to analyze whether or not filtering is necessary.

Example 1:
The client is a voice server and requests VXML. Because the portlet has specified in the portlet.xml file that it supports HTML and the filter can transcode HTML to VXML, the portlet will be rendered.

Example 2:
The client is an HTML browser. Because the portlet supports HTML natively, the rendering process will be started.

Example 3:
The client is an iMode device. Because the portlet is not generating cHTML and the filter cannot provide it, the rendering of this portlet will be skipped.

Assigning filters to a portlet

When a portlet filter is registered in the properties file, it can be assigned to a portlet. Multiple portlet filters can be assigned 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 runtime, 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.

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:

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

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

• The portlet generates its HTML output.

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

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

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 filters that are registered in the PortletFilterService.properties file 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.

See also

• Portal configuration
• Administer your portal
• Developing portlets
• Designing your portal