Module org.refcodes.archetype
Package org.refcodes.archetype

Class CliHelper

java.lang.Object
org.refcodes.archetype.CliHelper
All Implemented Interfaces:
org.refcodes.cli.Optionable, org.refcodes.mixin.VerboseAccessor
Direct Known Subclasses:
AppHelper
public class CliHelper extends Object implements org.refcodes.mixin.VerboseAccessor, org.refcodes.cli.Optionable
The CliHelper provides means to support CLI command line argument parsing.E.g. using the CliHelper you easily can create configuration files ("--init" or "--init path/to/your/config") from a template (found in "src/main/resources"), print a help text ("--help"), show system information ("--sysinfo") for support issues, regard being more verbose ("--verbose") or more quiet ("--quiet"), load a configuration from a specific location ("--config path/to/your/config"), all given that your command line syntax given uses the according predefined args syntax Constituent elements such as HelpFlag, VerboseFlag, QuietFlag, InitFlag, SysInfoFlag, DebugFlag or ConfigOption (and the like). The CliHelper can either be invoked via its constructor or by using the CliHelper.Builder retrieved by invoking the builder() method (allowing you to configure the CliHelper in a more verbose way).

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static class 
    CliHelper.Builder
    Builder to build CliHelper.

    Nested classes/interfaces inherited from interface org.refcodes.mixin.VerboseAccessor

    org.refcodes.mixin.VerboseAccessor.VerboseMutator, org.refcodes.mixin.VerboseAccessor.VerboseProperty

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected org.refcodes.properties.ext.runtime.RuntimeProperties
    _properties
     
    protected static final org.refcodes.runtime.ConfigLocator
    DEFAULT_CONFIG_LOCATOR
     
    protected static final String
    DEFAULT_PASSWORD_PROMPT
     
    protected static final org.refcodes.cli.SyntaxNotation
    DEFAULT_SYNTAX_NOTATION
     

  • Constructor Summary

    Constructors
    Constructor
    Description
    CliHelper(String[] aArgs, char aShortOptionPrefix, String aLongOptionPrefix, org.refcodes.cli.Constituent aArgsSyntax, org.refcodes.cli.SyntaxNotation aSyntaxNotation, Collection<org.refcodes.cli.Example> aExamples, String aDefaultConfig, org.refcodes.runtime.ConfigLocator aConfigLocator, Class<?> aResourceLocator, String aName, String aTitle, String aPasswordPrompt, String aDescription, String aCopyrightNote, String aLicenseNote, org.refcodes.textual.Font aBannerFont, char[] aBannerFontPalette, boolean aVerboseFallback, org.refcodes.logger.RuntimeLogger aLogger, Consumer<Integer> aShutdownHook)
    Creates a new CliHelper using the provided application's RuntimeLogger so that logs produced by the CliHelper are logged according to the application's RuntimeLogger configuration (depending on the RuntimeLogger.ini file).

  • Method Summary

    Modifier and Type
    Method
    Description
    static CliHelper.Builder
    builder()
    Creates builder to build CliHelper.
    void
    createResourceFile(String aResourcePath, File aDestinationFile)
    Copies a resource file (stored in the fat JAR) to the given destination on the file system or (if the destination is not provided) to a file with the name of the resource to the file system.
    void
    createResourceFile(String aResourcePath, String aDestinationPath)
    Copies a resource file (stored in the fat JAR) to the given destination on the file system or (if the destination is not provided) to a file with the name of the resource to the file system.
    void
    exit(int aStatusCode)
    Hook method for exiting the application.
    void
    exit(org.refcodes.data.ExitCode aExitCode)
    Convenience method for exiting the application.
    void
    exitOnException(Throwable e)
    Exits upon a given exception by printing the exception according to any detected VerboseFlag as well as DebugFlag and the retrieved RuntimeProperties (see printException(Exception)) and then exiting with an exit code derived from the exception type.
    org.refcodes.properties.ext.runtime.RuntimeProperties
    getRuntimeProperties()
    Returns the RuntimeProperties as of the provided CLI configuration.
    boolean
    isVerbose()
    Determines the verbose mode by evaluating the VerboseFlag.ALIAS and the QuietFlag.ALIAS properties after having constructed the RuntimeProperties from the command line arguments and the configuration file (e.g. the "quiet" property is false or the "verbose" property is true).
    protected void
    printBanner()
    Prints the application's banner to the console.
    void
    printException(Throwable e)
    Prints the exception according to any detected VerboseFlag as well as DebugFlag and the retrieved RuntimeProperties.
    protected void
    printHelp()
    Prints the application's help to the console.
    void
    printSysInfo()
    Prints system information helpful for debugging cases.
    char[]
    readPassword()
    Reads a password from the console using the configured (or the default) password prompt taking care of the verbose mode table's tail to be printed (in case necessary).
    char[]
    readPassword(String aPrompt)
    Reads a password from the console taking care of the verbose mode table's tail to be printed (in case necessary).
    String[]
    toOptions(org.refcodes.cli.Option<?> aOption)

    Methods inherited from class java.lang.Object

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

  • Field Details

    • DEFAULT_CONFIG_LOCATOR

      protected static final org.refcodes.runtime.ConfigLocator DEFAULT_CONFIG_LOCATOR

    • DEFAULT_SYNTAX_NOTATION

      protected static final org.refcodes.cli.SyntaxNotation DEFAULT_SYNTAX_NOTATION

    • DEFAULT_PASSWORD_PROMPT

      protected static final String DEFAULT_PASSWORD_PROMPT
      See Also:

    • _properties

      protected org.refcodes.properties.ext.runtime.RuntimeProperties _properties

  • Constructor Details

    • CliHelper

      public CliHelper(String[] aArgs, char aShortOptionPrefix, String aLongOptionPrefix, org.refcodes.cli.Constituent aArgsSyntax, org.refcodes.cli.SyntaxNotation aSyntaxNotation, Collection<org.refcodes.cli.Example> aExamples, String aDefaultConfig, org.refcodes.runtime.ConfigLocator aConfigLocator, Class<?> aResourceLocator, String aName, String aTitle, String aPasswordPrompt, String aDescription, String aCopyrightNote, String aLicenseNote, org.refcodes.textual.Font aBannerFont, char[] aBannerFontPalette, boolean aVerboseFallback, org.refcodes.logger.RuntimeLogger aLogger, Consumer<Integer> aShutdownHook)
      Creates a new CliHelper using the provided application's RuntimeLogger so that logs produced by the CliHelper are logged according to the application's RuntimeLogger configuration (depending on the RuntimeLogger.ini file).
      Parameters:
      aArgs - The command line arguments.
      aShortOptionPrefix - The short options' prefix to be set.
      aLongOptionPrefix - The long options' prefix to be set.
      aArgsSyntax - The args syntax root node of your command line syntax.
      aSyntaxNotation - The SyntaxNotation to use.
      aExamples - The Example examples to use when printing out the help.
      aDefaultConfig - The name to your default config file.
      aConfigLocator - The ConfigLocator to use when locating the configuration file (defaults to ConfigLocator.DEFAULT.
      aResourceLocator - The application's Class which to use when loading resources (of the according module) by invoking Class.getResourceAsStream(String).
      aName - The name of your application.
      aTitle - The title of the application.
      aPasswordPrompt - The prompt to use when requesting a password.
      aDescription - The description to use when printing out the help.
      aCopyrightNote - The copyright being applied.
      aLicenseNote - The license for the application.
      aBannerFont - The font for the banner to use.
      aBannerFontPalette - The ASCII color palette for the banner to use.
      aVerboseFallback - The fallback verbose mode if the verbose mode cannot be determined otherwise.
      aLogger - The application's logger.
      aShutdownHook - When provided, then this hook is called instead of System.exit(int) (it is up to the shutdown hook to terminate the application in the end).

  • Method Details

    • exit

      public void exit(int aStatusCode)
      Hook method for exiting the application. By default, System.exit(int) is called, though in a smart phone app, other exit strategies might be required, which can be taken care of by overwriting this method.
      Parameters:
      aStatusCode - The exit code to be passed.

    • exit

      public void exit(org.refcodes.data.ExitCode aExitCode)
      Convenience method for exiting the application. Delegates to the exit(int) method.
      Parameters:
      aExitCode - The exit code ExitCode.getStatusCode() to be passed to exit(int).

    • getRuntimeProperties

      public org.refcodes.properties.ext.runtime.RuntimeProperties getRuntimeProperties()
      Returns the RuntimeProperties as of the provided CLI configuration.
      Returns:
      The according RuntimeProperties instance.

    • isVerbose

      public boolean isVerbose()
      Determines the verbose mode by evaluating the VerboseFlag.ALIAS and the QuietFlag.ALIAS properties after having constructed the RuntimeProperties from the command line arguments and the configuration file (e.g. the "quiet" property is false or the "verbose" property is true). Also takes into account a potentially existing QuietFlag or VerboseFlag given being provided by your command line syntax.
      Specified by:
      isVerbose in interface org.refcodes.mixin.VerboseAccessor
      Returns:
      True in case to be more verbose.

    • printSysInfo

      public void printSysInfo()
      Prints system information helpful for debugging cases.

    • printException

      public void printException(Throwable e)
      Prints the exception according to any detected VerboseFlag as well as DebugFlag and the retrieved RuntimeProperties.
      Parameters:
      e - The Throwable to gracefully print.

    • exitOnException

      public void exitOnException(Throwable e)
      Exits upon a given exception by printing the exception according to any detected VerboseFlag as well as DebugFlag and the retrieved RuntimeProperties (see printException(Exception)) and then exiting with an exit code derived from the exception type.
      Parameters:
      e - The Throwable to gracefully print and from which to derive the exit code.

    • readPassword

      public char[] readPassword()
      Reads a password from the console using the configured (or the default) password prompt taking care of the verbose mode table's tail to be printed (in case necessary).
      Returns:
      The char array representing the password. The array can be cleaned (overridden char by char) afterwards to remove any hints in memory

    • readPassword

      public char[] readPassword(String aPrompt)
      Reads a password from the console taking care of the verbose mode table's tail to be printed (in case necessary).
      Parameters:
      aPrompt - The prompt to print when reading the password.
      Returns:
      The char array representing the password. The array can be cleaned (overridden char by char) afterwards to remove any hints in memory

    • createResourceFile

      public void createResourceFile(String aResourcePath, String aDestinationPath) throws IOException
      Copies a resource file (stored in the fat JAR) to the given destination on the file system or (if the destination is not provided) to a file with the name of the resource to the file system.
      Parameters:
      aResourcePath - The resource to copy from the fat JAR to the file system.
      aDestinationPath - The destination where to copy to or null if to use the name of the resource.
      Throws:
      IOException - thrown in case an I/O related problem occurred during the copy operation.

    • createResourceFile

      public void createResourceFile(String aResourcePath, File aDestinationFile) throws IOException
      Copies a resource file (stored in the fat JAR) to the given destination on the file system or (if the destination is not provided) to a file with the name of the resource to the file system.
      Parameters:
      aResourcePath - The resource to copy from the fat JAR to the file system.
      aDestinationFile - The destination where to copy to or null if to use the name of the resource.
      Throws:
      IOException - thrown in case an I/O related problem occurred during the copy operation.

    • toOptions

      public String[] toOptions(org.refcodes.cli.Option<?> aOption)
      Specified by:
      toOptions in interface org.refcodes.cli.Optionable

    • printBanner

      protected void printBanner()
      Prints the application's banner to the console.

    • printHelp

      protected void printHelp()
      Prints the application's help to the console.

    • builder

      public static CliHelper.Builder builder()
      Creates builder to build CliHelper.
      Returns:
      created builder