org.glassfish.jersey.server.spi

## Interface ContainerResponseWriter

    public interface ContainerResponseWriter

A suspendable, request-scoped I/O container response writer. I/O container sends a new instance of the response writer with every request as part of the call to the Jersey application `ApplicationHandler.apply(org.glassfish.jersey.server.ContainerRequest)` apply(...)} method. Each container response writer represents an open connection to the client (waiting for a response).

For each request the Jersey runtime will make sure to directly call either `suspend(...)` or `commit()` method on a response writer supplied to the `JerseyApplication.apply(...)` method before the method has finished. Therefore the I/O container implementations may assume that when the `JerseyApplication.apply(...)` method is finished, the container response writer is either `commited`, or `suspended`.

Author:
  Marek Potociar

### Nested Class Summary

Nested Classes
`static interface` `ContainerResponseWriter.TimeoutHandler` Time-out handler can be registered when the container response writer gets suspended.

### Method Summary

All Methods Instance Methods Abstract Methods
`void` `commit()` Commit the response & close the container response writer.
`boolean` `enableResponseBuffering()` Return `true` if the entity buffering should be enabled in Jersey.
`void` `failure(Throwable error)` Propagate an unhandled error to the I/O container.
`void` `setSuspendTimeout(long timeOut, TimeUnit timeUnit)` Set the suspend timeout.
`boolean` `suspend(long timeOut, TimeUnit timeUnit, ContainerResponseWriter.TimeoutHandler timeoutHandler)` Suspend the request/response processing.
`OutputStream` `writeResponseStatusAndHeaders(long contentLength, ContainerResponse responseContext)` Write the status and headers of the response and return an output stream for the web application to write the entity of the response.

### Method Detail

#### writeResponseStatusAndHeaders

    OutputStream writeResponseStatusAndHeaders(long contentLength,
                                               ContainerResponse responseContext)
                                        throws ContainerException

Write the status and headers of the response and return an output stream for the web application to write the entity of the response.

If the response content length is declared to be greater or equal to 0, it means that the content length in bytes of the entity to be written is known, otherwise -1. I/O containers may use this value to determine whether the `"Content-Length"` header can be set or utilize chunked transfer encoding.

Parameters:
  `contentLength` - greater or equal to 0 if the content length in bytes of the entity to be written is known, otherwise -1. Containers may use this value to determine whether the `"Content-Length"` header can be set or utilize chunked transfer encoding.
  `responseContext` - the JAX-RS response to be written. The status and headers are obtained from the response.
Returns:
  the output stream to write the entity (if any).
Throws:
  `ContainerException` - if an error occurred when writing out the status and headers or obtaining the output stream.

#### suspend

    boolean suspend(long timeOut,
                    TimeUnit timeUnit,
                    ContainerResponseWriter.TimeoutHandler timeoutHandler)

Suspend the request/response processing. The method returns `true` to indicate the response writer was suspended successfully. In case the provider has already been suspended earlier, the method returns `false`.

I/O container must not automatically `commit` the response writer when the processing on the I/O container thread is finished and the thread is released. Instead, the Jersey runtime will make sure to manually close the container response writer instance by explicitly calling the `commit()` or `failure(Throwable)` method at some later point in time.

Once suspended, the specified suspend timeout can be further updated using `setSuspendTimeout(long, java.util.concurrent.TimeUnit)` method.

Parameters:
  `timeOut` - time-out value. Value less or equal to 0, indicates that the processing is suspended indefinitely.
  `timeUnit` - time-out time unit.
  `timeoutHandler` - time-out handler to process a time-out event if it occurs.
Returns:
  `true` if the suspend operation completed successfully, `false` otherwise.
See Also:
  `setSuspendTimeout(long, TimeUnit)`, `commit()`

#### setSuspendTimeout

    void setSuspendTimeout(long timeOut,
                           TimeUnit timeUnit)
                    throws IllegalStateException

Set the suspend timeout. Once the container response writer is suspended, the suspend timeout value can be further updated by the method.

Parameters:
  `timeOut` - time-out value. Value less or equal to 0, indicates that the processing is suspended indefinitely.
  `timeUnit` - time-out time unit.
Throws:
  `IllegalStateException` - in case the response writer has not been suspended yet.

#### commit

    void commit()

Commit the response & close the container response writer. Indicates to the I/O container that request has been fully processed and response has been fully written. This signals the I/O container to finish the request/response processing, clean up any state, flush any streams, release resources etc.

See Also:
  `suspend(long, TimeUnit, TimeoutHandler)`, `failure(Throwable)`

#### failure

    void failure(Throwable error)

Propagate an unhandled error to the I/O container. Indicates to the I/O container that the request processing has finished with an error that could not be processed by the Jersey runtime. The I/O container is expected to process the exception in a container-specific way. This method also signals the I/O container to finish the request/response processing, clean up any state, flush any streams, release resources etc.

Parameters:
  `error` - unhandled request processing error.
See Also:
  `suspend(long, TimeUnit, TimeoutHandler)`, `commit()`

#### enableResponseBuffering

    boolean enableResponseBuffering()

Return `true` if the entity buffering should be enabled in Jersey. If enabled, the outbound entity is buffered by Jersey runtime up to a configured amount of bytes prior to being written to the output stream to determine its size that may be used to set the value of HTTP `"Content-Length"` header.

Containers that provide it's own solution for determining the message payload size may decide to return `false` to prevent Jersey from buffering message entities unnecessarily.

Returns:
  `true` to enable entity buffering to be done by Jersey runtime, `false` otherwise.