Portal Express, Version 6.0
Operating systems: i5/OS, Linux, Windows
Portlet filters
This section provides information on portlet filters in WebSphere Portal Express. 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
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 Setting configuration properties. To enable portlet filtering for the portal, set this property value 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. 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.
Assigning 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 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 Express 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.
Related information