Uploaded image for project: 'Jenkins'
  1. Jenkins
  2. JENKINS-32273

Refactor and unify issue handling in CLI commands

XMLWordPrintable

    • Icon: Improvement Improvement
    • Resolution: Fixed
    • Icon: Major Major
    • cli, core
    • None

      TL;DR;
      The aim of this JIRA is to start unification of an issue handling in CLI commands.

      Details:
      Currently there is a discrepancy between returned error codes if an issue occurred during execution. It depends on the fact whether the CLI command is implemented as @CLIMethod or extending hudson.cli.CLICommand class.

      @CLIMethod usually returns 1 in the case an issue occurred, similar situation in hudson.cli.CLICommand returns -1 to the shell.

      There is an ongoing effort to extract all CLI commands from the Core to CLI (see JENKINS-22969), so the discrepancy should be removed shortly and consistent error code definition should be set-up on one place only - in hudson.cli.CLICommand.

      Currently we should use this semantic in CLI:

      • 0 means All right
      • -1 means An error occurred

      Technically anything else than zero means an issue occurred. Later we can use more precisely defined error codes for the different issues if useful.

      Update 07-Jan-2016 (WIP):

      TODO

      • Refactor core commands to use correct exception classes
      • Update javadoc for CLICommand#run
      • Unify the handling in CLIRegisterer

      Proposed a new unified scheme of exception raising, handling, reporting and error code returning:
      Update 12-Feb-2016: - Exception -> Throwable

      Exception name Meaning Correct usage Incorrect usage Processing Return code
      CmdLineException Wrong parameter,
      input value can't be decoded etc.       		CommandDuringBuild.java
      • catch in CLICommand
      • print "\nERROR: " + cause message to stderr
      • print usage help
      		 2
      IllegalStateException Can't continue due to an incorrect
      state of Jenkins instance, job, build etc.       		CommandDuringBuild.java
      comes from Jenkins.getActiveInstance()       		none
      • catch in CLICommand
      • print "\nERROR: " + cause message to stderr
      		 4
      IllegalArgumentException Can't continue due to
      wrong input parameter (job doesn't exist etc.)       		CopyJobCommand.java
      • catch in CLICommand
      • print "\nERROR: " + cause message to stderr
      		 3
      AbortException Can't continue due to an other (rare) issue
      Note: Current usage of this exception is wrong,
      usually there should be IllegalState or CmdLine exception
      raised instead of this       		none
      • catch in CLICommand
      • print "\nERROR: " + cause message to stderr
      		 5
      AccessDeniedException Not sufficent rights for requested action comes from checkPermission() none
      • catch in CLICommand
      • print "\nERROR: " + cause message to stderr
      		 6
      BadCredentialsException Bad credentials provided via the CLI N/A N/A
      • catch in CLICommand
      • print "\nERROR: " + cause message to stderr with HASH
      • log a cause (HASH included) with INFO level
      		 7
      Exception
      Throwable       		Any unknown issue occurred, just to report it for the record N/A N/A
      • catch in CLICommand
      • print "\nERROR: " + general message to stderr
      • log general message + exception with WARNING level
      • print stacktrace to stderr for further investigation
      		 1

            pajasoft Pavel Janoušek
            pajasoft Pavel Janoušek
            Votes:
            0 Vote for this issue
            Watchers:
            8 Start watching this issue

              Created:
              Updated:
              Resolved: