/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.sis.console;

import java.util.Locale;
import java.util.logging.LogManager;
import java.util.logging.ConsoleHandler;
import java.io.Console;
import java.io.PrintStream;
import java.io.PrintWriter;
import java.io.IOException;
import java.sql.SQLException;
import org.opengis.referencing.operation.TransformException;
import org.apache.sis.storage.DataStoreException;
import org.apache.sis.util.ArraysExt;
import org.apache.sis.util.resources.Errors;
import org.apache.sis.util.logging.MonolineFormatter;


/**
 * Command line interface for Apache SIS. The {@link #main(String[])} method accepts the following actions:
 *
 * <blockquote><table class="compact">
 * <caption>Supported command-line actions</caption>
 * <tr><td>{@code help}       </td><td>Show a help overview.</td></tr>
 * <tr><td>{@code about}      </td><td>Show information about Apache SIS and system configuration.</td></tr>
 * <tr><td>{@code mime-type}  </td><td>Show MIME type for the given file.</td></tr>
 * <tr><td>{@code metadata}   </td><td>Show metadata information for the given file.</td></tr>
 * <tr><td>{@code crs}        </td><td>Show Coordinate Reference System information for the given file or code.</td></tr>
 * <tr><td>{@code identifier} </td><td>Show identifiers for metadata and referencing systems in the given file.</td></tr>
 * <tr><td>{@code transform}  </td><td>Convert or transform coordinates from given source CRS to target CRS.</td></tr>
 * </table></blockquote>
 *
 * Each command can accepts some of the following options:
 *
 * <blockquote><table class="compact">
 * <caption>Supported command-line options</caption>
 * <tr><td>{@code --sourceCRS} </td><td>The Coordinate Reference System of input data.</td></tr>
 * <tr><td>{@code --targetCRS} </td><td>The Coordinate Reference System of output data.</td></tr>
 * <tr><td>{@code --format}    </td><td>The output format: {@code xml}, {@code wkt}, {@code wkt1} or {@code text}.</td></tr>
 * <tr><td>{@code --locale}    </td><td>The locale to use for the command output.</td></tr>
 * <tr><td>{@code --timezone}  </td><td>The timezone for the dates to be formatted.</td></tr>
 * <tr><td>{@code --encoding}  </td><td>The encoding to use for the command outputs and some inputs.</td></tr>
 * <tr><td>{@code --colors}    </td><td>Whether colorized output shall be enabled.</td></tr>
 * <tr><td>{@code --brief}     </td><td>Whether the output should contains only brief information.</td></tr>
 * <tr><td>{@code --verbose}   </td><td>Whether the output should contains more detailed information.</td></tr>
 * <tr><td>{@code --debug}     </td><td>Prints full stack trace in case of failure.</td></tr>
 * <tr><td>{@code --help}      </td><td>Lists the options available for a specific command.</td></tr>
 * </table></blockquote>
 *
 * The {@code --locale}, {@code --timezone} and {@code --encoding} options apply to the command output sent
 * to the {@linkplain System#out standard output stream}, but usually do not apply to the error messages sent
 * to the {@linkplain System#err standard error stream}. The reason is that command output may be targeted to
 * a client, while the error messages are usually for the operator.
 *
 * <div class="section">SIS installation on remote machines</div>
 * Some sub-commands can operate on SIS installation on remote machines, provided that remote access has been enabled
 * at the Java Virtual Machine startup time. See {@linkplain org.apache.sis.console package javadoc} for more information.
 *
 * @author  Martin Desruisseaux (Geomatys)
 * @version 0.8
 * @since   0.3
 * @module
 */
public final class Command {
    /**
     * The code given to {@link System#exit(int)} when the program failed because of a unknown sub-command.
     */
    public static final int INVALID_COMMAND_EXIT_CODE = 1;

    /**
     * The code given to {@link System#exit(int)} when the program failed because of a unknown option.
     * The set of valid options depend on the sub-command to execute.
     */
    public static final int INVALID_OPTION_EXIT_CODE = 2;

    /**
     * The code given to {@link System#exit(int)} when the program failed because of an illegal user argument.
     * The user arguments are everything which is not a command name or an option. They are typically file names,
     * but can occasionally be other types like URL.
     */
    public static final int INVALID_ARGUMENT_EXIT_CODE = 3;

    /**
     * The code given to {@link System#exit(int)} when a file given in argument uses an unknown file format.
     */
    public static final int UNKNOWN_STORAGE_EXIT_CODE = 4;

    /**
     * The code given to {@link System#exit(int)} when the program failed because of an {@link java.io.IOException}.
     */
    public static final int IO_EXCEPTION_EXIT_CODE = 100;

    /**
     * The code given to {@link System#exit(int)} when the program failed because of an {@link java.sql.SQLException}.
     */
    public static final int SQL_EXCEPTION_EXIT_CODE = 101;

    /**
     * The code given to {@link System#exit(int)} when the program failed for a reason
     * other than the ones enumerated in the above constants.
     */
    public static final int OTHER_ERROR_EXIT_CODE = 199;

    /**
     * The sub-command to execute.
     */
    private final CommandRunner command;

    /**
     * Creates a new command for the given arguments. The first value in the given array which is
     * not an option is taken as the command name. All other values are options or filenames.
     *
     * @param  args  the command-line arguments.
     * @throws InvalidCommandException if an invalid command has been given.
     * @throws InvalidOptionException if the given arguments contain an invalid option.
     */
    protected Command(final String[] args) throws InvalidCommandException, InvalidOptionException {
        int commandIndex = -1;
        String commandName = null;
        for (int i=0; i<args.length; i++) {
            final String arg = args[i];
            if (arg.startsWith(Option.PREFIX)) {
                final String name = arg.substring(Option.PREFIX.length());
                final Option option = Option.forLabel(name);
                if (option.hasValue) {
                    i++;                        // Skip the next argument.
                }
            } else {
                // Takes the first non-argument option as the command name.
                commandName = arg;
                commandIndex = i;
                break;
            }
        }
        if (commandName == null) {
            command = new HelpCommand(-1, args);
        } else {
            switch (commandName.toLowerCase(Locale.US)) {
                case "help":       command = new HelpCommand      (commandIndex, args); break;
                case "about":      command = new AboutCommand     (commandIndex, args); break;
                case "mime-type":  command = new MimeTypeCommand  (commandIndex, args); break;
                case "metadata":   command = new MetadataCommand  (commandIndex, args); break;
                case "crs":        command = new CRSCommand       (commandIndex, args); break;
                case "identifier": command = new IdentifierCommand(commandIndex, args); break;
                case "transform":  command = new TransformCommand (commandIndex, args); break;
                default: throw new InvalidCommandException(Errors.format(
                            Errors.Keys.UnknownCommand_1, commandName), commandName);
            }
        }
        CommandRunner.instance = command;       // For ResourcesDownloader only.
    }

    /**
     * Runs the command. If an exception occurs, then the exception message is sent to the error output stream
     * before to be thrown. Callers can map the exception to a {@linkplain System#exit(int) system exit code}
     * by the {@link #exitCodeFor(Throwable)} method.
     *
     * @return 0 on success, or an exit code if the command failed for a reason other than a Java exception.
     * @throws Exception if an error occurred during the command execution. This is typically, but not limited, to
     *         {@link IOException}, {@link SQLException}, {@link DataStoreException} or {@link TransformException}.
     */
    public int run() throws Exception {
        if (command.hasContradictoryOptions(Option.BRIEF, Option.VERBOSE)) {
            return INVALID_OPTION_EXIT_CODE;
        }
        if (command.options.containsKey(Option.HELP)) {
            command.help(command.commandName.toLowerCase(Locale.US));
        } else try {
            return command.run();
        } catch (Exception e) {
            command.error(null, e);
            throw e;
        }
        return 0;
    }

    /**
     * Returns the exit code for the given exception, or 0 if unknown. This method iterates through the
     * {@linkplain Throwable#getCause() causes} until an exception matching a {@code *_EXIT_CODE}
     * constant is found.
     *
     * @param  cause  the exception for which to get the exit code.
     * @return the exit code as one of the {@code *_EXIT_CODE} constant, or {@link #OTHER_ERROR_EXIT_CODE} if unknown.
     */
    public static int exitCodeFor(Throwable cause) {
        while (cause != null) {
            if (cause instanceof InvalidCommandException) return INVALID_COMMAND_EXIT_CODE;
            if (cause instanceof InvalidOptionException)  return INVALID_OPTION_EXIT_CODE;
            if (cause instanceof IOException)             return IO_EXCEPTION_EXIT_CODE;
            if (cause instanceof SQLException)            return SQL_EXCEPTION_EXIT_CODE;
            cause = cause.getCause();
        }
        return OTHER_ERROR_EXIT_CODE;
    }

    /**
     * Prints the message of the given exception. This method is invoked only when the error occurred before
     * the {@link CommandRunner} has been built, otherwise the {@link CommandRunner#err} printer shall be used.
     *
     * @param  args  the command line arguments, used only for detecting if the {@code --debug} option was present.
     */
    private static void error(final String[] args, final Exception e) {
        final boolean debug = ArraysExt.containsIgnoreCase(args, Option.PREFIX + "debug");
        final Console console = System.console();
        if (console != null) {
            final PrintWriter err = console.writer();
            if (debug) {
                e.printStackTrace(err);
            } else {
                err.println(e.getLocalizedMessage());
            }
            err.flush();
        } else {
            @SuppressWarnings("UseOfSystemOutOrSystemErr")
            final PrintStream err = System.err;
            if (debug) {
                e.printStackTrace(err);
            } else {
                err.println(e.getLocalizedMessage());
            }
            err.flush();
        }
    }

    /**
     * Prints the information to the standard output stream.
     *
     * @param  args  command-line options.
     */
    public static void main(final String[] args) {
        /*
         * The logging configuration is given by the "conf/logging.properties" file in the Apache SIS
         * installation directory. By default, that configuration file contains the following line:
         *
         *     java.util.logging.ConsoleHandler.formatter = org.apache.sis.util.logging.MonolineFormatter
         *
         * However this configuration is silently ignored by LogManager at JVM startup time, probably
         * because the Apache SIS class is not on the system classpath. So we check again for this
         * configuration line here, and manually install our log formatter only if the above-cited
         * line is present.
         */
        final LogManager manager = LogManager.getLogManager();
        if (MonolineFormatter.class.getName().equals(manager.getProperty(ConsoleHandler.class.getName() + ".formatter"))) {
            MonolineFormatter.install();
        }
        /*
         * Now run the command.
         */
        final Command c;
        try {
            c = new Command(args);
        } catch (InvalidCommandException e) {
            error(args, e);
            System.exit(INVALID_COMMAND_EXIT_CODE);
            return;
        } catch (InvalidOptionException e) {
            error(args, e);
            System.exit(INVALID_OPTION_EXIT_CODE);
            return;
        }
        int status;
        try {
            status = c.run();
        } catch (Exception e) {
            status = exitCodeFor(e);
        }
        if (status != 0) {
            System.exit(status);
        }
    }
}