ExceptionVariance

From APIDesign

Revision as of 17:35, 14 July 2016

This essay is most useful when dealing with Checked exceptions as known from Java, however even in systems without compile time exception checking it may be useful. The same principle of Covariance/Contravariance of Exceptions applies in any language.

When creating both sides of an API - e.g. its ClientAPI facade as well as its ProviderAPI part, it is interesting to note that the way one deals with exceptions is (or at least should be) different.

The biggest drawback of Checked exceptions in Java is when they force callers to catch them and there is no reasonable recovery. How we can prevent that? Well, the easiest thing is to not throw any checked exceptions to the client. Then the clients don't need to care about the exceptions at compile time. Btw. I have to mention that I believe there are situations when clients should care about exceptions and then use the checked exceptions seems OK. But, if we want to take things to the extreme and if we want to make life of our [[clueless] API users absolutely exception-checkless: the less of compile time checked exceptions we throw - the easier for them during compilation.

However if we are creating a ProviderAPI - e.g. some interface others have to implement - the situation is quite different. We may ask them sum two numbers, but who knows what they need to do to compute that!? Maybe then need to read some files (and that in Java automatically yields IOException checked exception) or connect to network (also requires users to deal with their checked exceptions). If we don't allow them to propagate the exceptions, what can they do? They have to catch them, recover from them or re-throw them. That is often correct, but certainly not clueless. What can we do to increase cluelessness of people who implement methods in a ProviderAPI that we created? Yes, we should declare that these methods can throw any Exception.

This is just another example of APIvsSPI difference!