KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > commons > chain > Filter


1 /*
2  * Copyright 2003-2004 The Apache Software Foundation
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
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 it 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: 1.6 $ $Date: 2004/11/30 05:52:23 $
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 JavaDoc exception);
65
66
67 }
68
Popular Tags