Class ResponseBodyEmitter
- Direct Known Subclasses:
SseEmitter
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();
- Since:
- 4.2
- Author:
- Rossen Stoyanchev, Juergen Hoeller, Brian Clozel
-
Nested Class Summary
Modifier and TypeClassDescriptionstatic class
A simple holder of data to be written along with a MediaType hint for selecting a message converter to write with. -
Constructor Summary
ConstructorDescriptionCreate a new ResponseBodyEmitter instance.ResponseBodyEmitter
(Long timeout) Create a ResponseBodyEmitter with a custom timeout value. -
Method Summary
Modifier and TypeMethodDescriptionvoid
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
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.Return the configured timeout value, if any.void
onCompletion
(Runnable callback) Register code to invoke when the async request completes.void
Register code to invoke for an error during async request processing.void
Register code to invoke when the async request times out.void
Write the given object to the response.void
Overloaded variant ofsend(Object)
that also accepts a MediaType hint for how to serialize the given Object.void
Write a set of data and MediaType pairs in a batch.toString()
-
Constructor Details
-
ResponseBodyEmitter
public ResponseBodyEmitter()Create a new ResponseBodyEmitter instance. -
ResponseBodyEmitter
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.
- Parameters:
timeout
- the timeout value in milliseconds
-
-
Method Details
-
getTimeout
Return the configured timeout value, if any. -
extendResponse
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
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:
IOException
- raised when an I/O error occursIllegalStateException
- wraps any other errors
-
send
Overloaded variant ofsend(Object)
that also accepts a MediaType hint for how to serialize the given Object.- Parameters:
object
- the object to writemediaType
- a MediaType hint for selecting an HttpMessageConverter- Throws:
IOException
- raised when an I/O error occursIllegalStateException
- wraps any other errors
-
send
Write a set of data and MediaType pairs in a batch.Compared to
send(Object, MediaType)
, this batches the write operations and flushes to the network at the end.- Parameters:
items
- the object and media type pairs to write- Throws:
IOException
- raised when an I/O error occursIllegalStateException
- wraps any other errors- Since:
- 6.0.12
-
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
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
Register code to invoke when the async request times out. This method is called from a container thread when an async request times out.As of 6.2, one can register multiple callbacks for this event.
-
onError
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.As of 6.2, one can register multiple callbacks for this event.
- Since:
- 5.0
-
onCompletion
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 aResponseBodyEmitter
instance is no longer usable.As of 6.2, one can register multiple callbacks for this event.
-
toString
-