1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16 package org.apache.commons.chain;
17
18
19 /***
20 * <p>A {@link Chain} represents a configured list of
21 * {@link Command}s that will be executed in order to perform processing
22 * on a specified {@link Context}. Each included {@link Command} will be
23 * executed in turn, until either one of them returns <code>true</code>,
24 * one of the executed {@link Command}s throws an exception,
25 * or the end of the chain has been reached. The {@link Chain} itself will
26 * return the return value of the last {@link Command} that was executed
27 * (if no exception was thrown), or rethrow the thrown exception.</p>
28 *
29 * <p>Note that {@link Chain} extends {@link Command}, so that the two can
30 * be used interchangeably when a {@link Command} is expected. This makes it
31 * easy to assemble workflows in a hierarchical manner by combining subchains
32 * into an overall processing chain.</p>
33 *
34 * <p>To protect applications from evolution of this interface, specialized
35 * implementations of {@link Chain} should generally be created by extending
36 * the provided base class {@link org.apache.commons.chain.impl.ChainBase})
37 * rather than directly implementing this interface.</p>
38 *
39 * <p>{@link Chain} implementations should be designed in a thread-safe
40 * manner, suitable for execution on multiple threads simultaneously. In
41 * general, this implies that the state information identifying which
42 * {@link Command} is currently being executed should be maintained in a
43 * local variable inside the <code>execute()</code> method, rather than
44 * in an instance variable. The {@link Command}s in a {@link Chain} may be
45 * configured (via calls to <code>addCommand()</code>) at any time before
46 * the <code>execute()</code> method of the {@link Chain} is first called.
47 * After that, the configuration of the {@link Chain} is frozen.</p>
48 *
49 * @author Craig R. McClanahan
50 * @version $Revision: 155403 $ $Date: 2005-02-26 12:52:46 +0000 (Sat, 26 Feb 2005) $
51 */
52
53 public interface Chain extends Command {
54
55
56 /***
57 * <p>Add a {@link Command} to the list of {@link Command}s that will
58 * be called in turn when this {@link Chain}'s <code>execute()</code>
59 * method is called. Once <code>execute()</code> has been called
60 * at least once, it is no longer possible to add additional
61 * {@link Command}s; instead, an exception will be thrown.</p>
62 *
63 * @param command The {@link Command} to be added
64 *
65 * @exception IllegalArgumentException if <code>command</code>
66 * is <code>null</code>
67 * @exception IllegalStateException if this {@link Chain} has already
68 * been executed at least once, so no further configuration is allowed
69 */
70 void addCommand(Command command);
71
72
73 /***
74 * <p>Execute the processing represented by this {@link Chain} according
75 * to the following algorithm.</p>
76 * <ul>
77 * <li>If there are no configured {@link Command}s in the {@link Chain},
78 * return <code>false</code>.</li>
79 * <li>Call the <code>execute()</code> method of each {@link Command}
80 * configured on this chain, in the order they were added via calls
81 * to the <code>addCommand()</code> method, until the end of the
82 * configured {@link Command}s is encountered, or until one of
83 * the executed {@link Command}s returns <code>true</code>
84 * or throws an exception.</li>
85 * <li>Walk backwards through the {@link Command}s whose
86 * <code>execute()</code> methods, starting with the last one that
87 * was executed. If this {@link Command} instance is also a
88 * {@link Filter}, call its <code>postprocess()</code> method,
89 * discarding any exception that is thrown.</li>
90 * <li>If the last {@link Command} whose <code>execute()</code> method
91 * was called threw an exception, rethrow that exception.</li>
92 * <li>Otherwise, return the value returned by the <code>execute()</code>
93 * method of the last {@link Command} that was executed. This will be
94 * <code>true</code> if the last {@link Command} indicated that
95 * processing of this {@link Context} has been completed, or
96 * <code>false</code> if none of the called {@link Command}s
97 * returned <code>true</code>.</li>
98 * </ul>
99 *
100 * @param context The {@link Context} to be processed by this
101 * {@link Chain}
102 *
103 * @exception Exception if thrown by one of the {@link Command}s
104 * in this {@link Chain} but not handled by a <code>postprocess()</code>
105 * method of a {@link Filter}
106 * @exception IllegalArgumentException if <code>context</code>
107 * is <code>null</code>
108 *
109 * @return <code>true</code> if the processing of this {@link Context}
110 * has been completed, or <code>false</code> if the processing
111 * of this {@link Context} should be delegated to a subsequent
112 * {@link Command} in an enclosing {@link Chain}
113 */
114 boolean execute(Context context) throws Exception;
115
116
117 }