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