I know we can declare the exception for our method if we want it to be handled by the calling method. This will even allow us to do stuff like write to the OutputStream without wrapping the code in try/catch block if the enclosing method throws IOException.
My question is: Can anyone provide an instance where this is usually done where you'd like the calling method to handle the exception instead of the current method?
Edit: I meant calling method instead of super class in the last line.
In web frameworks (like spring) you often let errors propagate and container will deal with them (by showing error page or message to the user, rolling back transaction, etc).
Also, there are lots of java errors you never catch, like OutOfMemoryError. You can catch them, but you can't deal with them properly.
I guess by "super class" you mean the code that called your method.
If you expect the caller to know more about the problem compared to your method, than you can pass this responsibility up the calling stack.
In general, if you do not know how to handle the problem, don't. Ether pass it or wrap it in another exception.
If you can't handle the error at the point in a sensible way (e.g. displaying error message, taking an alternative path, etcetera), then just let it bubble up.
If you want the error to be handled at a different level of the application.
Here's a semi-concrete example. Let's say I've got a web application which is implemented as a series of states and actions. Suppose that, while a state is being processed, a database access causes an SQLException to be thrown. This would not happen during the normal operation of my application; it would only happen if there were something wrong with the database.
The method that access the database doesn't need to know what my procedure for handling semi-fatal errors like this is. That logic implemented at a higher level — in the method that processes the state — and it's essentially the same for any runtime error, whether it's literally a RuntimeException or not: spit out a nice-looking error message to the user telling them to contact tech support.
Imagine if I had to add a try/catch block performing this logic to every method that accessed the database and could possibly throw an SQLException. That's what's called a nightmare.
In general, I would say design your exception flow so that the exception is caught by the code that can actually take appropriate action.
This usually means that in a "library" method (or, some kind of general utility method in a large project), you will be throwing exceptions not catching them.
On the other hand, if you have a situation where you find yourself declaring your method to throw an exception that you believe in practice will hardly ever occur (e.g. serialisation generally involves all sorts of spurious checked exceptions which in practice won't occur, e.g. if you're deserialising an Integer, it's really unlikely that the Integer class is not present, but you still have to catch the appropriate exception), then you have a third option of re-casting to a RuntimeException.
You asked for an example, and here is a common one.
If you are writing code to read a particular file format, these normally declare IOException. The reason for this is that it might be used by a desktop app (which wants to put up a dialog box) or a text utility (which wants to write an error message) or a web app (which wants to return an error code). Exception handling allows you to do that.
I have used expections to as part of transferring information between architectural layers of application.
For Example:
if the DAO (Database Access Layer) gets a SQLException it throws a customized DAOLayerException which is caught by the businesslayer which intrun throws an exception which is caught by the presentation layer.
This was for unchecked exceptions.
I usually follow the practice of throwing checked exceptions (not handling them) if the function is to be used by numerous caller or are unknown at the time of development of the function.