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 }