Package cdc.util.cli

Class AbstractMainSupport<A,R>

java.lang.Object
cdc.util.cli.AbstractMainSupport<A,R>
Type Parameters:
A - MainArgs type.
R - Returned type.
public abstract class AbstractMainSupport<A,R> extends Object
Utility that can be used to create main programs.

The purpose is to force the adoption of a common pattern for such classes.

Some options are automatically defined and handled:

  • help: if passed, help is printed and program is exited.
  • version: if passed, version is printed and program is exited.
    Override getVersion() to define version.
  • args-list <FILE>: if passed, command line arguments are read from the designated file and added to other command line arguments.
    This is useful when command line is too long.
    Override addArgsFileOption(Options) to force its presence.
Args file syntax
The file must contains one argument (option of value) per line.
A line that is empty or starts with any number of white spaces followed by '#' and any other characters is a ignored.
Exemple:
 # (ignored)
 --option1
 --option2
 --option3
 value1
 value2
    # (ignored)
 value3
Author:
Damien Carbonne

  • Field Details

  • Constructor Details

    • AbstractMainSupport

      protected AbstractMainSupport(Class<?> mainClass, org.apache.logging.log4j.Logger logger)

  • Method Details

    • addArgsFileOption

      protected boolean addArgsFileOption(org.apache.commons.cli.Options options)
      Returns true if ARGS_FILE option must be added.

      The default implementation returns true if one option contains multiple values.

      Parameters:
      options - The options.
      Returns:
      true if ARGS_FILE option must be added.

    • addStandardOptions

      protected void addStandardOptions(org.apache.commons.cli.Options options)

    • getMainClass

      public final Class<?> getMainClass()

    • getLogger

      public final org.apache.logging.log4j.Logger getLogger()

    • getVersion

      protected String getVersion()
      Returns the version.

      If null is returned (default implementation), no version option is available.

      Returns:
      The version.

    • getHelpHeader

      protected String getHelpHeader()
      Returns the help header.

      If null is returned (default implementation), no help header is printed.

      Returns:
      The help header.

    • getHelpFooter

      protected String getHelpFooter()
      Returns the help footer.

      If null is returned (default implementation), no help footer is printed.

      Returns:
      The help footer.

    • addSpecificOptions

      protected abstract void addSpecificOptions(org.apache.commons.cli.Options options)
      Creates specific options and add them to an options collection.

      The standard options must not be added.

      Parameters:
      options - The options.

    • analyze

      protected abstract A analyze(org.apache.commons.cli.CommandLine cl) throws org.apache.commons.cli.ParseException
      Analyzes the command line.

      These options are already handled:

      • help
      • version
      • args-file
      Parameters:
      cl - The command line.
      Returns:
      A MainARgs instance.
      Throws:
      org.apache.commons.cli.ParseException - When command line parsing has a problem.

    • execute

      protected abstract R execute(A margs) throws Exception
      Executes the main program.
      Parameters:
      margs - The main arguments.
      Returns:
      The optional result.
      Throws:
      Exception - When program has a problem.

    • addNoArgOptions

      public static <E extends Enum<E> & OptionEnum> void addNoArgOptions(org.apache.commons.cli.Options options, Class<E> enumClass)

    • addGroupedNoArgOptions

      public static <E extends Enum<E> & OptionEnum> void addGroupedNoArgOptions(org.apache.commons.cli.Options options, Class<E> enumClass, boolean required)

    • createGroup

      public static org.apache.commons.cli.OptionGroup createGroup(org.apache.commons.cli.Options options, boolean required, String... opts)

    • createGroup

      public static org.apache.commons.cli.OptionGroup createGroup(org.apache.commons.cli.Options options, String... opts)

    • createGroup

      public static org.apache.commons.cli.OptionGroup createGroup(org.apache.commons.cli.Options options, boolean required, org.apache.commons.cli.Option... opts)

    • createGroup

      public static org.apache.commons.cli.OptionGroup createGroup(org.apache.commons.cli.Options options, org.apache.commons.cli.Option... opts)

    • createGroup

      @SafeVarargs public static <E extends Enum<E> & OptionEnum> org.apache.commons.cli.OptionGroup createGroup(org.apache.commons.cli.Options options, boolean required, E... values)

    • createGroup

      @SafeVarargs public static <E extends Enum<E> & OptionEnum> org.apache.commons.cli.OptionGroup createGroup(org.apache.commons.cli.Options options, E... values)

    • setMask

      public static <E extends Enum<E> & OptionEnum> void setMask(org.apache.commons.cli.CommandLine cl, Class<E> enumClass, AbstractMainSupport.Maskable<E> maskable)

    • removeComments

      static String removeComments(String s)
      Removes the comment part of a string.

      A comment starts with any number of white spaces followed by '#'

      Parameters:
      s - The string
      Returns:
      s with comments removed.

    • main

      public R main(String[] args)
      Default main program.

      This does the following things:

      1. Build options.
      2. Parse the command line strings and creates a CommandLine instance.
      3. Analyze the CommandLine instance and create a MainArgs instance.
      4. Calls execute with the MainArgs instance.
      Parameters:
      args - The command line arguments.
      Returns:
      The optional result.

    • getResult

      public final MainResult getResult()

    • hasArgsFile

      public final boolean hasArgsFile()
      Returns:
      true if an args file was passed and analyzed.
      This shall not be called before main(String[]) is called.

    • getReferencePath

      public final Path getReferencePath()
      Returns the reference directory as a Path.

      It is the directory that contains args-file, if this option has been used, or the current directory otherwise.

      Returns:
      The reference directory.

    • resolveToReferencePath

      public File resolveToReferencePath(File file)

    • getExceptionThrowing

      protected AbstractMainSupport.ExceptionThrowing getExceptionThrowing()
      Returns:
      When exceptions shall be thrown. Default to AbstractMainSupport.ExceptionThrowing.EXECUTION.

    • buildOptions

      protected org.apache.commons.cli.Options buildOptions()
      Creates options, add standard and specific options and returns them.
      Returns:
      The options.

    • getOptionsAsOptional

      protected org.apache.commons.cli.Options getOptionsAsOptional()
      Returns:
      Build all options and make them optional.

    • printHelp

      protected void printHelp(org.apache.commons.cli.Options options, Exception e)

    • printVersion

      protected void printVersion()

    • getValue

      public static <T> T getValue(org.apache.commons.cli.CommandLine cl, String opt, T def, Function<String,T> converter, AbstractMainSupport.ValueChecker<? super T> checker) throws org.apache.commons.cli.ParseException
      Returns the checked conversion of an option value to a type, or a checked default value.

      • If option is present:
        1. tries to convert the option value to <T> using converter.
          If conversion fails, a ParseException is thrown.
        2. then checks the conversion result using checker.
          If check fails, a ParseException is thrown.
        3. then returns the conversion result.
      • If option is absent:
        • checks the def using checker.
          If check fails, a ParseException is thrown.
        • returns def.
      Note: if option is optional, checker should accept def, whether it is null or not.
      Type Parameters:
      T - The returned value type.
      Parameters:
      cl - The command line.
      opt - The option name.
      def - Default value. MAY BE null.
      converter - Function used to convert a String to the expected type.
      checker - The value checker.
      Returns:
      The checked conversion of the option value to <T> type or checked def.
      Throws:
      org.apache.commons.cli.ParseException - If option value could not be converted, or check failed.

    • getValue

      public static <T> T getValue(org.apache.commons.cli.CommandLine cl, String opt, T def, Function<String,T> converter) throws org.apache.commons.cli.ParseException
      Returns the conversion of an option value to a type, or a default value.

      • If the option is present:
        1. tries to convert the option value to <T> using converter.
          If conversion fails, a ParseException is thrown.
        2. then returns the conversion result.
      • If the option is absent: returns def.
      Note: this is equivalent to calling getValue(cl, opt, def, converter, IS_TRUE).
      Type Parameters:
      T - The returned value type.
      Parameters:
      cl - The command line.
      opt - The option name.
      def - Default value. MAY BE null.
      converter - Function used to convert a String to the expected type.
      Returns:
      The conversion of the option value to <T> type or def.
      Throws:
      org.apache.commons.cli.ParseException - If option value could not be converted.

    • fillValues

      public static <T> void fillValues(org.apache.commons.cli.CommandLine cl, String opt, Collection<T> values, Function<String,T> converter, AbstractMainSupport.ValueChecker<? super T> checker) throws org.apache.commons.cli.ParseException
      Adds option values to a collection, after converting and checking them.
      Type Parameters:
      T - The value type.
      Parameters:
      cl - The command line.
      opt - The option name.
      values - The collection of values.
      converter - Function used to convert a String to the expected type.
      checker - The value checker.
      Throws:
      org.apache.commons.cli.ParseException - When a conversion or check failed.

    • fillValues

      public static <T> void fillValues(org.apache.commons.cli.CommandLine cl, String opt, Collection<T> values, Function<String,T> converter) throws org.apache.commons.cli.ParseException
      Adds option values to a collection, after converting them.

      Note: this is equivalent to calling fillValues(cl, opt, values, converter, IS_TRUE).

      Type Parameters:
      T - The value type.
      Parameters:
      cl - The command line.
      opt - The option name.
      values - The collection of values.
      converter - Function used to convert a String to the expected type.
      Throws:
      org.apache.commons.cli.ParseException - When a conversion failed.

    • getValues

      public static <T> List<T> getValues(org.apache.commons.cli.CommandLine cl, String opt, Function<String,T> converter, AbstractMainSupport.ValueChecker<? super T> checker) throws org.apache.commons.cli.ParseException
      Returns the values of an option, converted and checked, as a List.
      Type Parameters:
      T - The value type.
      Parameters:
      cl - The command line.
      opt - The option name.
      converter - Function used to convert a String to the expected type.
      checker - The value checker.
      Returns:
      A List of values.
      Throws:
      org.apache.commons.cli.ParseException - When a conversion or check failed.

    • getValues

      public static <T> List<T> getValues(org.apache.commons.cli.CommandLine cl, String opt, Function<String,T> converter) throws org.apache.commons.cli.ParseException
      Returns the values of an option, converted, as a List.

      Note: this is equivalent to calling getValues(cl, opt, converter, IS_TRUE).

      Type Parameters:
      T - The value type.
      Parameters:
      cl - The command line.
      opt - The option name.
      converter - Function used to convert a String to the expected type.
      Returns:
      A List of values.
      Throws:
      org.apache.commons.cli.ParseException - When a conversion failed.

    • fillValues

      public static void fillValues(org.apache.commons.cli.CommandLine cl, String opt, Collection<String> values)
      Adds the values of an option to a String collection.
      Parameters:
      cl - The command line.
      opt - The option name.
      values - The collection of values.

    • getValues

      public static List<String> getValues(org.apache.commons.cli.CommandLine cl, String opt)
      Returns the values of an option as a String List.
      Parameters:
      cl - The command line.
      opt - The option name.
      Returns:
      The values of option opt as a String List.

    • getValueAsResolvedFile

      public File getValueAsResolvedFile(org.apache.commons.cli.CommandLine cl, String opt, File def, AbstractMainSupport.ValueChecker<? super File> checker) throws org.apache.commons.cli.ParseException
      Returns an option as a resolved file.

      • Converts option to a File or use default value.
      • If this result is null, checks it and returns null.
      • Otherwise, resolve this result using getReferencePath(), checks the resolution and returns it.
      Parameters:
      cl - The command line.
      opt - The option name.
      def - The default value.
      checker - The checker.
      Returns:
      The checked resolved option value or checked default value as a file.
      Throws:
      org.apache.commons.cli.ParseException - When conversion failed or check failed.

    • getValueAsResolvedFile

      public File getValueAsResolvedFile(org.apache.commons.cli.CommandLine cl, String opt, AbstractMainSupport.ValueChecker<? super File> checker) throws org.apache.commons.cli.ParseException
      Returns an option as a resolved file.

      Note: this is equivalent to getValueAsResolvedFile(cl, opt, null, checker).

      Parameters:
      cl - The command line.
      opt - The option name.
      checker - The checker.
      Returns:
      The checked resolved option value or checked null as a file.
      Throws:
      org.apache.commons.cli.ParseException - When conversion failed or check failed.

    • getValueAsResolvedFile

      public File getValueAsResolvedFile(org.apache.commons.cli.CommandLine cl, String opt, File def) throws org.apache.commons.cli.ParseException
      Throws:
      org.apache.commons.cli.ParseException

    • getValueAsResolvedFile

      public File getValueAsResolvedFile(org.apache.commons.cli.CommandLine cl, String opt) throws org.apache.commons.cli.ParseException
      Throws:
      org.apache.commons.cli.ParseException

    • getValueAsFile

      public static File getValueAsFile(org.apache.commons.cli.CommandLine cl, String opt, File def, AbstractMainSupport.ValueChecker<? super File> checker) throws org.apache.commons.cli.ParseException
      Returns an option as a File.

      Note: if option is optional, checker should accept def, whether it is null or not.

      Parameters:
      cl - The command line.
      opt - The option name.
      def - The default value.
      checker - The checker.
      Returns:
      The checked conversion of option to a File or the checked default value.
      Throws:
      org.apache.commons.cli.ParseException - If option value could not be converted to a File, or check failed.

    • getValueAsFile

      public static File getValueAsFile(org.apache.commons.cli.CommandLine cl, String opt, AbstractMainSupport.ValueChecker<? super File> checker) throws org.apache.commons.cli.ParseException
      Returns an option as a File.

      Note: if option is optional, checker should accept null.

      Note: this is equivalent to getValueAsFile(cl, opt, null, checker).

      Parameters:
      cl - The command line.
      opt - The option name.
      checker - The checker.
      Returns:
      The checked conversion of option to a File or the checked null.
      Throws:
      org.apache.commons.cli.ParseException - If option value could not be converted to a File, or check failed.

    • getValueAsFile

      public static File getValueAsFile(org.apache.commons.cli.CommandLine cl, String opt, File def) throws org.apache.commons.cli.ParseException
      Returns an option value as a File.

      If option is absent, returns a default value.
      Result is null only when option does not exist and default value is null.

      Note: this is equivalent to getValueAsFile(cl, opt, def, IS_TRUE).

      Parameters:
      cl - The command line.
      opt - The option name.
      def - Default value.
      Returns:
      The option value as a File.
      Throws:
      org.apache.commons.cli.ParseException - If result could not be produced.

    • getValueAsFile

      public static File getValueAsFile(org.apache.commons.cli.CommandLine cl, String opt) throws org.apache.commons.cli.ParseException
      Returns an option value as a File.

      If option is absent, returns null.

      Note: this is equivalent to getValueAsFile(cl, opt, null, IS_TRUE).

      Parameters:
      cl - The command line.
      opt - The option name.
      Returns:
      The option value as a File.
      Throws:
      org.apache.commons.cli.ParseException - If result could not be produced.

    • getOrCreateValueAsDirectory

      public static File getOrCreateValueAsDirectory(org.apache.commons.cli.CommandLine cl, String opt, File def) throws org.apache.commons.cli.ParseException
      Returns an option value as a Directory, and tries to create it if it does not exist.
      Parameters:
      cl - The command line.
      opt - The option name.
      def - The default value.
      Returns:
      The option value as a Directory, possibly creating it.
      Throws:
      org.apache.commons.cli.ParseException - If result could not be produced.

    • getOrCreateValueAsDirectory

      public static File getOrCreateValueAsDirectory(org.apache.commons.cli.CommandLine cl, String opt) throws org.apache.commons.cli.ParseException
      Returns an option value as a Directory, and tries to create it if it does not exist.
      Parameters:
      cl - The command line.
      opt - The option name.
      Returns:
      The option value as a Directory, possibly creating it.
      Throws:
      org.apache.commons.cli.ParseException - If result could not be produced.

    • getValueAsURL

      public static URL getValueAsURL(org.apache.commons.cli.CommandLine cl, String opt, URL def) throws org.apache.commons.cli.ParseException
      Returns an option value as an URL.

      If option is absent, returns a default value (possibly null).
      If option is present and can be converted to an URL, returns this conversion.
      Otherwise, raises an exception.

      Parameters:
      cl - The command line.
      opt - The option name.
      def - Default value.
      Returns:
      The option value or default value.
      Throws:
      org.apache.commons.cli.ParseException - If option is present and can not be converted to a valid URL.

    • getValueAsURL

      public static URL getValueAsURL(org.apache.commons.cli.CommandLine cl, String opt) throws org.apache.commons.cli.ParseException
      Throws:
      org.apache.commons.cli.ParseException

    • getValueAsCharset

      public static Charset getValueAsCharset(org.apache.commons.cli.CommandLine cl, String opt, Charset def) throws org.apache.commons.cli.ParseException
      Returns an option value as a Charset.

      If option is absent, returns a default value.

      Parameters:
      cl - The command line.
      opt - The option name.
      def - Default value.
      Returns:
      The option value as a Charset.
      Throws:
      org.apache.commons.cli.ParseException - If the option value can not be parsed as a Charset.

    • getValueAsCharset

      public static Charset getValueAsCharset(org.apache.commons.cli.CommandLine cl, String opt) throws org.apache.commons.cli.ParseException
      Throws:
      org.apache.commons.cli.ParseException

    • getValueAsString

      public static String getValueAsString(org.apache.commons.cli.CommandLine cl, String opt, String def)
      Returns an option value as a string.

      If option is absent, returns a default value.

      Parameters:
      cl - The command line.
      opt - The option name.
      def - Default value.
      Returns:
      The option value as a string.

    • getValueAsChar

      public static char getValueAsChar(org.apache.commons.cli.CommandLine cl, String opt, char def) throws org.apache.commons.cli.ParseException
      Returns an option value as a char.

      If option is absent, returns a default value.

      Parameters:
      cl - The command line.
      opt - The option name.
      def - Default value.
      Returns:
      The option value as a char.
      Throws:
      org.apache.commons.cli.ParseException - If the option value can not be parsed as a char.

    • getValueAsChar

      public static Character getValueAsChar(org.apache.commons.cli.CommandLine cl, String opt, Character def) throws org.apache.commons.cli.ParseException
      Throws:
      org.apache.commons.cli.ParseException

    • getValueAsLong

      public static long getValueAsLong(org.apache.commons.cli.CommandLine cl, String opt, long def) throws org.apache.commons.cli.ParseException
      Returns an option value as a long.

      If option is absent, returns a default value.

      Parameters:
      cl - The command line.
      opt - The option name.
      def - Default value.
      Returns:
      The option value as a long.
      Throws:
      org.apache.commons.cli.ParseException - If the option value can not be parsed as a long.

    • getValueAsLong

      public static Long getValueAsLong(org.apache.commons.cli.CommandLine cl, String opt, Long def) throws org.apache.commons.cli.ParseException
      Throws:
      org.apache.commons.cli.ParseException

    • getValueAsInt

      public static int getValueAsInt(org.apache.commons.cli.CommandLine cl, String opt, int def) throws org.apache.commons.cli.ParseException
      Returns an option value as an int.

      If option is absent, returns a default value.

      Parameters:
      cl - The command line.
      opt - The option name.
      def - Default value.
      Returns:
      The option value as an int.
      Throws:
      org.apache.commons.cli.ParseException - If the option value can not be parsed as an int.

    • getValueAsInt

      public static Integer getValueAsInt(org.apache.commons.cli.CommandLine cl, String opt, Integer def) throws org.apache.commons.cli.ParseException
      Throws:
      org.apache.commons.cli.ParseException

    • getValueAsShort

      public static short getValueAsShort(org.apache.commons.cli.CommandLine cl, String opt, short def) throws org.apache.commons.cli.ParseException
      Returns an option value as a short.

      If option is absent, returns a default value.

      Parameters:
      cl - The command line.
      opt - The option name.
      def - Default value.
      Returns:
      The option value as a short.
      Throws:
      org.apache.commons.cli.ParseException - If the option value can not be parsed as a short.

    • getValueAsShort

      public static Short getValueAsShort(org.apache.commons.cli.CommandLine cl, String opt, Short def) throws org.apache.commons.cli.ParseException
      Throws:
      org.apache.commons.cli.ParseException

    • getValueAsByte

      public static byte getValueAsByte(org.apache.commons.cli.CommandLine cl, String opt, byte def) throws org.apache.commons.cli.ParseException
      Returns an option value as a byte.

      If option is absent, returns a default value.

      Parameters:
      cl - The command line.
      opt - The option name.
      def - Default value.
      Returns:
      The option value as a byte.
      Throws:
      org.apache.commons.cli.ParseException - If the option value can not be parsed as a byte.

    • getValueAsByte

      public static Byte getValueAsByte(org.apache.commons.cli.CommandLine cl, String opt, Byte def) throws org.apache.commons.cli.ParseException
      Throws:
      org.apache.commons.cli.ParseException

    • getValueAsDouble

      public static double getValueAsDouble(org.apache.commons.cli.CommandLine cl, String opt, double def) throws org.apache.commons.cli.ParseException
      Returns an option value as a double.

      If option is absent, returns a default value.

      Parameters:
      cl - The command line.
      opt - The option name.
      def - Default value.
      Returns:
      The option value as a double.
      Throws:
      org.apache.commons.cli.ParseException - If the option value can not be parsed as a double.

    • getValueAsDouble

      public static Double getValueAsDouble(org.apache.commons.cli.CommandLine cl, String opt, Double def) throws org.apache.commons.cli.ParseException
      Throws:
      org.apache.commons.cli.ParseException

    • getValueAsFloat

      public static float getValueAsFloat(org.apache.commons.cli.CommandLine cl, String opt, float def) throws org.apache.commons.cli.ParseException
      Returns an option value as a float.

      If option is absent, returns a default value.

      Parameters:
      cl - The command line.
      opt - The option name.
      def - Default value.
      Returns:
      The option value as a float.
      Throws:
      org.apache.commons.cli.ParseException - If the option value can not be parsed as a float.

    • getValueAsFloat

      public static Float getValueAsFloat(org.apache.commons.cli.CommandLine cl, String opt, Float def) throws org.apache.commons.cli.ParseException
      Throws:
      org.apache.commons.cli.ParseException

    • getValueAsEnum

      public static <E extends Enum<E>> E getValueAsEnum(org.apache.commons.cli.CommandLine cl, String opt, Class<E> enumClass, E def) throws org.apache.commons.cli.ParseException
      Returns an option value as a enum.

      If option is absent, returns a default value.

      Type Parameters:
      E - The enum type.
      Parameters:
      cl - The command line.
      opt - The option name.
      enumClass - Enum class
      def - Default value.
      Returns:
      The option value as an enum.
      Throws:
      org.apache.commons.cli.ParseException - If the option value can not be parsed as an enum value.

    • getNumberOfParts

      public static int getNumberOfParts(String s, String sep)

    • getPart

      public static String getPart(String s, String sep, int index, String def)

    • getPart

      public static String getPart(String s, String sep, int index)