About IOException, there was a comment here in HDFS-8562 I forgot to address:
SocketTimeoutException is timeouts, other IOExceptions could be other things. Maybe have two lines about exceptions, one for IOE and another for timeout?
SocketTimeoutException is also an IOException. Having the both in the throw list would not look clean. Not adding SocketTimeoutException explicitly doesn't prevent callers from handling it specially. If we'd like to add SocketTimeoutException in the accept() method throw list, we might need to do it as well for other methods. More suggestions are welcome.