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 Chain} represents a configured list of
021 * {@link Command}s that will be executed in order to perform processing
022 * on a specified {@link Context}. Each included {@link Command} will be
023 * executed in turn, until either one of them returns {@code true},
024 * one of the executed {@link Command}s throws an exception,
025 * or the end of the chain has been reached. The {@link Chain} itself will
026 * return the return value of the last {@link Command} that was executed
027 * (if no exception was thrown), or rethrow the thrown exception.
028 *
029 * <p>Note that {@link Chain} extends {@link Command}, so that the two can
030 * be used interchangeably when a {@link Command} is expected. This makes it
031 * easy to assemble workflows in a hierarchical manner by combining subchains
032 * into an overall processing chain.</p>
033 *
034 * <p>To protect applications from evolution of this interface, specialized
035 * implementations of {@link Chain} should generally be created by extending
036 * the provided base class {@link org.apache.commons.chain.impl.ChainBase})
037 * rather than directly implementing this interface.</p>
038 *
039 * <p>{@link Chain} implementations should be designed in a thread-safe
040 * manner, suitable for execution on multiple threads simultaneously. In
041 * general, this implies that the state information identifying which
042 * {@link Command} is currently being executed should be maintained in a
043 * local variable inside the {@code execute()} method, rather than
044 * in an instance variable. The {@link Command}s in a {@link Chain} may be
045 * configured (via calls to {@code addCommand()}) at any time before
046 * the {@code execute()} method of the {@link Chain} is first called.
047 * After that, the configuration of the {@link Chain} is frozen.</p>
048 *
049 * @param <C> Type of the context associated with this chain
050 *
051 * @author Craig R. McClanahan
052 * @version $Revision$ $Date$
053 */
054public interface Chain<C extends Context> extends Command<C> {
055
056    /**
057     * Add a {@link Command} to the list of {@link Command}s that will
058     * be called in turn when this {@link Chain}'s {@code execute()}
059     * method is called. Once {@code execute()} has been called
060     * at least once, it is no longer possible to add additional
061     * {@link Command}s; instead, an exception will be thrown.
062     *
063     * @param <CMD> the {@link Command} type to be added in the {@link Chain}
064     * @param command The {@link Command} to be added
065     *
066     * @throws IllegalArgumentException if {@code command}
067     *         is {@code null}
068     * @throws IllegalStateException if this {@link Chain} has already
069     *         been executed at least once, so no further configuration
070     *         is allowed
071     */
072    <CMD extends Command<C>> void addCommand(CMD command);
073
074    /**
075     * Execute the processing represented by this {@link Chain} according
076     * to the following algorithm.
077     * <ul>
078     * <li>If there are no configured {@link Command}s in the {@link Chain},
079     *     return {@code false}.</li>
080     * <li>Call the {@code execute()} method of each {@link Command}
081     *     configured on this chain, in the order they were added via calls
082     *     to the {@code addCommand()} method, until the end of the
083     *     configured {@link Command}s is encountered, or until one of
084     *     the executed {@link Command}s returns {@code true}
085     *     or throws an exception.</li>
086     * <li>Walk backwards through the {@link Command}s whose
087     *     {@code execute()} methods, starting with the last one that
088     *     was executed. If this {@link Command} instance is also a
089     *     {@link Filter}, call its {@code postprocess()} method,
090     *     discarding any exception that is thrown.</li>
091     * <li>If the last {@link Command} whose {@code execute()} method
092     *     was called threw an exception, rethrow that exception.</li>
093     * <li>Otherwise, return the value returned by the {@code execute()}
094     *     method of the last {@link Command} that was executed. This will be
095     *     {@code true} if the last {@link Command} indicated that
096     *     processing of this {@link Context} has been completed, or
097     *     {@code false} if none of the called {@link Command}s
098     *     returned {@code true}.</li>
099     * </ul>
100     *
101     * @param context The {@link Context} to be processed by this
102     *        {@link Chain}
103     *
104     * @return {@code true} if the processing of this {@link Context}
105     *         has been completed, or {@code false} if the processing
106     *         of this {@link Context} should be delegated to a
107     *         subsequent {@link Command} in an enclosing {@link Chain}
108     *
109     * @throws Exception if thrown by one of the {@link Command}s
110     *         in this {@link Chain} but not handled by a
111     *         {@code postprocess()} method of a {@link Filter}
112     * @throws IllegalArgumentException if {@code context}
113     *         is {@code null}
114     */
115    @Override
116    boolean execute(C context) throws Exception;
117}