001: /*
002: * Copyright 2003-2004 The Apache Software Foundation
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016: package org.apache.commons.chain;
017:
018: /**
019: * <p>A {@link Command} encapsulates a unit of processing work to be
020: * performed, whose purpose is to examine and/or modify the state of a
021: * transaction that is represented by a {@link Context}. Individual
022: * {@link Command}s can be assembled into a {@link Chain}, which allows
023: * them to either complete the required processing or delegate further
024: * processing to the next {@link Command} in the {@link Chain}.</p>
025: *
026: * <p>{@link Command} implementations should be designed in a thread-safe
027: * manner, suitable for inclusion in multiple {@link Chain}s that might be
028: * processed by different threads simultaneously. In general, this implies
029: * that {@link Command} classes should not maintain state information in
030: * instance variables. Instead, state information should be maintained via
031: * suitable modifications to the attributes of the {@link Context} that is
032: * passed to the <code>execute()</code> command.</p>
033: *
034: * <p>{@link Command} implementations typically retrieve and store state
035: * information in the {@link Context} instance that is passed as a parameter
036: * to the <code>execute()</code> method, using particular keys into the
037: * <code>Map</code> that can be acquired via
038: * <code>Context.getAttributes()</code>. To improve interoperability of
039: * {@link Command} implementations, a useful design pattern is to expose the
040: * key values used as JavaBeans properties of the {@link Command}
041: * implementation class itself. For example, a {@link Command} that requires
042: * an input and an output key might implement the following properties:</p>
043: *
044: * <pre>
045: * private String inputKey = "input";
046: * public String getInputKey() {
047: * return (this.inputKey);
048: * }
049: * public void setInputKey(String inputKey) {
050: * this.inputKey = inputKey;
051: * }
052: *
053: * private String outputKey = "output";
054: * public String getOutputKey() {
055: * return (this.outputKey);
056: * }
057: * public void setOutputKey(String outputKey) {
058: * this.outputKey = outputKey;
059: * }
060: * </pre>
061: *
062: * <p>And the operation of accessing the "input" information in the context
063: * would be executed by calling:</p>
064: *
065: * <pre>
066: * String input = (String) context.get(getInputKey());
067: * </pre>
068: *
069: * <p>instead of hard coding the attribute name. The use of the "Key"
070: * suffix on such property names is a useful convention to identify properties
071: * being used in this fashion, as opposed to JavaBeans properties that simply
072: * configure the internal operation of this {@link Command}.</p>
073: *
074: * @author Craig R. McClanahan
075: * @version $Revision: 411876 $ $Date: 2006-06-05 19:02:19 +0100 (Mon, 05 Jun 2006) $
076: */
077:
078: public interface Command {
079:
080: /**
081: * <p>Commands should return <code>CONTINUE_PROCESSING</code> if the processing
082: * of the given {@link Context} should be delegated to a subsequent
083: * {@link Command} in an enclosing {@link Chain}.</p>
084: *
085: * @since Chain 1.1
086: */
087: public static final boolean CONTINUE_PROCESSING = false;
088:
089: /**
090: * <p>Commands should return <code>PROCESSING_COMPLETE</code>
091: * if the processing of the given {@link Context}
092: * has been completed.</p>
093: *
094: * @since Chain 1.1
095: */
096: public static final boolean PROCESSING_COMPLETE = true;
097:
098: /**
099: * <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: }
|