throwing an exception or returning Optional

Question

In a service daemon coded in Java, we have services for getting various objects. When we use these services forgetting an object, I wonder if

• the method should return the object and throw an exception when It's not found
• or return an Optional (this is what we opted for, so far)

Mind you , this service is not for a web service, so I have no use for a Global Exception Handler or such

class MyService
    public A getA(String key){
        ...
        // if A not found
        throw NotFoundException()
    }

vs

class MyService
    public Optional<A> getA(String key){
        ...
        // if A not found
        return Optional.empty()
    }

Answer 1

There are two primary use cases for exceptions, which partially overlap:

1. You detect a problem that is unrelated to why this function might be called. It is unlikely that the calling code knows any better how to deal with this problem. Examples are out-of-memory conditions, or network errors where the calling code isn't aware that network communication is being used, etc. In these cases, exceptions can be used to perform a multi-level jump up the call-stack to a function that might be able to deal with the problem.

2. You detect a "this should not happen" problem, which is indicative of a bug in the system. Here, exceptions are used to halt the faulty calculations in their tracks. An example could be a retrieval function (getA), where it is known that the function can/should only be called with the id of an existing object.

For your example, both throwing an exception and returning an Optional are valid, but if it can somehow be expected that an ID gets passed in that doesn't correspond to an object, then the usual preference is to return an Optional.

Answer 2

IMHO, throwing an exception always exactly means "I could not fulfill my contract".

As an API developer, your steps should be:

• Design the contract (with usefulness for your callers in mind).
• Choose a method name that clearly indicates the contract.
• Implement that method.

Designing the contract

Your contract is something around "find me an A for the given key", but that needs clarification, with the following two candidates:

• "Get me an A with the given key." This version has no clause for not finding an A, so this contract can not be fulfilled then, meaning that an exception has to be thrown.
• "Try to get me an A with the given key." This allows for not finding an A, so this outcome should be indicated in the return value, e.g. using an Optional<A>.

Contracts have to be designed with the typical callers in mind.

Analogy: Same as in business. You strive to offer products that meet your customers' needs. Knowing your customers helps, but it's not necessary to know every single customer's mindset in detail.

So, it helps to have some understanding of your callers, but it's not your responsibility to figure out the impact of not finding an A in each and every call stack that arrives at your API.

Back to your method's expected callers:

• Do they expect the matching A to exist? Then the exception is preferrable, as it makes it easy for them to concentrate on the happy path.
• Do you expect callers that will deal with the non-existence in their normal control flow? Then the Optional-based contract is better.
• If you expect callers of both types, let them choose by offering both versions in different methods.

Naming the method

A name like getA() might imply (e.g. to me) that not returning an A is a violation of contract, but there are too many counter-examples out there to rely on that. Better be explicit in your naming, by using names like getAOrThrow() or TryGetA().

Implementing the method

Once the contract is clear, you can start coding. And if you chose to have both versions, you'd typically implement the exception-throwing one as a small wrapper around the Optional-based one.

Answer 3

throwing an exception or returning Optional

Exception and Optional offer different information. Using one or the other depends on whether what has to be done can be done or not with the information each of the two offers.

Use Optional when existence/non-existence of information suffices to go through the program flow. Example: Presume there is an object requiring type information. Using Optional it can be decided that objects missing type information has to be processed differently than objects including the type information.

Use Exception for a fine grained control of the program flow. Example: Presume there is an object requiring type information and type information must transition according to a state diagram. Use Exception to steer the transition between supported values.

Answer 4

The rule is that you throw exceptions in exceptional circumstances. For example, if the user enters a part number and you look up information about that part and return it, then it is normal that the user enters a wrong part code and nothing is found, no exception.

If every employee has a GUID and you can lookup further information about the employee by GUID then that GUID should always be correct. Throw an exception if the GUID doesn’t exist; there is very likely a bug to be fixed. On the other hand, if you don’t get the information because the internet connection is down, that is not an exception.