org.springframework.web.servlet.mvc.method.annotation

Class ResponseBodyEmitter

java.lang.Object

org.springframework.web.servlet.mvc.method.annotation.ResponseBodyEmitter

Direct Known Subclasses:

SseEmitter

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();
 

Since:

4.2

Author:

Rossen Stoyanchev, Juergen Hoeller

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
(package private) static class	ResponseBodyEmitter.DataWithMediaType Simple struct for a data entry.
(package private) static interface	ResponseBodyEmitter.Handler Handle sent objects and complete request processing.

Field Summary

Fields

Modifier and Type	Field and Description
private boolean	complete
private java.lang.Runnable	completionCallback
private java.util.Set<ResponseBodyEmitter.DataWithMediaType>	earlySendAttempts
private java.lang.Throwable	failure
private ResponseBodyEmitter.Handler	handler
private java.lang.Long	timeout
private java.lang.Runnable	timeoutCallback

Constructor Summary

Constructors

Constructor and Description
ResponseBodyEmitter() Create a new ResponseBodyEmitter instance.
ResponseBodyEmitter(java.lang.Long timeout) Create a ResponseBodyEmitter with a custom timeout value.

Method Summary

Modifier and Type	Method and Description
void	complete() Complete request processing.
void	completeWithError(java.lang.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.
java.lang.Long	getTimeout() Return the configured timeout value, if any.
(package private) void	initialize(ResponseBodyEmitter.Handler handler)
void	onCompletion(java.lang.Runnable callback) Register code to invoke when the async request completes.
void	onTimeout(java.lang.Runnable callback) Register code to invoke when the async request times out.
void	send(java.lang.Object object) Write the given object to the response.
void	send(java.lang.Object object, MediaType mediaType) Write the given object to the response also using a MediaType hint.
private void	sendInternal(java.lang.Object object, MediaType mediaType)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

timeout

private final java.lang.Long timeout

earlySendAttempts

private final java.util.Set<ResponseBodyEmitter.DataWithMediaType> earlySendAttempts

handler

private ResponseBodyEmitter.Handler handler

complete

private boolean complete

failure

private java.lang.Throwable failure

timeoutCallback

private java.lang.Runnable timeoutCallback

completionCallback

private java.lang.Runnable completionCallback

Constructor Detail

ResponseBodyEmitter

public ResponseBodyEmitter()

Create a new ResponseBodyEmitter instance.

ResponseBodyEmitter

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.

Parameters:

timeout - timeout value in milliseconds

Method Detail

getTimeout

public java.lang.Long getTimeout()

Return the configured timeout value, if any.

extendResponse

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.

initialize

void initialize(ResponseBodyEmitter.Handler handler)
         throws java.io.IOException

Throws:

java.io.IOException

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.

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,
                 MediaType mediaType)
          throws java.io.IOException

Write the given object to the response also using a MediaType hint.

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.

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

sendInternal

private void sendInternal(java.lang.Object object,
                          MediaType mediaType)
                   throws java.io.IOException

Throws:

java.io.IOException

complete

public void complete()

Complete request processing.

A dispatch is made into the app server where Spring MVC completes asynchronous request processing.

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.

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.

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.