001/*
002 * Copyright (C) 2009 Christian Schulte <cs@schulte.it>
003 * All rights reserved.
004 *
005 * Redistribution and use in source and binary forms, with or without
006 * modification, are permitted provided that the following conditions
007 * are met:
008 *
009 *   o Redistributions of source code must retain the above copyright
010 *     notice, this list of conditions and the following disclaimer.
011 *
012 *   o Redistributions in binary form must reproduce the above copyright
013 *     notice, this list of conditions and the following disclaimer in
014 *     the documentation and/or other materials provided with the
015 *     distribution.
016 *
017 * THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
018 * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
019 * AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
020 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY DIRECT, INDIRECT,
021 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
022 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
023 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
024 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
025 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
026 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
027 *
028 * $JOMC: Command.java 5215 2016-04-24 06:54:04Z schulte $
029 *
030 */
031package org.jomc.cli;
032
033import java.util.List;
034import java.util.Locale;
035import java.util.logging.Level;
036import org.apache.commons.cli.CommandLine;
037import org.apache.commons.cli.Options;
038
039/**
040 * Command.
041 *
042 * @author <a href="mailto:cs@schulte.it">Christian Schulte</a>
043 */
044public interface Command
045{
046
047    /**
048     * Listener interface.
049     */
050    public interface Listener
051    {
052
053        /**
054         * Gets called on logging.
055         *
056         * @param level The level of the event.
057         * @param message The message of the event or {@code null}.
058         * @param t The throwable of the event or {@code null}.
059         *
060         * @throws NullPointerException if {@code level} is {@code null}.
061         */
062        void onLog( Level level, String message, Throwable t );
063
064    }
065
066    /**
067     * Status code when the command completed successfully.
068     */
069    int STATUS_SUCCESS = 0;
070
071    /**
072     * Status code when the command failed.
073     */
074    int STATUS_FAILURE = 1;
075
076    /**
077     * Gets the list of registered listeners.
078     *
079     * @return The list of registered listeners.
080     */
081    List<Listener> getListeners();
082
083    /**
084     * Gets the log level of the instance.
085     *
086     * @return The log level of the instance.
087     *
088     * @see #setLogLevel(java.util.logging.Level)
089     */
090    Level getLogLevel();
091
092    /**
093     * Sets the log level of the instance.
094     *
095     * @param value The new log level of the instance or {@code null}.
096     *
097     * @see #getLogLevel()
098     */
099    void setLogLevel( Level value );
100
101    /**
102     * Gets the name of the command.
103     *
104     * @return The name of the command.
105     */
106    String getName();
107
108    /**
109     * Gets the abbreviated name of the command.
110     *
111     * @return The abbreviated name of the command.
112     */
113    String getAbbreviatedName();
114
115    /**
116     * Gets the short description of the command.
117     *
118     * @param locale The locale of the short description to return.
119     *
120     * @return The short description of the command.
121     *
122     * @throws NullPointerException if {@code locale} is {@code null}.
123     */
124    String getShortDescription( Locale locale ) throws NullPointerException;
125
126    /**
127     * Gets the long description of the command.
128     *
129     * @param locale The locale of the long description to return.
130     *
131     * @return The long description of the command.
132     *
133     * @throws NullPointerException if {@code locale} is {@code null}.
134     */
135    String getLongDescription( Locale locale ) throws NullPointerException;
136
137    /**
138     * Gets the options of the command.
139     *
140     * @return The options of the command.
141     */
142    Options getOptions();
143
144    /**
145     * Executes the command.
146     *
147     * @param commandLine Command line to execute.
148     *
149     * @return The status code to report.
150     *
151     * @throws NullPointerException if {@code commandLine} is {@code null}.
152     *
153     * @see #STATUS_SUCCESS
154     * @see #STATUS_FAILURE
155     */
156    int execute( CommandLine commandLine ) throws NullPointerException;
157
158}