Package com.globalmentor.application

Class BaseCliApplication

java.lang.Object

com.globalmentor.application.AbstractApplication

com.globalmentor.application.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 subclass should annotate itself as the main command, e.g.:

 
 @Command(name = "foobar", description = "FooBar application.")
 
 

This class expects a configuration file with the same name as the concrete application class (the subclass of this class) with a base extension of -config, loaded via Confound from the resources in the same path as the application class. For example the following might be stored as ExampleApp-config.properties:

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

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 mode and enables debug level logging.

--trace

Enables trace level logging.

Author:

Garret Wilson

Implementation Specification:

This implementation adds ANSI support via Jansi.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
protected static class	BaseCliApplication.MetadataProvider	Strategy for retrieving the application name and version from the configuration.

Field Summary

Fields

Modifier and Type	Field	Description
static java.lang.String	CONFIG_KEY_NAME	The configuration key containing the version of the program.
static java.lang.String	CONFIG_KEY_VERSION	The configuration key containing the version of the program.

Fields inherited from interface com.globalmentor.application.Application

EXIT_CODE_CONTINUE, EXIT_CODE_OK, EXIT_CODE_SOFTWARE, EXIT_CODE_USAGE, NO_ARGUMENTS

Constructor Summary

Constructors

Constructor	Description
BaseCliApplication(java.lang.String[] args)	Arguments constructor.
BaseCliApplication(java.lang.String[] args, org.slf4j.event.Level defaultLogLevel)	Arguments constructor.

Method Summary

Modifier and Type	Method	Description
protected int	execute()	Main execution implementation.
void	exit(int status)	Exits the application immediately with the given status without checking to see if exit should be performed.
java.lang.String	getName()
java.lang.String	getVersion()
void	initialize()	Initializes the application.
boolean	isDebug()	Returns whether debug mode is enabled.
void	reportError(java.lang.String message)	Reports the given error message to the user
void	reportError(java.lang.String message, java.lang.Throwable throwable)	Reports an error message to the user related to an exception.
void	reportError(java.lang.Throwable throwable)	Reports an error condition to the user.
void	run()
protected void	setDebug(boolean debug)	Enables or disables debug mode and debug level logging, which is disabled by default.
protected void	setTrace(boolean trace)	Enables or disables trace level logging, which is disabled by default.
protected void	updateLogLevel()	Updates the log level based upon the current debug setting.

Methods inherited from class com.globalmentor.application.AbstractApplication

canEnd, canStart, end, getArgs, getAuthenticator, getExpirationDate, getPreferences, setAuthenticator, setExpirationDate, start, toErrorMessage

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.globalmentor.application.Application

end

Methods inherited from interface io.clogr.Clogged

getLogger

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.

Implementation Specification:

The Level.WARN log level is used by default if no other log level-related options are indicated.

Parameters:

args - The command line arguments.

BaseCliApplication

public BaseCliApplication(@Nonnull
                          java.lang.String[] args,
                          org.slf4j.event.Level defaultLogLevel)

Arguments constructor.

Parameters:

args - The command line arguments.

defaultLogLevel - The default log level to use if no other log level-related options are indicated.

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 and debug level logging, which is disabled by default.

Parameters:

debug - The new state of debug mode.

setTrace

protected void setTrace(boolean trace)

Enables or disables trace level logging, which is disabled by default.

API Note:

This method does not turn on debug mode, so if debug mode is desired along with trace logging, be sure and call setDebug(boolean) as well.

Parameters:

trace - The new state of trace mode.

updateLogLevel

protected void updateLogLevel()

Updates the log level based upon the current debug setting. The current debug setting remains unchanged.

Implementation Specification:

If no log level-related options are indicated the defaultLogLevel is used.

See Also:

isDebug(), isTrace()

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(java.lang.Throwable throwable)

Reports an error condition to the user. A message will be added as appropriate.

Specified by:

reportError in interface Application

Overrides:

reportError in class AbstractApplication

Implementation Specification:

This version delegates to reportError(String, Throwable) using the message determined by AbstractApplication.toErrorMessage(Throwable).

Parameters:

throwable - The condition that caused the error.

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.