View Javadoc

1   /*
2    * Copyright 2003-2004 The Apache Software Foundation
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    *     http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  package org.apache.commons.chain;
17  
18  
19  /***
20   * <p>A {@link Chain} represents a configured list of
21   * {@link Command}s that will be executed in order to perform processing
22   * on a specified {@link Context}.  Each included {@link Command} will be
23   * executed in turn, until either one of them returns <code>true</code>,
24   * one of the executed {@link Command}s throws an exception,
25   * or the end of the chain has been reached.  The {@link Chain} itself will
26   * return the return value of the last {@link Command} that was executed
27   * (if no exception was thrown), or rethrow the thrown exception.</p>
28   *
29   * <p>Note that {@link Chain} extends {@link Command}, so that the two can
30   * be used interchangeably when a {@link Command} is expected.  This makes it
31   * easy to assemble workflows in a hierarchical manner by combining subchains
32   * into an overall processing chain.</p>
33   *
34   * <p>To protect applications from evolution of this interface, specialized
35   * implementations of {@link Chain} should generally be created by extending
36   * the provided base class {@link org.apache.commons.chain.impl.ChainBase})
37   * rather than directly implementing this interface.</p>
38   *
39   * <p>{@link Chain} implementations should be designed in a thread-safe
40   * manner, suitable for execution on multiple threads simultaneously.  In
41   * general, this implies that the state information identifying which
42   * {@link Command} is currently being executed should be maintained in a
43   * local variable inside the <code>execute()</code> method, rather than
44   * in an instance variable.  The {@link Command}s in a {@link Chain} may be
45   * configured (via calls to <code>addCommand()</code>) at any time before
46   * the <code>execute()</code> method of the {@link Chain} is first called.
47   * After that, the configuration of the {@link Chain} is frozen.</p>
48   *
49   * @author Craig R. McClanahan
50   * @version $Revision: 155403 $ $Date: 2005-02-26 12:52:46 +0000 (Sat, 26 Feb 2005) $
51   */
52  
53  public interface Chain extends Command {
54  
55  
56      /***
57       * <p>Add a {@link Command} to the list of {@link Command}s that will
58       * be called in turn when this {@link Chain}'s <code>execute()</code>
59       * method is called.  Once <code>execute()</code> has been called
60       * at least once, it is no longer possible to add additional
61       * {@link Command}s; instead, an exception will be thrown.</p>
62       *
63       * @param command The {@link Command} to be added
64       *
65       * @exception IllegalArgumentException if <code>command</code>
66       *  is <code>null</code>
67       * @exception IllegalStateException if this {@link Chain} has already
68       *  been executed at least once, so no further configuration is allowed
69       */
70      void addCommand(Command command);
71  
72  
73      /***
74       * <p>Execute the processing represented by this {@link Chain} according
75       * to the following algorithm.</p>
76       * <ul>
77       * <li>If there are no configured {@link Command}s in the {@link Chain},
78       *     return <code>false</code>.</li>
79       * <li>Call the <code>execute()</code> method of each {@link Command}
80       *     configured on this chain, in the order they were added via calls
81       *     to the <code>addCommand()</code> method, until the end of the
82       *     configured {@link Command}s is encountered, or until one of
83       *     the executed {@link Command}s returns <code>true</code>
84       *     or throws an exception.</li>
85       * <li>Walk backwards through the {@link Command}s whose
86       *     <code>execute()</code> methods, starting with the last one that
87       *     was executed.  If this {@link Command} instance is also a
88       *     {@link Filter}, call its <code>postprocess()</code> method,
89       *     discarding any exception that is thrown.</li>
90       * <li>If the last {@link Command} whose <code>execute()</code> method
91       *     was called threw an exception, rethrow that exception.</li>
92       * <li>Otherwise, return the value returned by the <code>execute()</code>
93       *     method of the last {@link Command} that was executed.  This will be
94       *     <code>true</code> if the last {@link Command} indicated that
95       *     processing of this {@link Context} has been completed, or
96       *     <code>false</code> if none of the called {@link Command}s
97       *     returned <code>true</code>.</li>
98       * </ul>
99       *
100      * @param context The {@link Context} to be processed by this
101      *  {@link Chain}
102      *
103      * @exception Exception if thrown by one of the {@link Command}s
104      *  in this {@link Chain} but not handled by a <code>postprocess()</code>
105      *  method of a {@link Filter}
106      * @exception IllegalArgumentException if <code>context</code>
107      *  is <code>null</code>
108      *
109      * @return <code>true</code> if the processing of this {@link Context}
110      *  has been completed, or <code>false</code> if the processing
111      *  of this {@link Context} should be delegated to a subsequent
112      *  {@link Command} in an enclosing {@link Chain}
113      */
114     boolean execute(Context context) throws Exception;
115 
116 
117 }