001    // Copyright 2005 The Apache Software Foundation
002    //
003    // Licensed under the Apache License, Version 2.0 (the "License");
004    // you may not use this file except in compliance with the License.
005    // You may obtain a copy of the License at
006    //
007    //     http://www.apache.org/licenses/LICENSE-2.0
008    //
009    // Unless required by applicable law or agreed to in writing, software
010    // distributed under the License is distributed on an "AS IS" BASIS,
011    // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
012    // See the License for the specific language governing permissions and
013    // limitations under the License.
014    
015    package org.apache.hivemind.lib.chain;
016    
017    import java.util.List;
018    
019    /**
020     * Service interface for <code>hivemind.lib.ChainBuilder</code>, a service which can assemble an
021     * implementation based on a command interface, and an ordered list of objects implementing that
022     * interface (the "commands"). This is an implementation of the Gang of Four Chain Of Command
023     * pattern.
024     * <p>
025     * For each method in the interface, the chain implementation will call the corresponding method on
026     * each command object in turn. If any of the command objects return true, then the chain of command
027     * stops and the initial method invocation returns true. Otherwise, the chain of command continues
028     * to the next command (and will return false if none of the commands returns true).
029     * <p>
030     * For methods whose return type is not boolean, the chain stops with the first non-null (for object
031     * types), or non-zero (for numeric types). The chain returns the value that was returned by the
032     * command. The chain If the method return type is void, all command will be invoked.
033     * <p>
034     * Method invocations will also be terminated if an exception is thrown.
035     * 
036     * @author Howard M. Lewis Ship
037     * @since 1.1
038     */
039    public interface ChainBuilder
040    {
041        /**
042         * Builds an implementation.
043         * 
044         * @param commandInterface
045         *            the interface the implementation implements.
046         * @param commands
047         *            a non-null list of command objects implementing the interface.
048         * @param toString
049         *            The value to be returned from the implementation's <code>toString()</code>
050         *            method (unless <code>toString()</code> is expressly part of the service
051         *            interface, in which case it is treated as any other method.
052         */
053        public Object buildImplementation(Class commandInterface, List commands, String toString);
054    }