Package ubic.gemma.cli.util

Class AbstractCLI

java.lang.Object
ubic.gemma.cli.util.AbstractCLI
All Implemented Interfaces:
org.springframework.beans.factory.Aware, org.springframework.context.ApplicationContextAware, CLI
Direct Known Subclasses:
AbstractAuthenticatedCLI, GenerateDatabaseUpdateCli, IndexGemmaCLI, InitializeDatabaseCli, ListExpressionDataFIleLocksCli, MeshTermFetcherCli, SingleCellDataDownloaderCli, SingleCellDataTransformCli, UnifiedOntologyUpdaterCli, UpdateDatabaseCli
public abstract class AbstractCLI extends Object implements CLI, org.springframework.context.ApplicationContextAware
Basic implementation of the CLI interface.

To use this, in your concrete subclass, implement buildOptions(org.apache.commons.cli.Options) and processOptions(org.apache.commons.cli.CommandLine) to handle any application-specific options (they can be no-ops) and doWork() to perform the actual work of the CLI.

Use AbstractAuthenticatedCLI if you need to authenticate the user.

Author:
pavlidis

  • Field Details

    • log

      protected final org.apache.commons.logging.Log log

    • SUCCESS

      protected static final int SUCCESS
      Exit code used for a successful doWork() execution.
      See Also:

    • FAILURE

      protected static final int FAILURE
      Exit code used for a failed doWork() execution.
      See Also:

    • FAILURE_FROM_ERROR_OBJECTS

      protected static final int FAILURE_FROM_ERROR_OBJECTS
      Exit code used for a successful doWork execution that resulted in failed error objects.
      See Also:

    • ABORTED

      protected static final int ABORTED
      Exit code used when a doWork() is aborted.
      See Also:

  • Constructor Details

    • AbstractCLI

      public AbstractCLI()

  • Method Details

    • getCommandName

      public String getCommandName()
      Description copied from interface: CLI
      A short memorable name for the command that can be used to locate this class.
      Specified by:
      getCommandName in interface CLI
      Returns:
      name; if null or blank, this will not be available as a shortcut command.

    • getCommandAliases

      public List<String> getCommandAliases()
      Description copied from interface: CLI
      A list of aliases for the command that can be used to locate this class.
      Specified by:
      getCommandAliases in interface CLI

    • getShortDesc

      public String getShortDesc()
      Description copied from interface: CLI
      Obtain a short description for this command explaining what it does.
      Specified by:
      getShortDesc in interface CLI

    • getCommandGroup

      public CLI.CommandGroup getCommandGroup()
      Description copied from interface: CLI
      Obtain the command group for this CLI.
      Specified by:
      getCommandGroup in interface CLI

    • getOptions

      public org.apache.commons.cli.Options getOptions()
      Description copied from interface: CLI
      Obtain the options for the CLI.
      Specified by:
      getOptions in interface CLI

    • allowPositionalArguments

      public boolean allowPositionalArguments()
      Description copied from interface: CLI
      Indicate if this CLI allows positional arguments.
      Specified by:
      allowPositionalArguments in interface CLI

    • executeCommand

      public final void executeCommand(CLIContext cliContext)
      Execute the given command given CLI arguments.

      Parse and process CLI arguments, invoke the command doWork() implementation, and print basic statistics about time usage.

      Any exception raised by doWork results in a value of FAILURE, and any error set in the internal error objects will result in a value of FAILURE_FROM_ERROR_OBJECTS.

      Specified by:
      executeCommand in interface CLI

    • getApplicationContext

      public final org.springframework.context.ApplicationContext getApplicationContext()
      Obtain the application context.

      Beans in a CLI context are usually lazily-initialized as using LazyInitByDefaultPostProcessor, so using the context to create beans ensures that only the necessary beans are created.

    • setApplicationContext

      public final void setApplicationContext(org.springframework.context.ApplicationContext applicationContext)
      Specified by:
      setApplicationContext in interface org.springframework.context.ApplicationContextAware

    • getCliContext

      protected final CLIContext getCliContext()
      Obtain the CLI context.

      This is only valid for the duration of the executeCommand(CLIContext) method.

    • getUsage

      protected String getUsage()
      Describe the intended usage for the command.

      This will be included in the 'Usage: ...' error message when the CLI is misused.

    • getHelpFooter

      @Nullable protected String getHelpFooter()
      Include a detailed help footer in the --help menu.
      See Also:

    • addThreadsOption

      protected final void addThreadsOption(org.apache.commons.cli.Options options)
      Add the -threads option.

      This is used to configure the internal batch processing thread pool which can be used with getBatchTaskExecutor().

      You may also use getNumThreads() to retrieve the number of threads to use.

    • addBatchOption

      protected final void addBatchOption(org.apache.commons.cli.Options options)
      Add the -batchFormat and -batchOutputFile options.

      These options allow the user to control how and where batch processing results are summarized.

    • setAllowPositionalArguments

      protected final void setAllowPositionalArguments()
      Allow positional arguments to be specified. The default is false and an error will be produced if positional arguments are supplied by the user.

      Those arguments can be retrieved in processOptions(CommandLine) by using CommandLine.getArgList().

    • getNumThreads

      protected final int getNumThreads()

    • buildOptions

      protected void buildOptions(org.apache.commons.cli.Options options)
      Build option implementation.

      Implement this method to add options to your command line, using the OptionBuilder.

      This is called right after buildStandardOptions(Options) so the options will be added after standard options.

    • processOptions

      protected void processOptions(org.apache.commons.cli.CommandLine commandLine) throws org.apache.commons.cli.ParseException
      Process command line options.

      Implement this to provide processing of options. It is called after buildOptions(Options) and right before doWork().

      Throws:
      org.apache.commons.cli.ParseException - in case of unrecoverable failure (i.e. missing option or invalid value), an exception can be raised and will result in an exit code of FAILURE.

    • doWork

      protected abstract void doWork() throws Exception
      Command line implementation.

      This is called after buildOptions(Options) and processOptions(CommandLine). so the implementation can assume that all its arguments have already been initialized and any setup behaviour have been performed.

      Throws:
      Exception - in case of unrecoverable failure, an exception is thrown and will result in a FAILURE exit code, otherwise use addErrorObject(java.io.Serializable, java.lang.String, java.lang.Throwable) to indicate an error and resume processing

    • promptConfirmationOrAbort

      protected final void promptConfirmationOrAbort(String confirmationMessage) throws Exception
      Prompt the user for a confirmation or raise an exception to abort the doWork() method.
      Throws:
      Exception

    • abort

      protected final void abort(String message) throws Exception
      Abort the execution of the CLI with the given message.

      The CLI will exit with the ABORTED exit code as a result.

      Throws:
      Exception

    • addSuccessObject

      protected final void addSuccessObject(Serializable successObject, String message)
      Add a success object to indicate success in a batch processing.
      Parameters:
      successObject - object that was processed
      message - success message

    • addSuccessObject

      protected final void addSuccessObject(Serializable successObject)
      See Also:

    • addWarningObject

      protected final void addWarningObject(@Nullable Serializable warningObject, String message)
      See Also:

    • addWarningObject

      protected final void addWarningObject(@Nullable Serializable warningObject, String message, Throwable throwable)
      Add a warning object with a stacktrace to indicate a recoverable failure in a batch processing.
      Parameters:
      warningObject - that was processed
      message - error message
      throwable - throwable to produce a stacktrace

    • addErrorObject

      protected final void addErrorObject(@Nullable Serializable errorObject, String message, Throwable throwable)
      Add an error object with a stacktrace to indicate failure in a batch processing.

      This is intended to be used when an Exception is caught.

      Parameters:
      errorObject - object that was processed
      message - error message
      throwable - throwable to produce a stacktrace

    • addErrorObject

      protected final void addErrorObject(@Nullable Serializable errorObject, String message)
      Add an error object without a cause stacktrace.
      See Also:

    • addErrorObject

      protected final void addErrorObject(@Nullable Serializable errorObject, Exception exception)
      Add an error object based on an exception.
      See Also:

    • getBatchTaskExecutor

      protected final BatchTaskExecutorService getBatchTaskExecutor()
      Obtain an executor for running batch tasks.

      The CLI will await any pending batch tasks before exiting. You may only submit batch tasks inside doWork().

      Successes and errors are reported automatically if addSuccessObject(Serializable, String) or addErrorObject(Serializable, String) haven't been invoked during the execution of the callable/runnable.

    • getBatchTaskProgressReporter

      protected final BatchTaskProgressReporter getBatchTaskProgressReporter()

    • setReportFrequencyMillis

      protected final void setReportFrequencyMillis(int reportFrequencyMillis)
      Set the frequency at which the batch task executor should report progress.

      The default is to report progress every 30 seconds. It may be overwritten by the -batchReportFrequency option.

    • setEstimatedMaxTasks

      protected final void setEstimatedMaxTasks(int estimatedMaxTasks)
      Set the estimated maximum number of batch tasks to be processed.

    • awaitBatchExecutorService

      protected final void awaitBatchExecutorService() throws InterruptedException
      Await the completion of all batch tasks.

      The batch task executor will be shutdown, preventing any new tasks from being submitted.

      Throws:
      InterruptedException