org.apache.commons.chain.Filter Maven / Gradle / Ivy
/*
* 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.
*/
package org.apache.commons.chain;
/**
* A {@link Filter} is a specialized {@link Command} that also expects
* the {@link Chain} that is executing it to call the
* postprocess()
method if it called the execute()
* method. This promise must be fulfilled in spite of any possible
* exceptions thrown by the execute()
method of this
* {@link Command}, or any subsequent {@link Command} whose
* execute()
method was called. The owning {@link Chain}
* must call the postprocess()
method of each {@link Filter}
* in a {@link Chain} in reverse order of the invocation of their
* execute()
methods.
*
* The most common use case for a {@link Filter}, as opposed to a
* {@link Command}, is where potentially expensive resources must be acquired
* and held until the processing of a particular request has been completed,
* even if execution is delegated to a subsequent {@link Command} via the
* execute()
returning false
. A {@link Filter}
* can reliably release such resources in the postprocess()
* method, which is guaranteed to be called by the owning {@link Chain}.
*
* @author Craig R. McClanahan
* @version $Revision: 480477 $ $Date: 2006-11-29 08:34:52 +0000 (Wed, 29 Nov 2006) $
*/
public interface Filter extends Command {
/**
* Execute any cleanup activities, such as releasing resources that
* were acquired during the execute()
method of this
* {@link Filter} instance.
*
* @param context The {@link Context} to be processed by this
* {@link Filter}
* @param exception The Exception
(if any) that was thrown
* by the last {@link Command} that was executed; otherwise
* null
*
* @exception IllegalArgumentException if context
* is null
*
* @return If a non-null exception
was "handled" by this
* method (and therefore need not be rethrown), return true
;
* otherwise return false
*/
boolean postprocess(Context context, Exception exception);
}