1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package org.apache.commons.chain;
18
19
20 /**
21 * <p>A {@link Command} encapsulates a unit of processing work to be
22 * performed, whose purpose is to examine and/or modify the state of a
23 * transaction that is represented by a {@link Context}. Individual
24 * {@link Command}s can be assembled into a {@link Chain}, which allows
25 * them to either complete the required processing or delegate further
26 * processing to the next {@link Command} in the {@link Chain}.</p>
27 *
28 * <p>{@link Command} implementations should be designed in a thread-safe
29 * manner, suitable for inclusion in multiple {@link Chain}s that might be
30 * processed by different threads simultaneously. In general, this implies
31 * that {@link Command} classes should not maintain state information in
32 * instance variables. Instead, state information should be maintained via
33 * suitable modifications to the attributes of the {@link Context} that is
34 * passed to the <code>execute()</code> command.</p>
35 *
36 * <p>{@link Command} implementations typically retrieve and store state
37 * information in the {@link Context} instance that is passed as a parameter
38 * to the <code>execute()</code> method, using particular keys into the
39 * <code>Map</code> that can be acquired via
40 * <code>Context.getAttributes()</code>. To improve interoperability of
41 * {@link Command} implementations, a useful design pattern is to expose the
42 * key values used as JavaBeans properties of the {@link Command}
43 * implementation class itself. For example, a {@link Command} that requires
44 * an input and an output key might implement the following properties:</p>
45 *
46 * <pre>
47 * private String inputKey = "input";
48 * public String getInputKey() {
49 * return (this.inputKey);
50 * }
51 * public void setInputKey(String inputKey) {
52 * this.inputKey = inputKey;
53 * }
54 *
55 * private String outputKey = "output";
56 * public String getOutputKey() {
57 * return (this.outputKey);
58 * }
59 * public void setOutputKey(String outputKey) {
60 * this.outputKey = outputKey;
61 * }
62 * </pre>
63 *
64 * <p>And the operation of accessing the "input" information in the context
65 * would be executed by calling:</p>
66 *
67 * <pre>
68 * String input = (String) context.get(getInputKey());
69 * </pre>
70 *
71 * <p>instead of hard coding the attribute name. The use of the "Key"
72 * suffix on such property names is a useful convention to identify properties
73 * being used in this fashion, as opposed to JavaBeans properties that simply
74 * configure the internal operation of this {@link Command}.</p>
75 *
76 * @author Craig R. McClanahan
77 * @version $Revision: 480477 $ $Date: 2006-11-29 08:34:52 +0000 (Wed, 29 Nov 2006) $
78 */
79
80 public interface Command {
81
82 /**
83 * <p>Commands should return <code>CONTINUE_PROCESSING</code> if the processing
84 * of the given {@link Context} should be delegated to a subsequent
85 * {@link Command} in an enclosing {@link Chain}.</p>
86 *
87 * @since Chain 1.1
88 */
89 public static final boolean CONTINUE_PROCESSING = false;
90
91 /**
92 * <p>Commands should return <code>PROCESSING_COMPLETE</code>
93 * if the processing of the given {@link Context}
94 * has been completed.</p>
95 *
96 * @since Chain 1.1
97 */
98 public static final boolean PROCESSING_COMPLETE = true;
99 /**
100 * <p>Execute a unit of processing work to be performed. This
101 * {@link Command} may either complete the required processing
102 * and return <code>true</code>, or delegate remaining processing
103 * to the next {@link Command} in a {@link Chain} containing this
104 * {@link Command} by returning <code>false</code>
105 *
106 * @param context The {@link Context} to be processed by this
107 * {@link Command}
108 *
109 * @exception Exception general purpose exception return
110 * to indicate abnormal termination
111 * @exception IllegalArgumentException if <code>context</code>
112 * is <code>null</code>
113 *
114 * @return <code>true</code> if the processing of this {@link Context}
115 * has been completed, or <code>false</code> if the processing
116 * of this {@link Context} should be delegated to a subsequent
117 * {@link Command} in an enclosing {@link Chain}
118 */
119 boolean execute(Context context) throws Exception;
120
121
122 }