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 Command} encapsulates a unit of processing work to be
21 * performed, whose purpose is to examine and/or modify the state of a
22 * transaction that is represented by a {@link Context}. Individual
23 * {@link Command}s can be assembled into a {@link Chain}, which allows
24 * them to either complete the required processing or delegate further
25 * processing to the next {@link Command} in the {@link Chain}.</p>
26 *
27 * <p>{@link Command} implementations should be designed in a thread-safe
28 * manner, suitable for inclusion in multiple {@link Chain}s that might be
29 * processed by different threads simultaneously. In general, this implies
30 * that {@link Command} classes should not maintain state information in
31 * instance variables. Instead, state information should be maintained via
32 * suitable modifications to the attributes of the {@link Context} that is
33 * passed to the <code>execute()</code> command.</p>
34 *
35 * <p>{@link Command} implementations typically retrieve and store state
36 * information in the {@link Context} instance that is passed as a parameter
37 * to the <code>execute()</code> method, using particular keys into the
38 * <code>Map</code> that can be acquired via
39 * <code>Context.getAttributes()</code>. To improve interoperability of
40 * {@link Command} implementations, a useful design pattern is to expose the
41 * key values used as JavaBeans properties of the {@link Command}
42 * implementation class itself. For example, a {@link Command} that requires
43 * an input and an output key might implement the following properties:</p>
44 *
45 * <pre>
46 * private String inputKey = "input";
47 * public String getInputKey() {
48 * return (this.inputKey);
49 * }
50 * public void setInputKey(String inputKey) {
51 * this.inputKey = inputKey;
52 * }
53 *
54 * private String outputKey = "output";
55 * public String getOutputKey() {
56 * return (this.outputKey);
57 * }
58 * public void setOutputKey(String outputKey) {
59 * this.outputKey = outputKey;
60 * }
61 * </pre>
62 *
63 * <p>And the operation of accessing the "input" information in the context
64 * would be executed by calling:</p>
65 *
66 * <pre>
67 * String input = (String) context.get(getInputKey());
68 * </pre>
69 *
70 * <p>instead of hard coding the attribute name. The use of the "Key"
71 * suffix on such property names is a useful convention to identify properties
72 * being used in this fashion, as opposed to JavaBeans properties that simply
73 * configure the internal operation of this {@link Command}.</p>
74 *
75 * @author Craig R. McClanahan
76 * @version $Revision: 411876 $ $Date: 2006-06-05 19:02:19 +0100 (Mon, 05 Jun 2006) $
77 */
78
79 public interface Command {
80
81 /***
82 * <p>Commands should return <code>CONTINUE_PROCESSING</code> if the processing
83 * of the given {@link Context} should be delegated to a subsequent
84 * {@link Command} in an enclosing {@link Chain}.</p>
85 *
86 * @since Chain 1.1
87 */
88 public static final boolean CONTINUE_PROCESSING = false;
89
90 /***
91 * <p>Commands should return <code>PROCESSING_COMPLETE</code>
92 * if the processing of the given {@link Context}
93 * has been completed.</p>
94 *
95 * @since Chain 1.1
96 */
97 public static final boolean PROCESSING_COMPLETE = true;
98 /***
99 * <p>Execute a unit of processing work to be performed. This
100 * {@link Command} may either complete the required processing
101 * and return <code>true</code>, or delegate remaining processing
102 * to the next {@link Command} in a {@link Chain} containing this
103 * {@link Command} by returning <code>false</code>
104 *
105 * @param context The {@link Context} to be processed by this
106 * {@link Command}
107 *
108 * @exception Exception general purpose exception return
109 * to indicate abnormal termination
110 * @exception IllegalArgumentException if <code>context</code>
111 * is <code>null</code>
112 *
113 * @return <code>true</code> if the processing of this {@link Context}
114 * has been completed, or <code>false</code> if the processing
115 * of this {@link Context} should be delegated to a subsequent
116 * {@link Command} in an enclosing {@link Chain}
117 */
118 boolean execute(Context context) throws Exception;
119
120
121 }