ResponseBodyEmitter (Spring Framework 5.1.0.RELEASE API)

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
`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 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

All Methods Instance Methods Concrete Methods
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(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.
`void`	`onCompletion(java.lang.Runnable callback)` Register code to invoke when the async request completes.
`void`	`onError(java.util.function.Consumer<java.lang.Throwable> callback)` Register code to invoke for an error during async request processing.
`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)` Overloaded variant of `send(Object)` that also accepts a MediaType hint for how to serialize the given Object.
`java.lang.String`	`toString()`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- 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
```
@Nullable
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.
  - 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,
                 @Nullable
                 MediaType 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.
  - toString
```
public java.lang.String toString()
```
    Overrides:
    
    toString in class java.lang.Object

Class ResponseBodyEmitter

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

ResponseBodyEmitter

ResponseBodyEmitter

Method Detail

getTimeout

extendResponse

send

send

complete

completeWithError

onTimeout

onError

onCompletion

toString