View Javadoc

1   /*
2   Karma core - Core of the Karma application
3   Copyright (C) 2004  Toolforge <www.toolforge.nl>
4   
5   This library is free software; you can redistribute it and/or
6   modify it under the terms of the GNU Lesser General Public
7   License as published by the Free Software Foundation; either
8   version 2.1 of the License, or (at your option) any later version.
9   
10  This library is distributed in the hope that it will be useful,
11  but WITHOUT ANY WARRANTY; without even the implied warranty of
12  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
13  Lesser General Public License for more details.
14  
15  You should have received a copy of the GNU Lesser General Public
16  License along with this library; if not, write to the Free Software
17  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
18  */
19  package nl.toolforge.karma.core.cmd;
20  
21  import nl.toolforge.karma.core.cmd.event.CommandResponseListener;
22  import org.apache.commons.cli.CommandLine;
23  
24  /***
25   * <p>A <code>Command</code> is an executable operation in Karma. Commands perform actions as per user requests.
26   * <p/>
27   * <p>Karma commands are based on the <code>Option</code> class in the
28   * <a href="http://jakarta.apache.org/commons/cli/apidocs/org/apache/commons/cli/Option.html">Apache</code> package.
29   * Karma wraps an <code>Option</code> and features to it.
30   *
31   * @author D.A. Smedes
32   * @author W.M. Oosterom
33   * @version $Id: Command.java,v 1.20 2004/09/15 20:57:21 asmedes Exp $
34   */
35  public interface Command {
36  
37    /***
38  	 * Gets the normal name of this command (its full name).
39  	 *
40  	 * @return The normal name of this command.
41  	 */
42  	public String getName();
43  
44  	/***
45  	 * Gets the alias for this command (its short name).
46  	 *
47  	 * @return The alias for this command.
48  	 */
49  	public String getAlias();
50  
51  	/***
52  	 * Gets this command's descriptive text. This is merely a one liner for the command, providing its very existence.
53  	 *
54  	 * @return The command's descriptive text.
55  	 */
56  	public String getDescription();
57  
58  	/***
59  	 * The command's help text. Help text can be unlimited. Use <code>HTML</code> for formatting.
60  	 */
61  	public String getHelp();
62  
63  	/***
64  	 * Executes the command.
65  	 *
66  	 * @throws CommandException When execution failed. This exception catches all underlying exceptions and rethrows them
67     *         as a CommandException, except for <code>RuntimeException</code>s.
68  	 */
69  	public void execute() throws CommandException;
70  
71    /***
72     * Called after {@link #execute}. Implementations can use this method to clean up resources and the like.
73     */
74    public void cleanUp();
75  
76  	/***
77  	 * Stores a reference to a <code>CommandContext</code>.
78  	 *
79  	 * @param context An initialized command context.
80  	 */
81  	public void setContext(CommandContext context);
82  
83  	public void setCommandLine(CommandLine commandLine);
84  
85  	/***
86  	 * Gets the parsed command line for this command. This command line can be queried by commands to check if options
87  	 * had been set, or to retrieve application data.
88  	 *
89  	 * @return A command line instance.
90  	 */
91  	public CommandLine getCommandLine();
92  
93    /***
94     * Register the given <code>CommandResponseListener</code> as the handler for the command responses.
95     *
96     * @param responseListener
97     */
98    public void registerCommandResponseListener(CommandResponseListener responseListener);
99  
100   /***
101    * Deregister the <code>CommandResponseListener</code>.
102    */
103   public void deregisterCommandResponseListener(CommandResponseListener responseListener);
104 
105   /***
106    * Return the specific <code>CommandResponse</code> object that this command uses.
107    *
108    * @return CommandResponse
109    */
110   public CommandResponse getCommandResponse();
111 }