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
015package org.apache.hivemind.lib.chain;
016
017import 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 */
039public 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}