Make FailureResolutionAware usable for users & plugin developers


(Andreas Schilling) #1

Hi everyone!

While developing some additional side-tooling (in form of Gradle tasks) for one of our builds I was thinking it would be cool to be able to supply information to the Try part of the failure reporting that is shown upon build failure. I then noticed that for internal consumers this is possible, but I wasn’t able to supply information myself by throwing an exception that implements FailureResolutionAware.

See also my stackoverflow discussion here

Wouldn’t it be a cool thing to expose this functionality to anyone or even promote it as a best practice? It’s a detail, I know, but I totally dig that sort of user guidance as I think it massively encourages developers to supply better failure information (Spring Boot sports the same concept with its FailureAnalyzers).

Would be great to get some insight on the topic from Gradle contributors!

Cheers,

Andreas


(Benjamin Muschko) #2

The class FailureResolutionAware is an internal API and not meant for external consumption. What exactly would be the benefit for exposing the interfacing to as public API? It’s really only an interface. Can you elaborate on the use case you are trying to solve (and potentially also provide a code snippet for how you’d apply it)?


(Stefan Oehme) #3

@bmuschko The benefit would be that community plugins can do the same thing as core plugins: List possible solutions to a problem prominently in the “Try …” part of the console output.


(Andreas Schilling) #4

The main benefit would be consistency in terms of what’s already there and is used by Gradle itself. As said, of course I can provide the same level of detail by just putting all information about the failure into the exception message, but when I see that Gradle already provides a nice presentation in the Where, What went wrong and Try manner I feel the urge to adhere to that :slight_smile:

The background is that I often supply additional tasks within a build that are not strictly for the build itself but help developers to perform certain (repetitive) tasks like preprocessing things, scaffolding or pre-validating something. Especially in cases where the error is more a semantic rather than a syntactic thing (or just a missing file/parameter) supplying something to the Try part of the error message would be nice.

The same holds (even more?) true when developing plugins.

Let me create some kinda artificial example: a task is provided that generates database access code from a Java file. Obviously this will just make sense for classes that are actually stored in a database. If the task expects the source Java file to be in a specific form (contains special annotations, implements special interfaces, etc.) the task might simply fail at some point because this expectation is not met. If I now as a developer of the tooling know that the user tried to apply the task to a file that misses a needed interface for the task to actually work, I of course can just let the process fail and write Class XYZ does not implement TheAwesomeInterface. As I probably know exactly why the process failed and possibly even can describe which file, which row and what part of the input made it fail, I can also supply something like Add TheAwesomeInterface to XYZ.Java, Line 27 or remove the file from the preprocessing step.

Now, nothing holds me back from doing that exact same thing with the current possibilities: Supply it to the exception message, preferably with some nice formatting. Still it would be great to at least optionally be able to supply an exception with FailureResolutionAware for the following reasons:

  1. When I spot the BUILD FAILED message I start to look up and first hit the Try block that tells me to either print the stacktrace or run a more verbose build. I know it’s my sloppy self to often stop here, but I guess I’m not the only one :slight_smile: If it would directly tell me what the problem was I’m less in danger to miss some valuable information supplied in the What went wrong part
  2. Consistency. Guidance to a solution does strictly speaking not belong to the What went wrong part. I’m nitpicking here, but so many things in software development are about the small details :slight_smile:
  3. As far as I saw I can use nice formatting for the messages coming out of a FailureResolutionAware. Again, a detail, but it’s nice.
  4. Possibly, the BuildExceptionReporter can detect whether an exception sports the additional information and then even supply a more prominent formatting of the console output to the user (borders, colors, indentation, …)
  5. At least I for myself feel very motivated to provide good information to the user if it is easy to do so. If I see some nice output or functionality I’m often like “Woah, that’s cool. How can I do that myself?”

Hope that clarifies it a bit :slight_smile:


(Benjamin Muschko) #5

Oh, I see. I thought this was just about making that interface public. It’s actually about exposing a mechanism for allowing plugins to propose potential solutions for error cases. That sounds reasonable and useful.

@andreas-schilling Would you mind opening an issue on gradle/gradle?


(Andreas Schilling) #6

Will do either this evening or tomorrow!


(Andreas Schilling) #7

Done: https://github.com/gradle/gradle/issues/1558