001: /*
002: * Copyright 2003-2004 The Apache Software Foundation
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016: package org.apache.commons.chain;
017:
018: /**
019: * <p>A {@link Chain} represents a configured list of
020: * {@link Command}s that will be executed in order to perform processing
021: * on a specified {@link Context}. Each included {@link Command} will be
022: * executed in turn, until either one of them returns <code>true</code>,
023: * one of the executed {@link Command}s throws an exception,
024: * or the end of the chain has been reached. The {@link Chain} itself will
025: * return the return value of the last {@link Command} that was executed
026: * (if no exception was thrown), or rethrow the thrown exception.</p>
027: *
028: * <p>Note that {@link Chain} extends {@link Command}, so that the two can
029: * be used interchangeably when a {@link Command} is expected. This makes it
030: * easy to assemble workflows in a hierarchical manner by combining subchains
031: * into an overall processing chain.</p>
032: *
033: * <p>To protect applications from evolution of this interface, specialized
034: * implementations of {@link Chain} should generally be created by extending
035: * the provided base class {@link org.apache.commons.chain.impl.ChainBase})
036: * rather than directly implementing this interface.</p>
037: *
038: * <p>{@link Chain} implementations should be designed in a thread-safe
039: * manner, suitable for execution on multiple threads simultaneously. In
040: * general, this implies that the state information identifying which
041: * {@link Command} is currently being executed should be maintained in a
042: * local variable inside the <code>execute()</code> method, rather than
043: * in an instance variable. The {@link Command}s in a {@link Chain} may be
044: * configured (via calls to <code>addCommand()</code>) at any time before
045: * the <code>execute()</code> method of the {@link Chain} is first called.
046: * After that, the configuration of the {@link Chain} is frozen.</p>
047: *
048: * @author Craig R. McClanahan
049: * @version $Revision: 155403 $ $Date: 2005-02-26 12:52:46 +0000 (Sat, 26 Feb 2005) $
050: */
051:
052: public interface Chain extends Command {
053:
054: /**
055: * <p>Add a {@link Command} to the list of {@link Command}s that will
056: * be called in turn when this {@link Chain}'s <code>execute()</code>
057: * method is called. Once <code>execute()</code> has been called
058: * at least once, it is no longer possible to add additional
059: * {@link Command}s; instead, an exception will be thrown.</p>
060: *
061: * @param command The {@link Command} to be added
062: *
063: * @exception IllegalArgumentException if <code>command</code>
064: * is <code>null</code>
065: * @exception IllegalStateException if this {@link Chain} has already
066: * been executed at least once, so no further configuration is allowed
067: */
068: void addCommand(Command command);
069:
070: /**
071: * <p>Execute the processing represented by this {@link Chain} according
072: * to the following algorithm.</p>
073: * <ul>
074: * <li>If there are no configured {@link Command}s in the {@link Chain},
075: * return <code>false</code>.</li>
076: * <li>Call the <code>execute()</code> method of each {@link Command}
077: * configured on this chain, in the order they were added via calls
078: * to the <code>addCommand()</code> method, until the end of the
079: * configured {@link Command}s is encountered, or until one of
080: * the executed {@link Command}s returns <code>true</code>
081: * or throws an exception.</li>
082: * <li>Walk backwards through the {@link Command}s whose
083: * <code>execute()</code> methods, starting with the last one that
084: * was executed. If this {@link Command} instance is also a
085: * {@link Filter}, call its <code>postprocess()</code> method,
086: * discarding any exception that is thrown.</li>
087: * <li>If the last {@link Command} whose <code>execute()</code> method
088: * was called threw an exception, rethrow that exception.</li>
089: * <li>Otherwise, return the value returned by the <code>execute()</code>
090: * method of the last {@link Command} that was executed. This will be
091: * <code>true</code> if the last {@link Command} indicated that
092: * processing of this {@link Context} has been completed, or
093: * <code>false</code> if none of the called {@link Command}s
094: * returned <code>true</code>.</li>
095: * </ul>
096: *
097: * @param context The {@link Context} to be processed by this
098: * {@link Chain}
099: *
100: * @exception Exception if thrown by one of the {@link Command}s
101: * in this {@link Chain} but not handled by a <code>postprocess()</code>
102: * method of a {@link Filter}
103: * @exception IllegalArgumentException if <code>context</code>
104: * is <code>null</code>
105: *
106: * @return <code>true</code> if the processing of this {@link Context}
107: * has been completed, or <code>false</code> if the processing
108: * of this {@link Context} should be delegated to a subsequent
109: * {@link Command} in an enclosing {@link Chain}
110: */
111: boolean execute(Context context) throws Exception;
112:
113: }
|