org.glassfish.jersey.server.spi
Interface ContainerResponseWriter

public interface ContainerResponseWriter

A suspendable, request-scoped container response writer. Container sends a new instance of the response writer with every request as part of the call to the Jersey application 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(...), cancel() or commit() method on a response writer supplied to the JerseyApplication.apply(...) method before the method has finished. Therefore the container implementations may assume that when the JerseyApplication.apply(...) method is finished, the container response writer is either commited, canceled or suspended.

Author:

Marek Potociar

Nested Class Summary

static interface

ContainerResponseWriter.TimeoutHandler Time-out handler can be registered when the container response writer gets suspended.

Method Summary

void	cancel() Cancel the request/response processing.
void	commit() Commit the response & close the container response writer.
void	setSuspendTimeout(long timeOut, java.util.concurrent.TimeUnit timeUnit) Set the suspend timeout.
void	suspend(long timeOut, java.util.concurrent.TimeUnit timeUnit, ContainerResponseWriter.TimeoutHandler timeoutHandler) Suspend the request/response processing.
java.io.OutputStream	writeResponseStatusAndHeaders(long contentLength, Response response) 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

java.io.OutputStream writeResponseStatusAndHeaders(long contentLength,
                                                   Response response)
                                                   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.

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.

response - 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

void suspend(long timeOut,
             java.util.concurrent.TimeUnit timeUnit,
             ContainerResponseWriter.TimeoutHandler timeoutHandler)
             throws java.lang.IllegalStateException

Suspend the request/response processing. Container must not automatically commit the response writer when the processing on the 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 either calling commit() or cancel() method.

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.

Throws:

java.lang.IllegalStateException - in case the container response writer has already been suspended.

See Also:

setSuspendTimeout(long, TimeUnit), cancel(), commit()

setSuspendTimeout

void setSuspendTimeout(long timeOut,
                       java.util.concurrent.TimeUnit timeUnit)
                       throws java.lang.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:

java.lang.IllegalStateException - in case the container has not been suspended yet.

See Also:

setSuspendTimeout(long, TimeUnit)

cancel

void cancel()

Cancel the request/response processing. This method automatically commits and closes the writer.

By invoking this method, Jersey application handler indicates to the container that the request processing related to this container context has been canceled.

Similarly to commit(), this enables the container context to release any resources, clean up any state, etc. The main difference is that a call to the cancel() method indicates that any unsent response data in the container buffer should be discarded.

See Also:

commit(), suspend(long, TimeUnit, TimeoutHandler)

commit

void commit()

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

See Also:

cancel(), suspend(long, TimeUnit, TimeoutHandler)