[MNG-7351] clarify differences between MojoFailureException and MojoExecutionException in javadoc

[kwin]

Following this checklist to help us incorporate your contribution quickly and easily:

• [x] Make sure there is a JIRA issue filed for the change (usually before you start working on it). Trivial changes like typos do not require a JIRA issue. Your pull request should address just this issue, without pulling in other changes.
• [x] Each commit in the pull request should have a meaningful subject line and body.
• [x] Format the pull request title like [MNG-XXX] - Fixes bug in ApproximateQuantiles, where you replace MNG-XXX with the appropriate JIRA issue. Best practice is to use the JIRA issue title in the pull request title and in the first line of the commit message.
• [ ] Write a pull request description that is detailed enough to understand what the pull request does, how, and why.
• [x] Run mvn clean verify to make sure basic checks pass. A more thorough check will be performed on your pull request automatically.
• [ ] You have run the Core IT successfully.

If your pull request is about ~20 lines of code you don't need to sign an Individual Contributor License Agreement if you are unsure please ask on the developers list.

To make clear that you license your contribution under the Apache License Version 2.0, January 2004 you have to acknowledge this by using the following check-box.

• [x] I hereby declare this contribution to be licenced under the Apache License Version 2.0, January 2004

• [ ] In any other case, please file an Apache Individual Contributor License Agreement.

[gnodet]

@kwin I think it would be interesting to add pointers to the code where those exceptions are actually handled ? I must admit I tried to find them but I haven't been able to find them in a timely manner. For example there's no BUILD ERROR string in the whole codebase...

[kwin]

@gnodet Indeed I couldn't find anything either yet. TBH I have just taken the information from https://books.sonatype.com/mvnref-book/reference/writing-plugins-sect-custom-plugin.html#writing-plugins-sect-failure which I consider a pretty reliable source. But maybe the different handling of those exceptions has vanished over time. Will do some more tests....

[kwin]

I tried it out with a dummy mojo and both exceptions behave exactly the same, i.e. both emit "BUILD FAILURE". I couldn't influence the build outcome with any of the --fail-xxx options nor continue the build after the exception happened. I had a quick look in the commit logs and found (https://github.com/apache/maven/commit/06dc81b54e48b76ce25675f2ae52e39ac8aeb396#diff-976d393f31905911c189adc496696a5047b0aae4526ba1c5d13bf7502ce2cbca) which once treated MojoExecutionException separately, but that class has been removed in https://github.com/apache/maven/commit/ae1501b9f67db880ea7f16299f95f00ce04728ff (with Maven 3), so most probably having two different exception classes is no longer useful in Maven 3...

[kwin]

Given that, I would recommend to either reestablish the different semantics or deprecate one exception class of the two. In any case right now it is highly confusing why there are two different exception classes and when to use which in mojos.

[kwin]

Dug a bit deeper and found https://github.com/apache/maven/blob/ed370a6382ee4e431d36ae38454174b94d4f33aa/maven-core/src/main/java/org/apache/maven/DefaultMaven.java#L235-L255 for the different handling.

[gnodet]

Dug a bit deeper and found

https://github.com/apache/maven/blob/ed370a6382ee4e431d36ae38454174b94d4f33aa/maven-core/src/main/java/org/apache/maven/DefaultMaven.java#L235-L255

for the different handling.

Now, the exceptions are handled in BuilderCommon and no case is done whether the exception is a MojoFailureException or MojoExecutionException which is coherent with your experiments. If we confirm this, I'd change the javadoc and eventually deprecate one of the exceptions.

[rmannibucau]

My understanding was that MojoExecutionException is a wrapper around another exception as primary usage whereas MojoFailureException is a root exception by itself (and previous handling tends to confirm it).

Overall the need of these exception is that mojo don't throw an Exception/Throwable but there is no technical reason - in particular now, so ultimately we can just deprecate both and change mojo contract for 4.0, no?

[kwin]

Overall the need of these exception is that mojo don't throw an Exception/Throwable but there is no technical reason

I think the reason is to throw an exception which would allow Maven to continue (by using --fail-never or --fail-at-end, https://maven.apache.org/ref/3.8.4/maven-embedder/cli.html). Using an unchecked exception will IMHO always lead to an immediate failure and broken Maven build.

[rmannibucau]

@kwin not sure, --fail-never will ignore the exception and --fail-at-end will stack it to fail after other modules build so MojoXXXExceptons never bring anything in this logic (as proven by BuilderCommon impl) so think it is fine to remove this constraint. There is no real recovery exception in maven - and don't think we need one.