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
019import java.util.Iterator;
020
021/**
022 * A {@link Catalog} is a collection of named {@link Command}s (or
023 * {@link Chain}s) that can be used to retrieve the set of commands that
024 * should be performed based on a symbolic identifier. Use of catalogs
025 * is optional, but convenient when there are multiple possible chains
026 * that can be selected and executed based on environmental conditions.
027 *
028 * @param <C> Type of the context associated with this command
029 *
030 * @author Craig R. McClanahan
031 * @version $Revision$ $Date$
032 */
033public interface Catalog<C extends Context> {
034
035    /**
036     * A default context attribute for storing a default {@link Catalog},
037     * provided as a convenience only.
038     */
039    String CATALOG_KEY = "org.apache.commons.chain.CATALOG";
040
041    /**
042     * Add a new name and associated {@link Command} or {@link Chain}
043     * to the set of named commands known to this {@link Catalog},
044     * replacing any previous command for that name.
045     *
046     * @param <CMD> the {@link Command} type to be added in the {@link Catalog}
047     * @param name Name of the new command
048     * @param command {@link Command} or {@link Chain} to be returned
049     *        for later lookups on this name
050     */
051    <CMD extends Command<C>> void addCommand(String name, CMD command);
052
053    /**
054     * Return the {@link Command} or {@link Chain} associated with the
055     * specified name, if any; otherwise, return {@code null}.
056     *
057     * @param <CMD> the expected {@link Command} type to be returned
058     * @param name Name for which a {@link Command} or {@link Chain}
059     *        should be retrieved
060     *
061     * @return The Command associated with the specified name.
062     */
063    <CMD extends Command<C>> CMD getCommand(String name);
064
065    /**
066     * Return an {@code Iterator} over the set of named commands
067     * known to this {@link Catalog}. If there are no known commands,
068     * an empty Iterator is returned.
069     *
070     * @return An iterator of the names in this Catalog.
071     */
072    Iterator<String> getNames();
073}