javax.portlet.filter.RenderFilter Maven / Gradle / Ivy

/*  Licensed to the Apache Software Foundation (ASF) under one
 *  or more contributor license agreements.  See the NOTICE file
 *  distributed with this work for additional information
 *  regarding copyright ownership.  The ASF licenses this file
 *  to you under the Apache License, Version 2.0 (the
 *  "License"); you may not use this file except in compliance
 *  with the License.  You may obtain a copy of the License at
 *
 *    http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing,
 *  software distributed under the License is distributed on an
 *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 *  KIND, either express or implied.  See the License for the
 *  specific language governing permissions and limitations
 *  under the License.
 */
/*
 * NOTE: this source code is based on an early draft version of JSR 286 and not intended for product
 * implementations. This file may change or vanish in the final version of the JSR 286 specification.
 */
/*
 * This source code implements specifications defined by the Java
 * Community Process. In order to remain compliant with the specification
 * DO NOT add / change / or delete method signatures!
 */
/*
 * Copyright 2006 IBM Corporation.
 *
 */
package javax.portlet.filter;

import java.io.IOException;

import javax.portlet.RenderRequest;
import javax.portlet.RenderResponse;
import javax.portlet.PortletException;

/**
 * The RenderFilter is an object that performs filtering 
 * tasks on either the render request to a portlet, or on the render response from 
 * a portlet, or both.
 * 
 * Filters perform filtering in the doFilter method. Every Filter has 
 * access to a FilterConfig object from which it can obtain 
 * its initialization parameters, a reference to the PortletContext 
 * which it can use, for example, to load resources needed for filtering tasks.
 * 

 * Filters are configured in the portlet deployment descriptor of a 
 * portlet application. 
 * 
 * @since 2.0
 */
public interface RenderFilter extends PortletFilter {

    /**
     * The doFilter method of the Filter is called by the 
     * portlet container each time a render request/response pair is passed 
     * through the chain due to a client request for a portlet method 
     * at the end of the chain. 
     * 

     * The FilterChain passed in to this method allows 
     * the Filter to pass on the render request and response to the next 
     * component in the chain.
     * 

     * The doFilter method of a filter will typically be implemented 
     * following this or some subset of the following pattern:
     * 

     *  The method examines the request information.
     *  The method may wrap the request object passed in to 
     *      its doFilter method with a customized implementation 
     *      the request wrapper RenderRequestWrapper 
     *      in order to modify request data.
     *  The method may wrap the response object passed in to its 
     *      doFilter method with a customized implementation 
     *      of the response wrapper RenderResponseWrapper 
     *      to modify response data.
     *  The filter may invoke the next component in the filter chain. 
     *      The next component may be another filter, or if the filter 
     *      making the invocation is the last filter configured in the 
     *      deployment descriptor for this chain, the next component 
     *      is the target method of the portlet. The invocation of the 
     *      next component is effected by calling the doFilter
     *      method on the FilterChain object, and passing in 
     *      the request and response with which it was called or passing 
     *      in wrapped versions it may have created. 
     *      The filter chain?s implementation of the doFilter 
     *      method, provided by the portlet container, must locate the 
     *      next component in the filter chain and invoke its doFilter
     *      method, passing in the appropriate request and response objects. 
     *      Alternatively, the filter chain can block the request by not 
     *      making the call to invoke the next component, leaving the filter 
     *      responsible for filling out the response object.
     *  After invocation of the next filter in the chain, the filter 
     *      may examine the response data.
     *  Alternatively, the filter may have thrown an exception to 
     *      indicate an error in processing. If the filter throws an 
     *      UnavailableException during its doFilter 
     *      processing, the portlet container must not attempt continued 
     *      processing down the filter chain. It may choose to retry the 
     *      whole chain at a later time if the exception is not marked permanent.
     *  When the last filter in the chain has been invoked, the next 
     *      component accessed is the target method on the portlet at 
     *      the end of the chain.
     * 
     * 
     * @param request  the current render request 
     * @param response  the current render response 
     * @param chain  the remaining filter chain
     * @throws IOException  if an IO error occurred in the filter processing
     * @throws PortletException  if a portlet exception occurred in the filter processing
     */
    public void doFilter(RenderRequest request, RenderResponse response,
                         FilterChain chain)
     throws IOException, PortletException;
        
}