View Javadoc

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: 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 }