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