Tuesday, October 5, 2010

JSR 286 Portlet filter feature

JSR 286 introduces a new feature of portlet filter which is not included in earlier version of JSR specification. In this post, I am going to describe portlet filter feature briefly along with implementation code and example.

What is Portlet Filter?

Portlet filter is a piece of code that can transform content of portlet request and response. The concept is almost same as we already learnt from Servlet filter.
A filter by implementing one of the javax.portlet.filter.XYZFilter interfaces and providing a public constructor taking no arguments. A filter is declared using the <filter> element in the portlet deployment descriptor. A filter or collection of filters can be configured for invocation by defining <filter-mapping> elements in the portlet deployment descriptor.


Portlet Filter Lifecycle -

When request comes for portlet access, portlet container locate list of filters first and create instances of filters from the list and then calls init(FilterConfig config) method of filter.
When the container receives an incoming request, it takes the first filter instance in the list and calls its doFilter method, passing in the PortletRequest and PortletResponse, and a reference to the FilterChain object it will use.
Depending on target method of doFilter call, the PortletRequest and PortletResponse must be instances of the following interfaces:

1) ActionRequest and ActionResponse for processAction calls
2) EventRequest and EventResponse for processEvent calls
3) RenderRequest and RenderResponse for render calls
4) ResourceRequest and ResourceResponse for serveResource calls

Before a filter instance can be removed from service by the portlet container, the portlet container must first call the destroy method on the filter to enable the filter to release any resources and perform other cleanup operations.

Portlet Filter Configurations on application -

A filter is defined in the deployment descriptor using the <filter> element. In this element, the programmer declares the following:

1) filter-name: used to map the filter to a portlet
2) filter-class: used by the portlet container to identify the filter type
3) lifecycle: used to determine for which lifecycles the filter should be applied
4) init-params: initialization parameters for a filter

Here is an example of a filter declaration:

<filter>
 <filter-name>MyPortletFilter</filter-name>
 <filter-class>com.ibm.portletfiltersexample.MyPortletFilter</filter-class>
<lifecycle>RENDER_PHASE</lifecycle>
</filter>

Once a filter has been declared in the portlet deployment descriptor, the <filter-mapping> element is used to define portlets in the portlet application to which the filter is to be applied. Filters can be associated with a portlet using the <portlet-name> element.

PortletFiltersExample portlet:

<filter-mapping>
 <filter-name>MyPortletFilter</filter-name>
 <portlet-name>PortletFiltersExample</portlet-name>
</filter-mapping>

Filters can be associated with groups of portlets using the ‘*’ character as a wildcard.

<portlet-name>*</portlet-name>

A portlet filter can be applied to different lifecycle method calls: processAction, processEvent, render, serveResource. The following constants are valid values for the <lifecycle> element:

1) ACTION_PHASE requesting that the portlet container processes this filter for the processAction lifecycle method. The filter implementation must implement the ActionFilter interface.
2) EVENT_PHASE requesting that the portlet container processes this filter for the processEvent lifecycle method. The filter implementation must implement the EventFilter interface.
3) RENDER_PHASE requesting that the portlet container processes this filter for the render lifecycle method. The filter implementation must implement the RenderFilter interface.
4) RESOURCE_PHASE requesting that the portlet container processes this filter for the serveResource lifecycle method. The filter implementation must implement the ResourceFilter interface.

Example:

<filter>
<filter-name>MyPortletFilter</filter-name>
 <filter-class>com.ibm.portletfiltersexample.MyPortletFilter</filter-class>
 <lifecycle>ACTION_PHASE</lifecycle>
 <lifecycle>RENDER_PHASE</lifecycle>
</filter>

In this example the portlet filter is applied to the action and render phase.

And the code of filter class, which implements RenderFilter interface, is as:

public class MyPortletFilter implements RenderFilter {

 public void init(javax.portlet.filter.FilterConfig arg0) throws PortletException {
  // TODO Auto-generated method stub
  }

  public void doFilter(RenderRequest req, RenderResponse res, FilterChain chain) throws IOException,PortletException {
   System.out.println(" DEBUG: M Portlet Filter Pre-processing a render request");
   // Hand off control to the next filter in the chain, or the portlet itself if no more filters  
   chain.doFilter(req, res);
   System.out.println(" DEBUG: M Portlet Filter Post-processing a render request");
  }

  public void destroy()
  {
   System.out.println("DEBUG: Destroying My Portlet :-("); 
  }
}

If you need any sample application of portlet filter, you please click on followning link and download the attached applicaton 'PortletFiltersExample.war' in dilip's post.

http://www.ibm.com/developerworks/forums/thread.jspa?threadID=316941&tstart=0 

No comments: