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 }