org.apache.commons.chain.Chain 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 Chain} represents a configured list of
* {@link Command}s that will be executed in order to perform processing
* on a specified {@link Context}. Each included {@link Command} will be
* executed in turn, until either one of them returns true,
* one of the executed {@link Command}s throws an exception,
* or the end of the chain has been reached. The {@link Chain} itself will
* return the return value of the last {@link Command} that was executed
* (if no exception was thrown), or rethrow the thrown exception.
*
* Note that {@link Chain} extends {@link Command}, so that the two can
* be used interchangeably when a {@link Command} is expected. This makes it
* easy to assemble workflows in a hierarchical manner by combining subchains
* into an overall processing chain.
*
* To protect applications from evolution of this interface, specialized
* implementations of {@link Chain} should generally be created by extending
* the provided base class {@link org.apache.commons.chain.impl.ChainBase})
* rather than directly implementing this interface.
*
* {@link Chain} implementations should be designed in a thread-safe
* manner, suitable for execution on multiple threads simultaneously. In
* general, this implies that the state information identifying which
* {@link Command} is currently being executed should be maintained in a
* local variable inside the execute() method, rather than
* in an instance variable. The {@link Command}s in a {@link Chain} may be
* configured (via calls to addCommand()) at any time before
* the execute() method of the {@link Chain} is first called.
* After that, the configuration of the {@link Chain} is frozen.
*
* @author Craig R. McClanahan
* @version $Revision: 480477 $ $Date: 2006-11-29 08:34:52 +0000 (Wed, 29 Nov 2006) $
*/
public interface Chain extends Command {
/**
* Add a {@link Command} to the list of {@link Command}s that will
* be called in turn when this {@link Chain}'s execute()
* method is called. Once execute() has been called
* at least once, it is no longer possible to add additional
* {@link Command}s; instead, an exception will be thrown.
*
* @param command The {@link Command} to be added
*
* @exception IllegalArgumentException if command
* is null
* @exception IllegalStateException if this {@link Chain} has already
* been executed at least once, so no further configuration is allowed
*/
void addCommand(Command command);
/**
* Execute the processing represented by this {@link Chain} according
* to the following algorithm.
*
* - If there are no configured {@link Command}s in the {@link Chain},
* return
false.
* - Call the
execute() method of each {@link Command}
* configured on this chain, in the order they were added via calls
* to the addCommand() method, until the end of the
* configured {@link Command}s is encountered, or until one of
* the executed {@link Command}s returns true
* or throws an exception.
* - Walk backwards through the {@link Command}s whose
*
execute() methods, starting with the last one that
* was executed. If this {@link Command} instance is also a
* {@link Filter}, call its postprocess() method,
* discarding any exception that is thrown.
* - If the last {@link Command} whose
execute() method
* was called threw an exception, rethrow that exception.
* - Otherwise, return the value returned by the
execute()
* method of the last {@link Command} that was executed. This will be
* true if the last {@link Command} indicated that
* processing of this {@link Context} has been completed, or
* false if none of the called {@link Command}s
* returned true.
*
*
* @param context The {@link Context} to be processed by this
* {@link Chain}
*
* @exception Exception if thrown by one of the {@link Command}s
* in this {@link Chain} but not handled by a postprocess()
* method of a {@link Filter}
* @exception IllegalArgumentException if context
* is null
*
* @return true if the processing of this {@link Context}
* has been completed, or false if the processing
* of this {@link Context} should be delegated to a subsequent
* {@link Command} in an enclosing {@link Chain}
*/
boolean execute(Context context) throws Exception;
}