Document a pattern that do not return exit code

[ttddyy]

I have been using picocli on the micrometer-docs-generator project and stumbled upon a problem that System.exit halt the maven process when exec-maven-java exec:java goal is used.

This is because exec:java uses the main maven process to invoke the target class and System.exit would simply halt the process that maven runs.

It is natural for a standalone CLI application to use the System.exit, but code invoked by some other application on the same process will have a problem using System.exit.

For my case, I initially tried to make the app a fat executable jar and make it invoked by exec:exec goal which spawns a new process, so it can use System.exit. micrometer-metrics/micrometer-docs-generator#69
At the end, instead of the executable jar, I decided to go with simply throwing an exception AFTER CommandLine#execute is executed based on the returned exit code.

int exitCode = new CommandLine(new DocsGeneratorCommand()).execute(args);
if (exitCode != ExitCode.OK) {
    throw new IllegalStateException("DocsGeneratorCommand failed.");
}

I appreciate this pattern is also documented somewhere.
Since all I see is always using System.exit, it would be a problem for the environment where System.exit causes a negative effect such as exec:java.

[remkop]

Yes very good point! 👍
Will you be able to provide a pull request for the user manual?
(Maybe a new subsection under 21. Tips & Tricks, and we can link to that section from the 9.1. Exit Code subsection?)

Note that the AutoComplete application had this exact same problem and this was solved by using System properties to decide whether to actually call System.exit or not. But that is just one idea. I just mention it because it may be useful to point to a concrete example from the doc.

[ttddyy]

Sure thing, I'll make a PR.

[remkop]

@ttddyy Thank you for your contribution!

I took the liberty to rewrite and add some examples.
The updated documentation is now live in a new section called Rare Use Cases.

Again many thanks!