Package org.moeaframework.util.cli

Class CommandLineUtility

java.lang.Object
org.moeaframework.util.cli.CommandLineUtility
Direct Known Subclasses:
BuildProblem, CalculateIndicator, DataStoreTool, EndOfRunEvaluator, GeneratePlots, Initialize, JNAInfo, LaunchDiagnosticTool, Main, MetricsAnalysis, MetricsEvaluator, MetricsValidator, ParetoFrontConverter, ReferenceSetGenerator, ResultFileConverter, ResultFileMerger, ResultFileMetadata, ResultFileSeedMerger, ResultFileValidator, ResultFileViewer, RuntimeEvaluator, SampleGenerator, SobolAnalysis, Solve, TestExamples, UpdateCodeSamples, WeightGenerator
public abstract class CommandLineUtility extends Object
Abstract class for providing command line utilities. This class is provided to ensure a standard interface for command line utilities as well as handling the quirks of different operating systems.

By default, Unix-style CLIs are supported where options are passed in using either the single character short form (e.g., -h) or the long form (e.g., --help. Alternatively, if any commands are specified, the CLI behaves more like the Git CLI, where the first positional argument specifies the command to execute. Each command simply invokes its underlying implementation, which is itself another command line utility.

Implementations should provide a main method that invokes start(String[]). Any unhandled exception should be propagated out of the main method, allowing the CLI to exit with a non-zero status code.

  • Constructor Summary

    Constructors
    Constructor
    Description
    CommandLineUtility()
    Constructs a command line utility.

  • Method Summary

    Modifier and Type
    Method
    Description
    protected PrintWriter
    createOutputWriter()
    Creates and returns a writer for printing output from this command line utility.
    protected PrintWriter
    createOutputWriter(File file)
    Creates and returns a writer for printing output from this command line utility.
    protected PrintWriter
    createOutputWriter(String filename)
    Creates and returns a writer for printing output from this command line utility.
    void
    fail(String... message)
    Exits this command line utility with an error.
    List<Command>
    getCommands()
    Return the commands made available by this command line utility.
    protected org.apache.commons.cli.Options
    getLocalizedOptions()
    Returns the options with their descriptions loaded using Localization.
    org.apache.commons.cli.Options
    getOptions()
    Returns the options made available by this command line utility.
    protected String
    getUsageString()
    Returns the formatted usage string.
    protected boolean
    prompt(String prompt)
    Display a confirmation (yes/no) prompt to the user and wait for user input.
    abstract void
    run(org.apache.commons.cli.CommandLine commandLine)
    Runs this command line utility with the specified command line arguments.
    protected void
    runCommand(org.apache.commons.cli.CommandLine commandLine)
    Finds the matching command and invokes its start(String[]) method.
    void
    setAcceptConfirmations(boolean acceptConfirmations)
    Sets the flag to hide and automatically respond to confirmation (yes/no) prompts.
    protected void
    setUsageBuilder(org.moeaframework.util.cli.UsageBuilder usageBuilder)
    Sets the usage builder used to create and format the usage string.
    protected void
    showHelp()
    Format and display the help information that details the available command line options.
    void
    start(String[] args)
    Starts this command line utility with the command line arguments provided by the main method.

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • CommandLineUtility

      public CommandLineUtility()
      Constructs a command line utility. The constructor for subclasses should provide a private constructor unless programmatic access is also desired.

  • Method Details

    • getOptions

      public org.apache.commons.cli.Options getOptions()
      Returns the options made available by this command line utility. The base implementation automatically provides the -h,--help option. Implementations overriding this method and begin with a call to super.getOptions().
      Returns:
      the options made available by this command line utility

    • getCommands

      public List<Command> getCommands()
      Return the commands made available by this command line utility. The base implementation returns an empty list, indicating no commands are configured.
      Returns:
      the commands

    • run

      public abstract void run(org.apache.commons.cli.CommandLine commandLine) throws Exception
      Runs this command line utility with the specified command line arguments.
      Parameters:
      commandLine - the command line arguments
      Throws:
      Exception - if any exception occurred while running this command

    • start

      public void start(String[] args) throws Exception
      Starts this command line utility with the command line arguments provided by the main method. The command line arguments are parsed into a CommandLine object and the run method is invoked.

      At the start of this method, a specialized uncaught exception handler is registered with the calling thread. This exception handler is responsible for formatting and displaying any errors on the command line. Note that this exception handler is not removed at the end of this method; its removal is not necessary when this utility is invoked on the command line.

      Parameters:
      args - the command line arguments
      Throws:
      Exception - if any exception occurred while running this command

    • runCommand

      protected void runCommand(org.apache.commons.cli.CommandLine commandLine) throws Exception
      Finds the matching command and invokes its start(String[]) method. Implementations are expected to call this from their run(CommandLine) method after processing any options.
      Parameters:
      commandLine - the parsed command line
      Throws:
      Exception - if any exception occurred while running this command

    • getLocalizedOptions

      protected org.apache.commons.cli.Options getLocalizedOptions()
      Returns the options with their descriptions loaded using Localization.
      Returns:
      the available command line options

    • showHelp

      protected void showHelp()
      Format and display the help information that details the available command line options.

    • setUsageBuilder

      protected void setUsageBuilder(org.moeaframework.util.cli.UsageBuilder usageBuilder)
      Sets the usage builder used to create and format the usage string.
      Parameters:
      usageBuilder - the usage builder

    • getUsageString

      protected String getUsageString()
      Returns the formatted usage string.
      Returns:
      the formatted usage string

    • setAcceptConfirmations

      public void setAcceptConfirmations(boolean acceptConfirmations)
      Sets the flag to hide and automatically respond to confirmation (yes/no) prompts.
      Parameters:
      acceptConfirmations - if true, accept all confirmation prompts

    • fail

      public void fail(String... message)
      Exits this command line utility with an error.
      Parameters:
      message - the error message

    • prompt

      protected boolean prompt(String prompt)
      Display a confirmation (yes/no) prompt to the user and wait for user input.
      Parameters:
      prompt - the prompt message
      Returns:
      true if the prompt was approved; false otherwise

    • createOutputWriter

      protected PrintWriter createOutputWriter()
      Creates and returns a writer for printing output from this command line utility. The caller is responsible for closing this writer.
      Returns:
      the writer

    • createOutputWriter

      protected PrintWriter createOutputWriter(String filename) throws FileNotFoundException
      Creates and returns a writer for printing output from this command line utility. The caller is responsible for closing this writer.
      Parameters:
      filename - the filename, or null
      Returns:
      the writer
      Throws:
      FileNotFoundException - if opening the file for writing failed

    • createOutputWriter

      protected PrintWriter createOutputWriter(File file) throws FileNotFoundException
      Creates and returns a writer for printing output from this command line utility. The caller is responsible for closing this writer.
      Parameters:
      file - the file, or null
      Returns:
      the writer
      Throws:
      FileNotFoundException - if opening the file for writing failed