1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16 package org.apache.commons.chain;
17
18
19 /***
20 * <p>A {@link Filter} is a specialized {@link Command} that also expects
21 * the {@link Chain} that is executing it to call the
22 * <code>postprocess()</code> method if it called the <code>execute()</code>
23 * method. This promise must be fulfilled in spite of any possible
24 * exceptions thrown by the <code>execute()</code> method of this
25 * {@link Command}, or any subsequent {@link Command} whose
26 * <code>execute()</code> method was called. The owning {@link Chain}
27 * must call the <code>postprocess()</code> method of each {@link Filter}
28 * in a {@link Chain} in reverse order of the invocation of their
29 * <code>execute()</code> methods.</p>
30 *
31 * <p>The most common use case for a {@link Filter}, as opposed to a
32 * {@link Command}, is where potentially expensive resources must be acquired
33 * and held until the processing of a particular request has been completed,
34 * even if execution is delegated to a subsequent {@link Command} via the
35 * <code>execute()</code> returning <code>false</code>. A {@link Filter}
36 * can reliably release such resources in the <code>postprocess()</code>
37 * method, which is guaranteed to be called by the owning {@link Chain}.</p>
38 *
39 * @author Craig R. McClanahan
40 * @version $Revision: 155403 $ $Date: 2005-02-26 12:52:46 +0000 (Sat, 26 Feb 2005) $
41 */
42
43 public interface Filter extends Command {
44
45
46 /***
47 * <p>Execute any cleanup activities, such as releasing resources that
48 * were acquired during the <code>execute()</code> method of this
49 * {@link Filter} instance.</p>
50 *
51 * @param context The {@link Context} to be processed by this
52 * {@link Filter}
53 * @param exception The <code>Exception</code> (if any) that was thrown
54 * by the last {@link Command} that was executed; otherwise
55 * <code>null</code>
56 *
57 * @exception IllegalArgumentException if <code>context</code>
58 * is <code>null</code>
59 *
60 * @return If a non-null <code>exception</code> was "handled" by this
61 * method (and therefore need not be rethrown), return <code>true</code>;
62 * otherwise return <code>false</code>
63 */
64 boolean postprocess(Context context, Exception exception);
65
66
67 }