A controller method return value type for asynchronous request processing where one or more objects are written to the response.

While org.springframework.web.context.request.async.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 org.springframework.http.converter.HttpMessageConverter.

Supported as a return type on its own as well as within a org.springframework.http.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();

Nested and Inner Type Summary

Modifier and Type	Class and Description
public 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.
private class	ResponseBodyEmitter.DefaultCallback
private class	ResponseBodyEmitter.ErrorCallback
pack-priv static interface	ResponseBodyEmitter.Handler Contract to handle the sending of event data, the completion of event sending, and the registration of callbacks to be invoked in case of timeout, error, and completion for any reason (including from the container side).

Field Summary

Modifier and Type	Field and Description
private boolean	complete Store successful completion before the handler is initialized.
private final ResponseBodyEmitter.DefaultCallback	completionCallback
private final Set<ResponseBodyEmitter.DataWithMediaType>	earlySendAttempts Store send data before handler is initialized.
private final ResponseBodyEmitter.ErrorCallback	errorCallback
private Throwable	failure Store an error before the handler is initialized.
private ResponseBodyEmitter.Handler	handler
private boolean	ioErrorOnSend After an I/O error, we don't call `completeWithError` directly but wait for the Servlet container to call us via `AsyncListener#onError` on a container thread at which point we call completeWithError.
private final Long	timeout
private final ResponseBodyEmitter.DefaultCallback	timeoutCallback

Constructor Summary

Access	Constructor and Description
public	ResponseBodyEmitter() Create a new ResponseBodyEmitter instance.
public	ResponseBodyEmitter(Long the timeout value in milliseconds timeout) Create a ResponseBodyEmitter with a custom timeout value.

Method Summary

Modifier and Type	Method and Description
public synchronized 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.
public synchronized 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. before the response body has been written to.
public Long	getTimeout() Return the configured timeout value, if any.
pack-priv synchronized void	initialize(ResponseBodyEmitter.Handler handler)
pack-priv synchronized void	initializeWithError(Throwable ex)
public synchronized void	onCompletion(Runnable callback) Register code to invoke when the async request completes.
public synchronized void	onError(Consumer<Throwable> callback) Register code to invoke for an error during async request processing.
public synchronized void	onTimeout(Runnable callback) Register code to invoke when the async request times out.
public void	send(Object the object to write object) Write the given object to the response.
public synchronized void	send(Object the object to write object, MediaType a MediaType hint for selecting an HttpMessageConverter mediaType) Overloaded variant of `send(Object)` that also accepts a MediaType hint for how to serialize the given Object.
public synchronized void	send(Set<ResponseBodyEmitter.DataWithMediaType> the object and media type pairs to write items) Write a set of data and MediaType pairs in a batch.
private void	sendInternal(Set<ResponseBodyEmitter.DataWithMediaType> items)
public String	toString() Overrides java.lang.Object.toString. Returns a string representation of the object.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll wait wait wait

Field Detail

complete	back to summary
private boolean complete Store successful completion before the handler is initialized.

completionCallback	back to summary
private final ResponseBodyEmitter.DefaultCallback completionCallback

earlySendAttempts	back to summary
private final Set<ResponseBodyEmitter.DataWithMediaType> earlySendAttempts Store send data before handler is initialized.

errorCallback	back to summary
private final ResponseBodyEmitter.ErrorCallback errorCallback

failure	back to summary
private Throwable failure Store an error before the handler is initialized. Annotations @Nullable

handler	back to summary
private ResponseBodyEmitter.Handler handler Annotations @Nullable

ioErrorOnSend back to summary

ioErrorOnSend	back to summary
private boolean ioErrorOnSend After an I/O error, we don't call `completeWithError` directly but wait for the Servlet container to call us via `AsyncListener#onError` on a container thread at which point we call completeWithError. This flag is used to ignore further calls to complete or completeWithError that may come for example from an application try-catch block on the thread of the I/O error.

private boolean ioErrorOnSend

After an I/O error, we don't call completeWithError directly but wait for the Servlet container to call us via AsyncListener#onError on a container thread at which point we call completeWithError. This flag is used to ignore further calls to complete or completeWithError that may come for example from an application try-catch block on the thread of the I/O error.

timeout	back to summary
private final Long timeout Annotations @Nullable

timeoutCallback	back to summary
private final ResponseBodyEmitter.DefaultCallback timeoutCallback

Constructor Detail

ResponseBodyEmitter	back to summary
public ResponseBodyEmitter() Create a new ResponseBodyEmitter instance.

ResponseBodyEmitter	back to summary
public ResponseBodyEmitter(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. Parameters timeout:Long the timeout value in milliseconds

ResponseBodyEmitter

back to summary

public ResponseBodyEmitter(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.

Parameters

timeout:Long: the timeout value in milliseconds

Method Detail

complete	back to summary
public synchronized 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 back to summary

completeWithError	back to summary
public synchronized void completeWithError(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`.

public synchronized void completeWithError(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.

extendResponse	back to summary
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. before the response body has been written to. The default implementation is empty.

extendResponse

back to summary

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. before the response body has been written to.

The default implementation is empty.

getTimeout	back to summary
public Long getTimeout() Return the configured timeout value, if any. Annotations @Nullable

getTimeout

back to summary

public Long getTimeout()

Return the configured timeout value, if any.

Annotations

@Nullable

initialize	back to summary
pack-priv synchronized void initialize(ResponseBodyEmitter.Handler handler) throws IOException

initializeWithError	back to summary
pack-priv synchronized void initializeWithError(Throwable ex)

onCompletion	back to summary
public synchronized void onCompletion(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.

onError	back to summary
public synchronized void onError(Consumer<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

onError

back to summary

public synchronized void onError(Consumer<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

onTimeout	back to summary
public synchronized void onTimeout(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.

send back to summary

send	back to summary
public void send(Object object) throws 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:Object the object to write Exceptions IOException: raised when an I/O error occurs IllegalStateException: wraps any other errors

public void send(Object object) throws 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:Object: the object to write

Exceptions

IOException:: raised when an I/O error occurs
IllegalStateException:: wraps any other errors

send back to summary

send	back to summary
public synchronized void send(Object object, MediaType mediaType) throws IOException Overloaded variant of `send(Object)` that also accepts a MediaType hint for how to serialize the given Object. Parameters object:Object the object to write mediaType:MediaType a MediaType hint for selecting an HttpMessageConverter Exceptions IOException: raised when an I/O error occurs IllegalStateException: wraps any other errors

public synchronized void send(Object object, MediaType mediaType) throws IOException

Overloaded variant of send(Object) that also accepts a MediaType hint for how to serialize the given Object.

Parameters

object:Object: the object to write
mediaType:MediaType: a MediaType hint for selecting an HttpMessageConverter

Exceptions

IOException:: raised when an I/O error occurs
IllegalStateException:: wraps any other errors

send back to summary

send	back to summary
public synchronized void send(Set<ResponseBodyEmitter.DataWithMediaType> items) throws IOException 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:Set<ResponseBodyEmitter.DataWithMediaType> the object and media type pairs to write Exceptions IOException: raised when an I/O error occurs IllegalStateException: wraps any other errors Since 6.0.12

public synchronized void send(Set<ResponseBodyEmitter.DataWithMediaType> items) throws IOException

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:Set<ResponseBodyEmitter.DataWithMediaType>: the object and media type pairs to write

Exceptions

IOException:: raised when an I/O error occurs
IllegalStateException:: wraps any other errors

Since

6.0.12

sendInternal	back to summary
private void sendInternal(Set<ResponseBodyEmitter.DataWithMediaType> items) throws IOException

toString back to summary

toString	back to summary
public String toString() Overrides java.lang.Object.toString. Doc from java.lang.Object.toString. Returns a string representation of the object. Satisfying this method's contract implies a non-`null` result must be returned. Returns:String a string representation of the object Annotations @Override

public String toString()

Overrides java.lang.Object.toString.

Doc from java.lang.Object.toString.

Returns a string representation of the object. Satisfying this method's contract implies a non-null result must be returned.

Returns:String

a string representation of the object

Annotations

@Override

org.springframework.web.servlet.mvc.method.annotation back to summary

public Class ResponseBodyEmitter.DataWithMediaType

Class Inheritance

extends Object

java.lang.Object
org.springframework.web.servlet.mvc.method.annotation.ResponseBodyEmitter.DataWithMediaType

A simple holder of data to be written along with a MediaType hint for selecting a message converter to write with.

Field Summary

Modifier and Type	Field and Description
private final Object	data
private final MediaType	mediaType

Constructor Summary

Access	Constructor and Description
public	DataWithMediaType(Object data, MediaType mediaType)

Method Summary

Modifier and Type	Method and Description
public Object	getData()
public MediaType	getMediaType()

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

data	back to summary
private final Object data

mediaType	back to summary
private final MediaType mediaType Annotations @Nullable

Constructor Detail

DataWithMediaType	back to summary
public DataWithMediaType(Object data, MediaType mediaType)

Method Detail

getData	back to summary
public Object getData()

getMediaType	back to summary
public MediaType getMediaType() Annotations @Nullable

org.springframework.web.servlet.mvc.method.annotation back to summary

private Class ResponseBodyEmitter.DefaultCallback

Class Inheritance

extends Object
implements Runnable

java.lang.Object
org.springframework.web.servlet.mvc.method.annotation.ResponseBodyEmitter.DefaultCallback

All Implemented Interfaces

java.lang.Runnable

Field Summary

Modifier and Type	Field and Description
private Runnable	delegate

Constructor Summary

Access	Constructor and Description
private	DefaultCallback()

Method Summary

Modifier and Type	Method and Description
public void	run() Implements java.lang.Runnable.run. Runs this operation.
public void	setDelegate(Runnable delegate)

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

delegate	back to summary
private Runnable delegate Annotations @Nullable

Constructor Detail

DefaultCallback	back to summary
private DefaultCallback()

Method Detail

run	back to summary
public void run() Implements java.lang.Runnable.run. Doc from java.lang.Runnable.run. Runs this operation. Annotations @Override

run

back to summary

public void run()

Implements java.lang.Runnable.run.

Doc from java.lang.Runnable.run.

Runs this operation.

Annotations

@Override

setDelegate	back to summary
public void setDelegate(Runnable delegate)

org.springframework.web.servlet.mvc.method.annotation back to summary

private Class ResponseBodyEmitter.ErrorCallback

Class Inheritance

extends Object
implements Consumer<Throwable>

java.lang.Object
org.springframework.web.servlet.mvc.method.annotation.ResponseBodyEmitter.ErrorCallback

All Implemented Interfaces

java.util.function.Consumer

Field Summary

Modifier and Type	Field and Description
private Consumer<Throwable>	delegate

Constructor Summary

Access	Constructor and Description
private	ErrorCallback()

Method Summary

Modifier and Type	Method and Description
public void	accept(Throwable the input argument t) Implements java.util.function.Consumer.accept. Performs this operation on the given argument.
public void	setDelegate(Consumer<Throwable> callback)

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

delegate	back to summary
private Consumer<Throwable> delegate Annotations @Nullable

Constructor Detail

ErrorCallback	back to summary
private ErrorCallback()

Method Detail

accept	back to summary
public void accept(Throwable t) Implements java.util.function.Consumer.accept. Doc from java.util.function.Consumer.accept. Performs this operation on the given argument. Parameters t:Throwable the input argument Annotations @Override

back to summary

public void accept(Throwable t)

Implements java.util.function.Consumer.accept.

Doc from java.util.function.Consumer.accept.

Performs this operation on the given argument.

Parameters

t:Throwable: the input argument

Annotations

@Override

setDelegate	back to summary
public void setDelegate(Consumer<Throwable> callback)

org.springframework.web.servlet.mvc.method.annotation back to summary

pack-priv Interface ResponseBodyEmitter.Handler

Known Direct Implementers: org.springframework.web.servlet.mvc.method.annotation.ResponseBodyEmitterReturnValueHandler.HttpMessageConvertingHandler

Contract to handle the sending of event data, the completion of event sending, and the registration of callbacks to be invoked in case of timeout, error, and completion for any reason (including from the container side).

Method Summary

Modifier and Type	Method and Description
public void	complete()
public void	completeWithError(Throwable failure)
public void	onCompletion(Runnable callback)
public void	onError(Consumer<Throwable> callback)
public void	onTimeout(Runnable callback)
public void	send(Object data, MediaType mediaType) Immediately write and flush the given data to the network.
public void	send(Set<ResponseBodyEmitter.DataWithMediaType> items) Immediately write all data items then flush to the network.

Method Detail

complete	back to summary
public void complete()

completeWithError	back to summary
public void completeWithError(Throwable failure)

onCompletion	back to summary
public void onCompletion(Runnable callback)

onError	back to summary
public void onError(Consumer<Throwable> callback)

onTimeout	back to summary
public void onTimeout(Runnable callback)

send	back to summary
public void send(Object data, MediaType mediaType) throws IOException Immediately write and flush the given data to the network.

send

back to summary

public void send(Set<ResponseBodyEmitter.DataWithMediaType> items) throws IOException

Immediately write all data items then flush to the network.

Since: 6.0.12