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}