Sets the timeout (in milliseconds) for this AsyncContext.
The timeout applies to this AsyncContext once the container-initiated dispatch during which one of the ServletRequest#startAsync methods was called has returned to the container.
The timeout will expire if neither the complete() method nor any of the dispatch methods are called. A timeout value of zero or less indicates no timeout.
If setTimeout(long) is not called, then the container's default timeout, which is available via a call to getTimeout(), will apply.
timeout - the timeout in milliseconds
IllegalStateException - if this method is called after the container-initiated dispatch, during which one of the ServletRequest#startAsync methods was called, has returned to the container
im unable to understand what does container-initiated dispatch means ?
About your second question:
void setTimeout(long timeout)
can throw (un-checked) IllegalStateException, when someone is setting a timeout on a AsyncContext object, which already FINISHED its work.
Have a look here:
last line of code should throw an exception
OK, I must admit, my code sample is very primitive, but I'm too lazy to write now multi-class example with async requests running in separate threads
And exactly under such conditions (multi-threaded servlet processing) you have not so bad chance to try working with object, which already finished its work (life-cycle).
I hope, you get the idea: once AsyncContext is recycled you cant use it anymore.
BTW, this is true not only about setTimeout(), but also for nearly all other methods in AsyncContext interface.
And one more hint: just look into the source code of some open-source implementation. I've just done that with "tomcat 7.0"