public class ResponseBodyEmitter
extends java.lang.Object
A controller method return value type for asynchronous request processing
where one or more objects are written to the response.
While DeferredResult
is used to produce a single result, a ResponseBodyEmitter can be used
to send multiple objects where each object is written with a compatible
HttpMessageConverter.
Supported as a return type on its own as well as within a
ResponseEntity.
@RequestMapping(value="/stream", method=RequestMethod.GET)
public ResponseBodyEmitter handle() {
ResponseBodyEmitter emitter = new ResponseBodyEmitter();
// Pass the emitter to another component...
return emitter;
}
// in another thread
emitter.send(foo1);
// and again
emitter.send(foo2);
// and done
emitter.complete();
Complete request processing by performing a dispatch into the servlet
container, where Spring MVC is invoked once more, and completes the
request processing lifecycle.
Invoked after the response is updated with the status code and headers,
if the ResponseBodyEmitter is wrapped in a ResponseEntity, but before the
response is committed, i.e.
public ResponseBodyEmitter(java.lang.Long timeout)
Create a ResponseBodyEmitter with a custom timeout value.
By default not set in which case the default configured in the MVC
Java Config or the MVC namespace is used, or if that's not set, then the
timeout depends on the default of the underlying server.
Invoked after the response is updated with the status code and headers,
if the ResponseBodyEmitter is wrapped in a ResponseEntity, but before the
response is committed, i.e. before the response body has been written to.
The default implementation is empty.
send
public void send(java.lang.Object object)
throws java.io.IOException
Write the given object to the response.
If any exception occurs a dispatch is made back to the app server where
Spring MVC will pass the exception through its exception handling mechanism.
Note: if the send fails with an IOException, you do
not need to call completeWithError(Throwable) in order to clean
up. Instead the Servlet container creates a notification that results in a
dispatch where Spring MVC invokes exception resolvers and completes
processing.
Parameters:
object - the object to write
Throws:
java.io.IOException - raised when an I/O error occurs
java.lang.IllegalStateException - wraps any other errors
send
public void send(java.lang.Object object,
@NullableMediaType mediaType)
throws java.io.IOException
Overloaded variant of send(Object) that also accepts a MediaType
hint for how to serialize the given Object.
Parameters:
object - the object to write
mediaType - a MediaType hint for selecting an HttpMessageConverter
Throws:
java.io.IOException - raised when an I/O error occurs
java.lang.IllegalStateException - wraps any other errors
complete
public void complete()
Complete request processing by performing a dispatch into the servlet
container, where Spring MVC is invoked once more, and completes the
request processing lifecycle.
Note: this method should be called by the application
to complete request processing. It should not be used after container
related events such as an error while sending.
completeWithError
public void completeWithError(java.lang.Throwable ex)
Complete request processing with an error.
A dispatch is made into the app server where Spring MVC will pass the
exception through its exception handling mechanism. Note however that
at this stage of request processing, the response is committed and the
response status can no longer be changed.
Note: this method should be called by the application
to complete request processing with an error. It should not be used after
container related events such as an error while
sending.
onTimeout
public void onTimeout(java.lang.Runnable callback)
Register code to invoke when the async request times out. This method is
called from a container thread when an async request times out.
onError
public void onError(java.util.function.Consumer<java.lang.Throwable> callback)
Register code to invoke for an error during async request processing.
This method is called from a container thread when an error occurred
while processing an async request.
Since:
5.0
onCompletion
public void onCompletion(java.lang.Runnable callback)
Register code to invoke when the async request completes. This method is
called from a container thread when an async request completed for any
reason including timeout and network error. This method is useful for
detecting that a ResponseBodyEmitter instance is no longer usable.