Package cdc.util.cli

Class 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

    • Constructor Detail

      • AbstractMainSupport

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

    • Method Detail

      • 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)

      • getLogger

        protected 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

        @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)

      • 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.

      • 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)
                      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, tries to convert its value to <T> using converter.
        If the conversion succeeds, returns its result, otherwise throws a ParseException.
        If the option is absent, returns the passed def.

        Type Parameters:
        T - The result 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 <Y> type or def.
        Throws:
        org.apache.commons.cli.ParseException - If result could not be converted.

      • fillValues

        public static void fillValues​(org.apache.commons.cli.CommandLine cl,
                              String opt,
                              Collection<String> values)

      • 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
        Throws:
        org.apache.commons.cli.ParseException

      • 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
        Throws:
        org.apache.commons.cli.ParseException

      • 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.

        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
        Throws:
        org.apache.commons.cli.ParseException

      • getValueAsExistingFile

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

      • getValueAsExistingFile

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

      • getValueAsDirectory

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

      • getValueAsDirectory

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

      • getValueAsNullOrExistingFile

        public static File getValueAsNullOrExistingFile​(org.apache.commons.cli.CommandLine cl,
                                                String opt,
                                                File def)
                                         throws org.apache.commons.cli.ParseException
        Returns an option value as an existing file or null.

        If option is absent, returns a default value (possibly null).
        If result is not null and does not exist as a file, throws an exception.
        To obtain a null result :

        • default value must be set to null.
        • option must be absent.
        Parameters:
        cl - The command line.
        opt - The option name.
        def - Default value. MAY BE null.
        Returns:
        The option value or default value. Is either an existing file or null.
        Throws:
        org.apache.commons.cli.ParseException - If result is not null and does not exist.

      • getValueAsNullOrExistingFile

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

      • getValueAsExistingDirectory

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

      • getValueAsExistingDirectory

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

      • getValueAsNullOrExistingDirectory

        public static File getValueAsNullOrExistingDirectory​(org.apache.commons.cli.CommandLine cl,
                                                     String opt,
                                                     File def)
                                              throws org.apache.commons.cli.ParseException
        Returns an option value as an existing directory or null.

        If option is absent, returns a default value (possibly null).
        If result is not null and does not exist as a directory, throws an exception.
        To obtain a null result :

        • default value must be set to null.
        • option must be absent.
        Parameters:
        cl - The command line.
        opt - The option name.
        def - Default value.
        Returns:
        The option value or default value. Is either an existing directory or null.
        Throws:
        org.apache.commons.cli.ParseException - If result is not null and does not exist.

      • getValueAsNullOrExistingDirectory

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

      • getValueAsExistingFileOrDirectory

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

      • getValueAsExistingFileOrDirectory

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

      • getValueAsNullOrExistingFileOrDirectory

        public static File getValueAsNullOrExistingFileOrDirectory​(org.apache.commons.cli.CommandLine cl,
                                                           String opt,
                                                           File def)
                                                    throws org.apache.commons.cli.ParseException
        Returns an option value as an existing file or directory or null.

        If option is absent, returns a default value (possibly null).
        If result is not null and does not exist as a file or directory, throws an exception.
        To obtain a null result :

        • default value must be set to null.
        • option must be absent.
        Parameters:
        cl - The command line.
        opt - The option name.
        def - Default value.
        Returns:
        The option value or default value. Is either an existing file or directory or null.
        Throws:
        org.apache.commons.cli.ParseException - If result is not null and does not exist.

      • getValueAsNullOrExistingFileOrDirectory

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

      • 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

      • 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)