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 */
017package org.apache.commons.chain;
018
019/**
020 * A {@link Command} encapsulates a unit of processing work to be
021 * performed, whose purpose is to examine and/or modify the state of a
022 * transaction that is represented by a {@link Context}. Individual
023 * {@link Command}s can be assembled into a {@link Chain}, which allows
024 * them to either complete the required processing or delegate further
025 * processing to the next {@link Command} in the {@link Chain}.
026 *
027 * <p>{@link Command} implementations should be designed in a thread-safe
028 * manner, suitable for inclusion in multiple {@link Chain}s that might be
029 * processed by different threads simultaneously. In general, this implies
030 * that {@link Command} classes should not maintain state information in
031 * instance variables. Instead, state information should be maintained via
032 * suitable modifications to the attributes of the {@link Context} that is
033 * passed to the {@code execute()} command.</p>
034 *
035 * <p>{@link Command} implementations typically retrieve and store state
036 * information in the {@link Context} instance that is passed as a parameter
037 * to the {@code execute()} method, using particular keys into the
038 * {@code Map} that can be acquired via {@code Context.getAttributes()}. To
039 * improve interoperability of {@link Command} implementations, a useful
040 * design pattern is to expose the key values used as JavaBeans properties
041 * of the {@link Command} implementation class itself. For example, a
042 * {@link Command} that requires an input and an output key might implement
043 * the following properties:</p>
044 *
045 * <pre>
046 *   private String inputKey = "input";
047 *   public String getInputKey() {
048 *     return this.inputKey;
049 *   }
050 *   public void setInputKey(String inputKey) {
051 *     this.inputKey = inputKey;
052 *   }
053 *
054 *   private String outputKey = "output";
055 *   public String getOutputKey() {
056 *     return this.outputKey;
057 *   }
058 *   public void setOutputKey(String outputKey) {
059 *     this.outputKey = outputKey;
060 *   }
061 * </pre>
062 *
063 * <p>And the operation of accessing the "input" information in the context
064 * would be executed by calling:</p>
065 *
066 * <pre>
067 *   String input = (String) context.get(getInputKey());
068 * </pre>
069 *
070 * <p>instead of hard coding the attribute name. The use of the "Key"
071 * suffix on such property names is a useful convention to identify properties
072 * being used in this fashion, as opposed to JavaBeans properties that simply
073 * configure the internal operation of this {@link Command}.</p>
074 *
075 * @param <C> Type of the context associated with this command
076 *
077 * @author Craig R. McClanahan
078 * @version $Revision$ $Date$
079 */
080public interface Command<C extends Context> {
081
082    /**
083     * Commands should return {@code CONTINUE_PROCESSING} if the processing
084     * of the given {@link Context} should be delegated to a subsequent
085     * {@link Command} in an enclosing {@link Chain}.
086     *
087     * @since Chain 1.1
088     */
089    boolean CONTINUE_PROCESSING = false;
090
091    /**
092     * Commands should return {@code PROCESSING_COMPLETE}
093     * if the processing of the given {@link Context}
094     * has been completed.
095     *
096     * @since Chain 1.1
097     */
098    boolean PROCESSING_COMPLETE = true;
099
100    /**
101     * Execute a unit of processing work to be performed. This
102     * {@link Command} may either complete the required processing
103     * and return {@code true}, or delegate remaining processing
104     * to the next {@link Command} in a {@link Chain} containing this
105     * {@link Command} by returning {@code false}.
106     *
107     * @param context The {@link Context} to be processed by this
108     *        {@link Command}
109     *
110     * @return {@code true} if the processing of this {@link Context}
111     *         has been completed, or {@code false} if the processing
112     *         of this {@link Context} should be delegated to a
113     *         subsequent {@link Command} in an enclosing {@link Chain}
114     *
115     * @throws Exception general purpose exception return
116     *         to indicate abnormal termination
117     * @throws IllegalArgumentException if {@code context}
118     *         is {@code null}
119     */
120    boolean execute(C context) throws Exception;
121}