001 /* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017 package org.apache.commons.chain; 018 019 020 /** 021 * <p>A {@link Filter} is a specialized {@link Command} that also expects 022 * the {@link Chain} that is executing it to call the 023 * <code>postprocess()</code> method if it called the <code>execute()</code> 024 * method. This promise must be fulfilled in spite of any possible 025 * exceptions thrown by the <code>execute()</code> method of this 026 * {@link Command}, or any subsequent {@link Command} whose 027 * <code>execute()</code> method was called. The owning {@link Chain} 028 * must call the <code>postprocess()</code> method of each {@link Filter} 029 * in a {@link Chain} in reverse order of the invocation of their 030 * <code>execute()</code> methods.</p> 031 * 032 * <p>The most common use case for a {@link Filter}, as opposed to a 033 * {@link Command}, is where potentially expensive resources must be acquired 034 * and held until the processing of a particular request has been completed, 035 * even if execution is delegated to a subsequent {@link Command} via the 036 * <code>execute()</code> returning <code>false</code>. A {@link Filter} 037 * can reliably release such resources in the <code>postprocess()</code> 038 * method, which is guaranteed to be called by the owning {@link Chain}.</p> 039 * 040 * @author Craig R. McClanahan 041 * @version $Revision: 480477 $ $Date: 2006-11-29 08:34:52 +0000 (Wed, 29 Nov 2006) $ 042 */ 043 044 public interface Filter extends Command { 045 046 047 /** 048 * <p>Execute any cleanup activities, such as releasing resources that 049 * were acquired during the <code>execute()</code> method of this 050 * {@link Filter} instance.</p> 051 * 052 * @param context The {@link Context} to be processed by this 053 * {@link Filter} 054 * @param exception The <code>Exception</code> (if any) that was thrown 055 * by the last {@link Command} that was executed; otherwise 056 * <code>null</code> 057 * 058 * @exception IllegalArgumentException if <code>context</code> 059 * is <code>null</code> 060 * 061 * @return If a non-null <code>exception</code> was "handled" by this 062 * method (and therefore need not be rethrown), return <code>true</code>; 063 * otherwise return <code>false</code> 064 */ 065 boolean postprocess(Context context, Exception exception); 066 067 068 }