java api design - NULL or Exception

Question

Is it better to return a null value or throw an exception from an API method?

Returning a null requires ugly null checks all over, and cause a major quality problem if the return is not checked.

Throwing an exception forces the user to code for the faulty condition, but since Java exceptions bubble up and force the caller code to handle them, in general, using custom exceptions may be a bad idea (specifically in java).

Any sound and practical advice?

Answer 1

Josh Bloch recommends returning empty objects or "unit" objects in place of null values. Check out Effective Java for a ton of useful Java tidbits.

Answer 2

I think the answer is entirely dependent on the context of your application, and what you consider to be an "exceptional circumstance" versus programmer error.

For example, if writing an XML parser you may choose to implement methods like:

/**
 * Returns first child element with matching element name or else
 * throws an exception.  Will never return null.
 */
Element getMandatoryChildElement(Element parent, String elementName)
throws MissingElementException;

... as this approach allows you to implement your message parsing code in a single block of logic, without having to check that the message is well-formed after retrieving each element or attribute.

Answer 3

If null is an acceptable return value (ie, it can result from valid inputs rather than an error case) then return null; otherwise throw an exception.

I don't at all understand your statement that a checked exception may be a bad idea because the caller is forced to handle them - this is the whole point of checked exceptions. It guards against error conditions propagating into the code without being handled properly.