Welcome Jira Service Desk 4.0 EAP milestone 01

jsd
api
jira-server

#1

We’re proud to present the first EAP milestone (m01) for Jira Service Desk 4.0.

Jira Service Desk 4.0 will contain some breaking changes, most coming from the Jira platform and a few specific to Jira Service Desk.

You can track all the changes and monitor EAP milestones from the Preparing for Jira 8.0 page.

Here are important things to be aware of:

End of support for com.atlassian.fugue
Already deprecated in Jira Service Desk 3.15, we’ll be permanently removing com.atlassian.fugue in 4.0 and updating our APIs to use Core Java Data types and Exceptions instead.

To download this EAP milestone, go here.

And if you have any comments or questions, don’t hesitate in posting them here and we’ll take a look.

Regards,
Lachlan Goodhew-Cook
Senior Developer, Jira Service Desk Team


#2

Hi Lachlan,

Thanks for making this available. So I’m just having a go at making Automation for Jira compatible with ServiceDesk 4.0 and there’s a few issues.

The first is using Exceptions for control flow such as validation errors seems like a pretty bad API choice to me. So previously a lot of the services would return Eithers with errors or the successful result. Now I get that you’re deprecating fugue, but switching to exceptions for validation errors seems not an ideal API choice. Even worse, the exceptions aren’t even mentioned on the interfaces as being thrown so as a third party developer I don’t really know what I’m supposed to be catching. Would be interesting to hear your thoughts on why you decided to implement the new APIs using Exceptions for standard validation errors. In my opinion (and I thought the general opinion of Java developers out there) was that this was bad practice. It leads to messy code for clients (shitloads of try/catch blocks), and unforeseen errors if someone forgets to add a try/catch block.

After some debugging I figured out that I’m meant to be catching ServiceDeskServiceException or sub-classes thereof. However when I tried to implement this, I found that the 4.0.0 EAP does not export the ‘com.atlassian.servicedesk’ package that these exceptions are in to OSGi, so when I try to catch an exception like this right now in my add-on I get a ‘ClassNotFoundException’. Is that just an oversight in this EAP?

Right now I’ll have to catch RuntimeExceptions and then check with reflection that it’s a ServiceDeskServiceException to get to the actual error message (with reflection again).

Cheers,
Andreas


#3

Hi @andreas,

Firstly, thanks for taking the time to try out our EAP and provide this feedback. It’s invaluable. Hopefully my response below will answer the questions and concerns you’ve raised.

Why we’re implementing new APIs using Exceptions for standard validation errors

I’m curious about your experience with Fugue and how it would differ from using exceptions. Inside Jira Service Desk, we often returned the Left as soon as we had it (internally we use pocketknife.steps to avoid many if (x.isLeft) {} checks) which would cascade back up the callstack until something handled the Left. Not dissimilar to how an Unchecked Exception would work. You throw the Exception where it happens (for example, entity not found in the database) then the calling code doesn’t know how to deal with it, except to maybe clean up the error message until it reaches the API layer, where it’s returned to the caller as a RestResponse.
The decision to add Exceptions in place of Eithers was certainly deliberated. We knew it would be painful to consume, but we wanted to offset that pain by reducing the differences across Atlassian products, to get closer to reaching a standard. Jira, Confluence, and Bitbucket Server APIs all use Exceptions. Jira uses Checked Exceptions and everything else is Unchecked.

The exceptions aren’t mentioned on the interfaces

That’s a fair point. Jira Service Desk decided to go with Unchecked Exceptions to reduce the number of catch blocks that re-threw Exceptions (or throw declarations that reflected a function further down). We’ve taken a similar approach to Bitbucket Server by declaring what could be thrown in the @throws section on the javadoc, and where more specific errors apply they’ll be called out too.
I’m looking into getting the documentation released soon.

The 4.0.0 EAP does not export the com.atlassian.servicedesk package - Is that an oversight in this EAP?

It is an oversight Andreas. We put the exceptions in the com.atlassian.servicedesk.* package which wasn’t exported correctly. I’ve fixed this, but I just missed getting it in the most recent EAP release (EAP 3) but in an upcoming EAP release (Jira Service Desk EAP 4) they’ll be moved to com.atlassian.servicedesk.api.* which should be exported along with everything else.

Thank you for your time.
Lachlan Goodhew-Cook,
Jira Service Desk Server Team


#4

Hey @andreas,

We’ve fixed the docs and released them here:

See PortalService#getPortalForProject for an example of where more specific Exceptions are documented.

You can rely on catching a ServiceDeskServiceException for any time you would have previously handled AnError. We don’t explicitly call out AuthorizationException or ForbiddenException on every API but they can be assumed to be thrown on almost all endpoints.

Lachlan Goodhew-Cook,
Jira Service Desk Server Team


#6

Hi Lachlan,

Sorry - ignore my previous reply. Didn’t immediately see your previous comment.

Great thanks for those clarifications and that the exceptions will be exported to OSGi soon.

Re your comments about Exceptions vs Either: In my opinion and from my experience working on Jira core (where most services do return errors via return objects and don’t throw exceptions), it’s better to have the service layer in the app use proper return objects to indicate errors rather than exceptions. It simply is better from an API self-documenting point of view for developers using APIs, and leads to less unexpected errors at runtime. In any case - sounds like that ship has sailed - we can deal with it in our wrapper layer for Atlassian APIs that we already need anyways for various other reasons (API compatibility, cloud vs server agnostic APIs for other components in our system etc)

Having the exceptions in javadoc is nice, however as a third party dev I can’t just download sources via maven unfortunately so I don’t really get access to those in my IDEA easily (unless I want to jump through several hoops).

Cheers,
Andreas


#7

I agree wholeheartedly with Andreas. Return objects are preferable to exceptions for service APIs. I think this will lead to many vendors writing wrapper layers to convert exceptions to return objects. As much as I hate checked exceptions, I feel that it would be a better choice than unchecked here to make the API more discoverable. Having to rely on javadoc to detect changes in behaviour isn’t fit for purpose. For example, if an api call added a new exception type in a future version existing code would compile fine, but we would not know the code actually didn’t handle a particular case.

If access to the JSD source was as simple as that of Jira (or other Atlassian applications) then the javadoc would be more useful. As it is it is very frustrating to work with online Javadoc.

Jon