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 Chain} represents a configured list of 021 * {@link Command}s that will be executed in order to perform processing 022 * on a specified {@link Context}. Each included {@link Command} will be 023 * executed in turn, until either one of them returns {@code true}, 024 * one of the executed {@link Command}s throws an exception, 025 * or the end of the chain has been reached. The {@link Chain} itself will 026 * return the return value of the last {@link Command} that was executed 027 * (if no exception was thrown), or rethrow the thrown exception. 028 * 029 * <p>Note that {@link Chain} extends {@link Command}, so that the two can 030 * be used interchangeably when a {@link Command} is expected. This makes it 031 * easy to assemble workflows in a hierarchical manner by combining subchains 032 * into an overall processing chain.</p> 033 * 034 * <p>To protect applications from evolution of this interface, specialized 035 * implementations of {@link Chain} should generally be created by extending 036 * the provided base class {@link org.apache.commons.chain.impl.ChainBase}) 037 * rather than directly implementing this interface.</p> 038 * 039 * <p>{@link Chain} implementations should be designed in a thread-safe 040 * manner, suitable for execution on multiple threads simultaneously. In 041 * general, this implies that the state information identifying which 042 * {@link Command} is currently being executed should be maintained in a 043 * local variable inside the {@code execute()} method, rather than 044 * in an instance variable. The {@link Command}s in a {@link Chain} may be 045 * configured (via calls to {@code addCommand()}) at any time before 046 * the {@code execute()} method of the {@link Chain} is first called. 047 * After that, the configuration of the {@link Chain} is frozen.</p> 048 * 049 * @param <C> Type of the context associated with this chain 050 * 051 * @author Craig R. McClanahan 052 * @version $Revision$ $Date$ 053 */ 054public interface Chain<C extends Context> extends Command<C> { 055 056 /** 057 * Add a {@link Command} to the list of {@link Command}s that will 058 * be called in turn when this {@link Chain}'s {@code execute()} 059 * method is called. Once {@code execute()} has been called 060 * at least once, it is no longer possible to add additional 061 * {@link Command}s; instead, an exception will be thrown. 062 * 063 * @param <CMD> the {@link Command} type to be added in the {@link Chain} 064 * @param command The {@link Command} to be added 065 * 066 * @throws IllegalArgumentException if {@code command} 067 * is {@code null} 068 * @throws IllegalStateException if this {@link Chain} has already 069 * been executed at least once, so no further configuration 070 * is allowed 071 */ 072 <CMD extends Command<C>> void addCommand(CMD command); 073 074 /** 075 * Execute the processing represented by this {@link Chain} according 076 * to the following algorithm. 077 * <ul> 078 * <li>If there are no configured {@link Command}s in the {@link Chain}, 079 * return {@code false}.</li> 080 * <li>Call the {@code execute()} method of each {@link Command} 081 * configured on this chain, in the order they were added via calls 082 * to the {@code addCommand()} method, until the end of the 083 * configured {@link Command}s is encountered, or until one of 084 * the executed {@link Command}s returns {@code true} 085 * or throws an exception.</li> 086 * <li>Walk backwards through the {@link Command}s whose 087 * {@code execute()} methods, starting with the last one that 088 * was executed. If this {@link Command} instance is also a 089 * {@link Filter}, call its {@code postprocess()} method, 090 * discarding any exception that is thrown.</li> 091 * <li>If the last {@link Command} whose {@code execute()} method 092 * was called threw an exception, rethrow that exception.</li> 093 * <li>Otherwise, return the value returned by the {@code execute()} 094 * method of the last {@link Command} that was executed. This will be 095 * {@code true} if the last {@link Command} indicated that 096 * processing of this {@link Context} has been completed, or 097 * {@code false} if none of the called {@link Command}s 098 * returned {@code true}.</li> 099 * </ul> 100 * 101 * @param context The {@link Context} to be processed by this 102 * {@link Chain} 103 * 104 * @return {@code true} if the processing of this {@link Context} 105 * has been completed, or {@code false} if the processing 106 * of this {@link Context} should be delegated to a 107 * subsequent {@link Command} in an enclosing {@link Chain} 108 * 109 * @throws Exception if thrown by one of the {@link Command}s 110 * in this {@link Chain} but not handled by a 111 * {@code postprocess()} method of a {@link Filter} 112 * @throws IllegalArgumentException if {@code context} 113 * is {@code null} 114 */ 115 @Override 116 boolean execute(C context) throws Exception; 117}