public class ResponseBodyEmitter extends Object
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();
Modifier and Type | Class and Description |
---|---|
static class |
ResponseBodyEmitter.DataWithMediaType
A simple holder of data to be written along with a MediaType hint for
selecting a message converter to write with.
|
Constructor and Description |
---|
ResponseBodyEmitter()
Create a new ResponseBodyEmitter instance.
|
ResponseBodyEmitter(Long timeout)
Create a ResponseBodyEmitter with a custom timeout value.
|
Modifier and Type | Method and Description |
---|---|
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.
|
void |
completeWithError(Throwable ex)
Complete request processing with an error.
|
protected void |
extendResponse(ServerHttpResponse outputMessage)
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.
|
Long |
getTimeout()
Return the configured timeout value, if any.
|
void |
onCompletion(Runnable callback)
Register code to invoke when the async request completes.
|
void |
onError(Consumer<Throwable> callback)
Register code to invoke for an error during async request processing.
|
void |
onTimeout(Runnable callback)
Register code to invoke when the async request times out.
|
void |
send(Object object)
Write the given object to the response.
|
void |
send(Object object,
MediaType mediaType)
Overloaded variant of
send(Object) that also accepts a MediaType
hint for how to serialize the given Object. |
String |
toString() |
public ResponseBodyEmitter()
public ResponseBodyEmitter(Long timeout)
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.
timeout
- the timeout value in millisecondsprotected void extendResponse(ServerHttpResponse outputMessage)
The default implementation is empty.
public void send(Object object) throws IOException
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.
object
- the object to writeIOException
- raised when an I/O error occursIllegalStateException
- wraps any other errorspublic void send(Object object, @Nullable MediaType mediaType) throws IOException
send(Object)
that also accepts a MediaType
hint for how to serialize the given Object.object
- the object to writemediaType
- a MediaType hint for selecting an HttpMessageConverterIOException
- raised when an I/O error occursIllegalStateException
- wraps any other errorspublic void complete()
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
.
public void completeWithError(Throwable ex)
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
.
public void onTimeout(Runnable callback)
public void onError(Consumer<Throwable> callback)
public void onCompletion(Runnable callback)
ResponseBodyEmitter
instance is no longer usable.