Clarify javax.ws.rs.core.Response javadoc wrt extracting entities.

A number of javax.ws.rs.core.Response methods, e.g., getEntity() and hasEntity(), include a line in the javadoc like

* @throws IllegalStateException in case the response has been {@link #close() closed}.

However, in the absence of a method like isClosed(), we end up writing code like

try {
   if (response.getEntity() != null) return response;
}
catch(IllegalStateException ise) {
   // IllegalStateException from ClientResponse.getEntity() means the response is closed and got no entity
}

instead of

if (!response.isClosed() && response.getEntity() != null) {
   return response;
}

The implementation of isClosed() should be simple, and it leads to nicer code.

An example of a potential use of Response.isClosed() arises in RESTEasy when:

1. A resource method uses a Client to contact another server and gets an exception back.

2. A builtin ExceptionMapper tries to unwrap the Exception:

   protected Response unwrapException(HttpRequest request, Throwable e, RESTEasyTracingLogger logger)
   {
      Response jaxrsResponse = null;
      Throwable unwrappedException = e.getCause();

      /*
       *                If the response property of the exception does not
       *                contain an entity and an exception mapping provider
       *                (see section 4.4) is available for
       *                WebApplicationException an implementation MUST use the
       *                provider to create a new Response instance, otherwise
       *                the response property is used directly.
       */

      if (unwrappedException instanceof WebApplicationException) {
         WebApplicationException wae = (WebApplicationException) unwrappedException;
         Response response = wae.getResponse();
         if (response != null) {
            try { // Here's where we guard against IllegalStateExceptioin
               if (response.getEntity() != null) return response;
            }
            catch(IllegalStateException ise) {
               // IllegalStateException from ClientResponse.getEntity() means the response is closed and got no entity
            }
         }
      }

        ...

Before we wrapped the call to Response.getEntity() in try/catch, we were getting an IllegalStateException, which isn't very helpful.