Document Behavior of MantaClient#close

[tjcelaya]

The current behavior of MantaClient#close is to traverse the danglingStreams collection and close potentially-open stream in addition to shutthing down the connection pool but is not explicit about multi-threaded behavior (it does not provide a JavaDoc). Depending on how users share instances between threads, they may see one of the following exceptions as a result of the client being shut down in a separate thread:

• java.lang.IllegalStateException: Connection pool shut down
• java.io.IOException: Attempted read on closed stream

This leads to two questions:

• How do we signal to other threads that the client is shutting down?
  • Conversely, should the client throw an exception on close() to indicate that there are still pending requests? This might be a reasonable improvement over our current behavior where we block indefinitely until all resources are successfully closed and could be provided as a secondary close method similar to the awaitTermination(long timeout, TimeUnit unit) method of ExecutorService
• Should every method exposed by the client check if the client is closed before proceeding? This seems like overkill since HttpClient will eventually throw IllegalStateException: Connection pool shut down

At the very least, adding a JavaDoc to MantaClient#close about its behavior would be beneficial for users.