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

Refactor and unify issue handling in CLI commands

    Details

    • Type: Improvement
    • Status: Resolved
    • Priority: Major
    • Resolution: Fixed
    • Component/s: cli, core
    • Labels:
      None
    • Similar Issues:

      Description

      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

        Attachments

          Issue Links

            Activity

              People

              • Assignee:
                pajasoft Pavel Janoušek
                Reporter:
                pajasoft Pavel Janoušek
              • Votes:
                0 Vote for this issue
                Watchers:
                9 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved: