How to publish exceptions in an API

If I开发者_如何学运维 have a method call that throws two exceptions, but one exception is a super-class of the other, should I throw both exceptions in the method signature, or just the super-class exception? I just wonder how it will look for an exception to be thrown as one instance but published as that instance's super-class.

---

First off, a warning: an API should throw exceptions that make sense to the caller. It's harmful for an API to declare exceptions from things that fail internally. In those cases, it should be wrapped in an exception that communicates the problem to the caller.

That said, I don't have any problem with throwing a super class and its subclass. The caller only has to catch the super class exception, but declaring both in the throws clause documents well which might happen.

E.g. An FTP library's put(File, URL) method might say that a general IOException could happen (to handle cases where the socket connection fails, etc), but also put a FileNotFoundException in the throws clause to communicate that it will be thrown if the file to transfer can't be found.

---

You should let the throws clause include both exceptions. There is no semantical difference but it makes a difference in documentation purposes.

This is how they do it in the standard API. Have a look at FileImageOutputStream for instance. It throws both a FileNotFoundException and an IOException even though the former is a subclass of the latter:

public FileImageOutputStream(File f) throws FileNotFoundException,
                                            IOException

This way the method explicitly documents that it may throw a FileNotFoundException. In the client code it's thus clear that you shouldn't need to bother about EOFException, CharacterCodingException, CharConversionException or any other IOException.

---

Throw both because both can be treated differently in catch block, Also it will create good documentation

---

As a rule of thumb, I would say that it is like checked or unchecked exceptions :

• if the caller can do something with the distinctions of the 2 exceptions then throw both of them, even if they are mother/daughter
• if the caller cannot do anything of the difference, then throw only one
• if the caller cannot do something for repairing (for example retrying a connection, retrying an sql call due to optimistic locking), then throw a Runtime.

---

I read the OP's question not as whether the method should throw both of these related exceptions, but as whether to document them both via the method signature given that they are both thrown.

If one is documented, then the other should be documented for clarity and completeness.

That said, throwing both exceptions when one of them is base of the other raises design suspicions that make me want to see the code to understand why. Situations like this can sometimes occur when the method is using exceptions to indicate some detail about its internal operation rather than as-simply-as-possible indicating that the method could not do what it is designed to do.