The aim of this JIRA is to start unification of an issue handling in CLI commands.
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):
- 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.
|IllegalStateException|| Can't continue due to an incorrect
state of Jenkins instance, job, build etc.
comes from Jenkins.getActiveInstance()
|IllegalArgumentException|| Can't continue due to
wrong input parameter (job doesn't exist etc.)
|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
|AccessDeniedException||Not sufficent rights for requested action||comes from checkPermission()||none||
|BadCredentialsException||Bad credentials provided via the CLI||N/A||N/A||
|Any unknown issue occurred, just to report it for the record||N/A||N/A||