KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > commons > chain > Command


1 /*
2  * Copyright 2003-2004 The Apache Software Foundation
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
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: 1.5 $ $Date: 2004/02/25 00:01:07 $
77  */
78
79 public interface Command {
80
81
82     /**
83      * <p>Execute a unit of processing work to be performed. This
84      * {@link Command} may either complete the required processing
85      * and return <code>true</code>, or delegate remaining processing
86      * to the next {@link Command} in a {@link Chain} containing this
87      * {@link Command} by returning <code>false</code>
88      *
89      * @param context The {@link Context} to be processed by this
90      * {@link Command}
91      *
92      * @exception Exception general purpose exception return
93      * to indicate abnormal termination
94      * @exception IllegalArgumentException if <code>context</code>
95      * is <code>null</code>
96      *
97      * @return <code>true</code> if the processing of this {@link Context}
98      * has been completed, or <code>false</code> if the processing
99      * of this {@link Context} should be delegated to a subsequent
100      * {@link Command} in an enclosing {@link Chain}
101      */
102     boolean execute(Context context) throws Exception JavaDoc;
103
104
105 }
106
Popular Tags