Package com.globalmentor.application

Class BaseCliApplication

  • All Implemented Interfaces:
    Application, com.globalmentor.model.Named<java.lang.String>, io.clogr.Clogged, java.lang.Runnable
    public abstract class BaseCliApplication
extends AbstractApplication
    Base implementation for facilitating creation of a CLI application.

    A concrete application class should create a static MetadataProvider class (an inner class is recommended) extending the abstract metadata provider class, specifying the class of the concrete application itself. This class expects a configuration file with the same name as the concrete application class with a base extension of -config, such as ExampleApp-config.properties, loaded via Confound from the resources in the same path as the application class. For example: 

     
 name=${project.name}
 version=${project.version}

    The provider class should be specified as the version provider, e.g.: 

     
 &#64;Command(name = "foobar", description = "FooBar application.", versionProvider = MetadataProvider.class, mixinStandardHelpOptions = true)

    By default this class merely prints the command-line usage. This can be overridden for programs with specific functionality, but if the application requires a command then the command methods can be added and annotated separately, with the default run() method remaining for displaying an explanation.

    This class sets up the following options:

    --debug, -d
    Turns on debug level logging.
    Author:
    Garret Wilson
    Implementation Specification:
    This implementation adds ANSI support via Jansi.

    • Field Detail

      • CONFIG_KEY_NAME

        public static final java.lang.String CONFIG_KEY_NAME
        The configuration key containing the version of the program.
        See Also:
        Constant Field Values

      • CONFIG_KEY_VERSION

        public static final java.lang.String CONFIG_KEY_VERSION
        The configuration key containing the version of the program.
        See Also:
        Constant Field Values

    • Constructor Detail

      • BaseCliApplication

        public BaseCliApplication​(@Nonnull
                          java.lang.String[] args)
        Arguments constructor.
        Parameters:
        args - The command line arguments.

    • Method Detail

      • getName

        public java.lang.String getName()
        Implementation Specification:
        This implementation retrieves the name from resources for the concrete application class using the resource key "name".
        Throws:
        io.confound.config.ConfigurationException - if there was an error retrieving the configured name or the name could not be found.
        See Also:
        CONFIG_KEY_NAME

      • getVersion

        public java.lang.String getVersion()
        Implementation Specification:
        This implementation retrieves the name from resources for the concrete application class using the resource key "version".
        Returns:
        The application version string .
        Throws:
        io.confound.config.ConfigurationException - if there was an error retrieving the configured name or the name could not be found.
        See Also:
        CONFIG_KEY_VERSION

      • isDebug

        public boolean isDebug()
        Description copied from interface: Application
        Returns whether debug mode is enabled.
        Returns:
        The state of debug mode.

      • setDebug

        protected void setDebug​(boolean debug)
        Enables or disables debug mode, which is disabled by default.
        Parameters:
        debug - The new state of debug mode.

      • updateLogLevel

        protected void updateLogLevel()
        Updates the log level based upon the current debug setting. The current debug setting remains unchanged.

      • initialize

        public void initialize()
                throws java.lang.Exception
        Initializes the application. This method is called after construction but before application execution.
        Specified by:
        initialize in interface Application
        Overrides:
        initialize in class AbstractApplication
        Implementation Specification:
        This implementation calls AnsiConsole.systemInstall().
        Throws:
        java.lang.Exception - if anything goes wrong.

      • execute

        protected int execute()
        Main execution implementation.
        Overrides:
        execute in class AbstractApplication
        Implementation Specification:
        This implementation uses picocli to execute the application using CommandLine.execute(String...).
        Returns:
        The application status:
        0
        Success.
        Any positive exit code.
        There was an error and the application should exit.
        -1
        The application should not exit but continue running, such as for a GUI or daemon application.

      • run

        public void run()
        Implementation Specification:
        The default implementation prints the command-line usage.
        Implementation Note:
        This can be overridden for programs with specific functionality, but if the application requires a command then the command methods can be added and annotated separately, with the default run() method remaining for displaying an explanation.

      • exit

        public void exit​(int status)
        Exits the application immediately with the given status without checking to see if exit should be performed.
        Implementation Specification:
        This implementation calls AnsiConsole.systemUninstall().
        Parameters:
        status - The exit status.
        See Also:
        System.exit(int)

      • reportError

        public void reportError​(@Nonnull
                        java.lang.String message,
                        @Nonnull
                        java.lang.Throwable throwable)
        Reports an error message to the user related to an exception.
        Specified by:
        reportError in interface Application
        Overrides:
        reportError in class AbstractApplication
        Implementation Specification:
        This implementation calls reportError(String), and then logs both the error and exception using Logger.debug(String).
        Implementation Note:
        Double logging allows the message to be presented to the user at Level.INFO level, while still providing a stack trace at Level.DEBUG level, which is likely only enabled in debug mode.
        Parameters:
        message - The message to display.
        throwable - The condition that caused the error.
        See Also:
        Throwable.printStackTrace(PrintStream)

      • reportError

        public void reportError​(java.lang.String message)
        Reports the given error message to the user
        Specified by:
        reportError in interface Application
        Overrides:
        reportError in class AbstractApplication
        Implementation Specification:
        This implementation logs the error using Logger#error(String).
        Parameters:
        message - The error to display.