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 */
017package org.apache.commons.chain;
018
019/**
020 * A {@link Filter} is a specialized {@link Command} that also expects
021 * the {@link Chain} that is executing it to call the
022 * {@code postprocess()} method if it called the {@code execute()}
023 * method. This promise must be fulfilled in spite of any possible
024 * exceptions thrown by the {@code execute()} method of this
025 * {@link Command}, or any subsequent {@link Command} whose
026 * {@code execute()} method was called. The owning {@link Chain}
027 * must call the {@code postprocess()} method of each {@link Filter}
028 * in a {@link Chain} in reverse order of the invocation of their
029 * {@code execute()} methods.
030 *
031 * <p>The most common use case for a {@link Filter}, as opposed to a
032 * {@link Command}, is where potentially expensive resources must be acquired
033 * and held until the processing of a particular request has been completed,
034 * even if execution is delegated to a subsequent {@link Command} via the
035 * {@code execute()} returning {@code false}. A {@link Filter}
036 * can reliably release such resources in the {@code postprocess()}
037 * method, which is guaranteed to be called by the owning {@link Chain}.</p>
038 *
039 * @param <C> Type of the context associated with this command
040 *
041 * @author Craig R. McClanahan
042 * @version $Revision$ $Date$
043 */
044public interface Filter<C extends Context> extends Command<C> {
045
046    /**
047     * Execute any cleanup activities, such as releasing resources that
048     * were acquired during the {@code execute()} method of this
049     * {@link Filter} instance.
050     *
051     * @param context The {@link Context} to be processed by this
052     *        {@link Filter}
053     * @param exception The {@code Exception} (if any) that was thrown
054     *        by the last {@link Command} that was executed; otherwise
055     *        {@code null}
056     *
057     * @return If a non-null {@code exception} was "handled" by this
058     *         method (and therefore need not be rethrown), return
059     *         {@code true}; otherwise return {@code false}
060     *
061     * @throws IllegalArgumentException if {@code context}
062     *         is {@code null}
063     */
064   boolean postprocess(C context, Exception exception);
065}