View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *     http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.commons.chain;
18  
19  import java.util.Iterator;
20  
21  /**
22   * A {@link Catalog} is a collection of named {@link Command}s (or
23   * {@link Chain}s) that can be used to retrieve the set of commands that
24   * should be performed based on a symbolic identifier. Use of catalogs
25   * is optional, but convenient when there are multiple possible chains
26   * that can be selected and executed based on environmental conditions.
27   *
28   * @param <C> Type of the context associated with this command
29   *
30   * @author Craig R. McClanahan
31   * @version $Revision$ $Date$
32   */
33  public interface Catalog<C extends Context> {
34  
35      /**
36       * A default context attribute for storing a default {@link Catalog},
37       * provided as a convenience only.
38       */
39      String CATALOG_KEY = "org.apache.commons.chain.CATALOG";
40  
41      /**
42       * Add a new name and associated {@link Command} or {@link Chain}
43       * to the set of named commands known to this {@link Catalog},
44       * replacing any previous command for that name.
45       *
46       * @param <CMD> the {@link Command} type to be added in the {@link Catalog}
47       * @param name Name of the new command
48       * @param command {@link Command} or {@link Chain} to be returned
49       *        for later lookups on this name
50       */
51      <CMD extends Command<C>> void addCommand(String name, CMD command);
52  
53      /**
54       * Return the {@link Command} or {@link Chain} associated with the
55       * specified name, if any; otherwise, return {@code null}.
56       *
57       * @param <CMD> the expected {@link Command} type to be returned
58       * @param name Name for which a {@link Command} or {@link Chain}
59       *        should be retrieved
60       *
61       * @return The Command associated with the specified name.
62       */
63      <CMD extends Command<C>> CMD getCommand(String name);
64  
65      /**
66       * Return an {@code Iterator} over the set of named commands
67       * known to this {@link Catalog}. If there are no known commands,
68       * an empty Iterator is returned.
69       *
70       * @return An iterator of the names in this Catalog.
71       */
72      Iterator<String> getNames();
73  }