Closing JAX RS Client/Response

Question

It's not clear must I close JAX RS Client/Response instances or not. And if I must, always or not?

According to documentation about the Client class:

Calling this method effectively invalidates all resource targets produced by the client instance.

The WebTarget class does not have any invalidate()/close() method, but the Response class does. According to documentation:

Close the underlying message entity input stream (if available and open) as well as releases any other resources associated with the response (e.g. buffered message entity data).

... The close() method should be invoked on all instances that contain an un-consumed entity input stream to ensure the resources associated with the instance are properly cleaned-up and prevent potential memory leaks. This is typical for client-side scenarios where application layer code processes only the response headers and ignores the response entity.

The last paragraph is not clear to me. What does "un-consumed entity input stream" mean? If I get an InputSteam or a String from response, should I close the response explicitly?

We can get a response result without getting access to Response instance:

Client client = ...;
WebTarget webTarget = ...;
Invocation.Builder builder = webTarget.request(MediaType.APPLICATION_JSON_TYPE);
Invocation invocation = builder.buildGet();
InputStream reso = invocation.invoke(InputStream.class);

I'm working with RESTeasy implementation, and I expected that response will be closed inside of resteasy implementation, but I could not find it. Could anyone tell me why? I know that the Response class will implement Closeable interface But even know, the Response is used, without closing it.

Answer 1

According to the documentation close() is idempotent.

This operation is idempotent, i.e. it can be invoked multiple times with the same effect which also means that calling the close() method on an already closed message instance is legal and has no further effect.

So you can safely close the InputStream yourself and should.

That being said I style wise would not do invocation.invoke(InputStream.class) as the invoker(Class) is made for doing entity transformation. Instead if you want InputStream you should probably just call invocation.invoke() and deal with the Response object directly as you may want some header info before reading the stream. The reason you want headers when dealing with a response InputStream is typical because you either don't care about the body or the body requires special processing and size considerations which is what the documentation is alluding to (e.g. HEAD request to ping server).

See also link

A message instance returned from this method will be cached for subsequent retrievals via getEntity(). Unless the supplied entity type is an input stream, this method automatically closes the an unconsumed original response entity data stream if open. In case the entity data has been buffered, the buffer will be reset prior consuming the buffered data to enable subsequent invocations of readEntity(...) methods on this response.

So if you choose anything other than InputStream you will not have to close the Response (but regardless its safe to do it anyways as its idempotent).

Answer 2

Looking into the resteasy-client source code, Invocation#invoke(Class<T>) is simply calling Invocation#invoke() and calling Invocation#extractResult(GenericType<T> responseType, Response response, Annotation[] annotations) to extract the result from the Response:

@Override
public <T> T invoke(Class<T> responseType)
{
   Response response = invoke();
   if (Response.class.equals(responseType)) return (T)response;
   return extractResult(new GenericType<T>(responseType), response, null);
}

Invocation#extractResult(GenericType<T> responseType, Response response, Annotation[] annotations) closes the Response in the finally block:

/**
 * Extracts result from response throwing an appropriate exception if not a successful response.
 *
 * @param responseType
 * @param response
 * @param annotations
 * @param <T>
 * @return
 */
public static <T> T extractResult(GenericType<T> responseType, Response response, Annotation[] annotations)
{
   int status = response.getStatus();
   if (status >= 200 && status < 300)
   {
      try
      {
         if (response.getMediaType() == null)
         {
            return null;
         }
         else
         {
            T rtn = response.readEntity(responseType, annotations);
            if (InputStream.class.isInstance(rtn)
                 || Reader.class.isInstance(rtn))
            {
               if (response instanceof ClientResponse)
               {
                  ClientResponse clientResponse = (ClientResponse)response;
                  clientResponse.noReleaseConnection();
               }
            }
            return rtn;

         }
      }
      catch (WebApplicationException wae)
      {
         try
         {
            response.close();
         }
         catch (Exception e)
         {

         }
         throw wae;
      }
      catch (Throwable throwable)
      {
         try
         {
            response.close();
         }
         catch (Exception e)
         {

         }
         throw new ResponseProcessingException(response, throwable);
      }
      finally
      {
         if (response.getMediaType() == null) response.close();
      }
   }
   try
   {
      // Buffer the entity for any exception thrown as the response may have any entity the user wants
      // We don't want to leave the connection open though.
      String s = String.class.cast(response.getHeaders().getFirst("resteasy.buffer.exception.entity"));
      if (s == null || Boolean.parseBoolean(s))
      {
         response.bufferEntity();
      }
      else
      {
         // close connection
         if (response instanceof ClientResponse)
         {
            try
            {
               ClientResponse.class.cast(response).releaseConnection();
            }
            catch (IOException e)
            {
               // Ignore
            }
         }
      }
      if (status >= 300 && status < 400) throw new RedirectionException(response);

      return handleErrorStatus(response);
   }
   finally
   {
      // close if no content
      if (response.getMediaType() == null) response.close();
   }

}