javax.portlet.filter.ResourceFilter Maven / Gradle / Ivy
Show all versions of portlet-api Show documentation
/* 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.
*/
/*
* 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!
*/
package javax.portlet.filter;
import java.io.IOException;
import javax.portlet.ResourceRequest;
import javax.portlet.ResourceResponse;
import javax.portlet.PortletException;
/**
* The
* ResourceFilter is an object that performs filtering
* tasks on either the resource request to a portlet, or on the resource 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.
*
*
* Asynchronous Processing Considerations
*
* If the ResourceFilter is to support asynchronous mode, care must be taken
* regarding resource allocation and release.
* Any resources attached to the ResourceRequest during the inbound portion
* of the doFilter invocation
* and needed during asynchronous processing should not be released during outbound processing
* if asynchronous mode has been started.
*
* If resources must be allocated in this way during inbound processing, the portlet should
* use a {@link javax.portlet.PortletAsyncListener} to release the resources upon request
* completion even when error conditions or timeouts occur.
*
* Alternatively, the portlet may
* use the AsyncContext#dispatch() method at the end of asynchronous processing
* in order to cause the portlet resource method to be invoked again with the same
* ResourceRequest and ResourceResponse objects.
* The resources can be released during asynchronous dispatch outbound processing if
* asynchronous mode is not active.
*
* The ResourceRequest#isAsyncStarted() method will return true
* if the portlet is currently in asynchronous mode.
* The ResourceRequest#igetDispatcherType() method will return
* DispatcherType#REQUEST during initial request processing and
* DipatcherType#ASYNC during processing resulting from an asynchronous dispatch.
*
*
* @since 2.0
*/
public interface ResourceFilter extends PortletFilter {
/**
* The doFilter method of the Filter is called by the
* portlet container each time a resource 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 resource 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
ResourceRequestWrapper
* 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 ResourceResponseWrapper
* 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 resource request
* @param response the current resource 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(ResourceRequest request, ResourceResponse response,
FilterChain chain)
throws IOException, PortletException;
}