Custom exceptions or empty list

Question

I am working on a project to parse the text. I am parsing for specific text and store them in the array. I have written a class for it. If I get improper text so that I cannot find what I want in the given input, What is the best practice, should I return the empty array and let the calling class handle it or should I raise a custom exception to the calling class.

Answer 1

If I were using your class as a library and received an empty array as a return value, I would assume -- barring documentation otherwise -- nothing had been read (and be very confused if my input had text to read!)

Similarly, I would hope that when and if a piece of library code threw an exception, it would throw something useful so that I could debug the problem. That might come in the form of a custom exception, or it might come in the form of an existing library exception; for example, ParseException, which supplies the offset into the text where the exception occurred. However, if there is some other piece of information that's relevant to your particular exceptional case, then a custom Exception subclass may be warranted.

Answer 2

If caller's view of empty-list is error i.e. caller always except some value in list and handling empty list is not usual in his case that's a signal that a custom exception is better.

For example: If caller has a category input and contract is your API will have its product, emptiness is error according to contract.

Now, if there is no use-case of above tight contract between caller and API, it's perfectly valid to send empty list.

For example: Caller asks for a list of XYZ articles and you don't have, an empty article list is fine.

It's purely subjective and use-case driven, Java doesn't provide any specific guidelines on this.

Answer 3

It's hard to have "best practices" since every design case is different. As a rule of thumb, consider what API would be easiest for your consumer to use and would be least surprising. I also highly suggest picking up a copy of Effective Java by Joshua Bloch if you haven't seen it already. Specifically applicable are sections on "Use Exceptions for Exceptional Conditions", and "Favor use of the Built in Exceptions" (and the book contains lots of other good style and correctness suggestions).

Now to your particular case:

Is it expected that your user should provide proper text or improper text as input? If the former, then an Exception is more likely the correct solution. Furthermore, If you returned an empty array, What would the difference be between proper text that happens to be empty, and improper text? Could you tell the difference in your calling code? Does such a distinction matter?

Now what exception to throw? You could throw a subclass of IOException (as you're dealing with input), the (arguably) potential downside is that IOException is not a RuntimeException so anyone calling your code would be forced to either handle the exception or rethrow it. (Checked versus Unchecked exceptions is another debate).

Answer 4

It depends on what you are doing. If improper text is a common and expected thing, simply ignoring it and returning an empty array (or null) may be completely reasonable. But if improper text should never happen and calls into question the validity of previously or subsequently processed input (that may already have been added to the array) you should probably throw an exception.