Support endpoint errors

[mpritham]

Before this PR

Endpoint errors were added to the Conjure specification in this PR. conjure-java does not use user-defined endpoint errors.

After this PR

Generated ServerErrors classes

Developers will be able to create checked exceptions for each error that is defined as an error an endpoint can throw. Specifically, for each endpoint-defined error, conjure-java will generate a class for the error's namespace with name {namespace}ServerErrors. This class will hold the definition of an exception, which is a sub-class of CheckedServiceException (introduced here), as well as methods to construct the exception.

Changes to Errors classes

When an error is used as an endpoint error, factory methods to create ServiceExceptions are no longer provided in the Errors utility classes. 🌶️ This means that once an error becomes associated with an endpoint, it can no longer be used to throw un-checked runtime exceptions. This is intentional and acts as a forcing function for adoption: associating errors with one endpoint will require users to add endpoint errors for all of the endpoints throwing the error.

Updates to Undertow Service Interfaces and Handlers

For each endpoint that defines endpoint-errors, the corresponding endpoint in the Undertow service interface, and the endpoint handler method, will include a throws clause including the list of checked exceptions corresponding to the endpoint errors, that were generated in the ServerErrors class (see above).

Jersey

Endpoint errors will not be supported on Jersey servers. An exception will be thrown if a user attempts to generate code for Jersey services with endpoint errors defined.

==COMMIT_MSG==
Support endpoint errors
==COMMIT_MSG==

Possible downsides?

[changelog-app]

Generate changelog in changelog/@unreleased

What do the change types mean?

• feature: A new feature of the service.
• improvement: An incremental improvement in the functionality or operation of the service.
• fix: Remedies the incorrect behaviour of a component of the service in a backwards-compatible way.
• break: Has the potential to break consumers of this service's API, inclusive of both Palantir services
  and external consumers of the service's API (e.g. customer-written software or integrations).
• deprecation: Advertises the intention to remove service functionality without any change to the
  operation of the service itself.
• manualTask: Requires the possibility of manual intervention (running a script, eyeballing configuration,
  performing database surgery, ...) at the time of upgrade for it to succeed.
• migration: A fully automatic upgrade migration task with no engineer input required.

Note: only one type should be chosen.

How are new versions calculated?

• ❗The break and manual task changelog types will result in a major release!
• 🐛 The fix changelog type will result in a minor release in most cases, and a patch release version for patch branches. This behaviour is configurable in autorelease.
• ✨ All others will result in a minor version release.

Type

• Feature
• Improvement
• Fix
• Break
• Deprecation
• Manual task
• Migration

Description

[wip] Generate checked exceptions for endpoint errors when they are defined

Check the box to generate changelog(s)

• Generate changelog entry

[mpritham]

This is good for a re-review. Shouldn't be merged: it has the CheckedServiceException class which we'd like to be in the conjure-java-runtime-api repo, it uses an RC version of conjure.

Going to branch off of this to work on the error serialization piece.

[mpritham]

Introduced this method which adds the javadoc to the provided methodBuilder. I opted to add an "options" record because there are two dimensions of generation options we need to support: 1) if we should include the request line (e.g. @apiNote {@code GET /foo/bar}), 2) if we should include endpoint errors.

Usage	Request Line?	Endpoint Errors?
Jersey service generation	No	No
Undertow service generation	Yes	Yes
Dialogue interface generation	Yes	No*

*Not yet at least. We can either decide to return a result type in Dialogue, or throw a checked exception. If we do the latter, we need to add @throws pieces to the JavaDoc similar to what we do when generating Undertow service interfaces. If we go with the former, we'll still need to document the result union type but the JavaDoc would be added where we define the results type.

[mpritham]

For Jersey service generation, we shouldn't even get to the logic that adds the JavaDoc. Endpoint errors are not supported for Jersey, and we will throw an IllegalArgumentException if a user attempts to code-gen Jersey services with endpoint errors defined.

[carterkozak]

Agreed, I think we always want to add the error javadoc if errors are present -- we validate that they aren't when the legacy Jersey generator is used

[carterkozak]

Ah right, sorry, missed the piece about dialogue, definitely don't want to leak the server-side piece there!