Module org.elasticsearch.server

Package org.elasticsearch.rest

Interface ChunkedRestResponseBodyPart

All Known Implementing Classes:

LoggingChunkedRestResponseBodyPart

public interface ChunkedRestResponseBodyPart

A body (or a part thereof) of an HTTP response that uses the chunked transfer-encoding. This allows Elasticsearch to avoid materializing the full response into on-heap buffers up front, instead serializing only as much of the response as can be flushed to the network right away.

Each ChunkedRestResponseBodyPart represents a sequence of chunks that are ready for immediate transmission: if isPartComplete() returns false then encodeChunk(int, org.elasticsearch.common.recycler.Recycler<org.apache.lucene.util.BytesRef>) can be called at any time and must synchronously return the next chunk to be sent. Many HTTP responses will be a single part, but if an implementation's isLastPart() returns false at the end of the part then the transmission is paused and getNextPart(org.elasticsearch.action.ActionListener<org.elasticsearch.rest.ChunkedRestResponseBodyPart>) is called to compute the next sequence of chunks asynchronously.

Field Summary

Fields

Modifier and Type	Field	Description
static final Logger	logger

Method Summary

Modifier and Type	Method	Description
ReleasableBytesReference	encodeChunk(int sizeHint, Recycler<org.apache.lucene.util.BytesRef> recycler)	Serializes approximately as many bytes of the response as request by sizeHint to a ReleasableBytesReference that is created from buffers backed by the given recycler.
static ChunkedRestResponseBodyPart	fromTextChunks(String contentType, Iterator<CheckedConsumer<Writer,IOException>> chunkIterator)	Create a one-part chunked response body to be written to a specific RestChannel from a stream of UTF-8-encoded text chunks, each represented as a consumer of a Writer.
static ChunkedRestResponseBodyPart	fromXContent(ChunkedToXContent chunkedToXContent, ToXContent.Params params, RestChannel channel)	Create a one-part chunked response body to be written to a specific RestChannel from a ChunkedToXContent.
void	getNextPart(ActionListener<ChunkedRestResponseBodyPart> listener)	Asynchronously retrieves the next part of the response body.
String	getResponseContentTypeString()
boolean	isLastPart()
boolean	isPartComplete()

Field Details

logger

static final Logger logger

Method Details

isPartComplete

boolean isPartComplete()

Returns:

true if this body part contains no more chunks and the REST layer should check for a possible continuation by calling isLastPart(), or false if the REST layer should request another chunk from this body using encodeChunk(int, org.elasticsearch.common.recycler.Recycler<org.apache.lucene.util.BytesRef>).

isLastPart

boolean isLastPart()

Returns:

true if this is the last chunked body part in the response, or false if the REST layer should request further chunked bodies by calling getNextPart(org.elasticsearch.action.ActionListener<org.elasticsearch.rest.ChunkedRestResponseBodyPart>).

getNextPart

void getNextPart(ActionListener<ChunkedRestResponseBodyPart> listener)

Asynchronously retrieves the next part of the response body. Called if isLastPart() returns false.

Note that this is called on a transport thread: implementations must take care to dispatch any nontrivial work elsewhere.

Note that the Task corresponding to any invocation of ElasticsearchClient.execute(org.elasticsearch.action.ActionType<Response>, Request) completes as soon as the client action returns its response, so it no longer exists when this method is called and cannot be used to receive cancellation notifications. Instead, if the HTTP channel is closed while sending a response then the REST layer will invoke RestResponse.close(). If the HTTP channel is closed while the REST layer is waiting for a continuation then the RestResponse will not be closed until the continuation listener is completed. Implementations will typically explicitly create a CancellableTask to represent the computation and transmission of the entire RestResponse, and will cancel this task if the RestResponse is closed prematurely.

Parameters:

listener - Listener to complete with the next part of the body. By the point this is called we have already started to send the body of the response, so there's no good ways to handle an exception here. Completing the listener exceptionally will log an error, abort sending the response, and close the HTTP connection.

encodeChunk

ReleasableBytesReference encodeChunk(int sizeHint,
 Recycler<org.apache.lucene.util.BytesRef> recycler)
                              throws IOException

Serializes approximately as many bytes of the response as request by sizeHint to a ReleasableBytesReference that is created from buffers backed by the given recycler.

Parameters:

sizeHint - how many bytes to approximately serialize for the given chunk

recycler - recycler used to acquire buffers

Returns:

serialized chunk

Throws:

IOException - on serialization failure

getResponseContentTypeString

String getResponseContentTypeString()

Returns:

the response Content-Type header value for this response body

fromXContent

static ChunkedRestResponseBodyPart fromXContent(ChunkedToXContent chunkedToXContent,
 ToXContent.Params params,
 RestChannel channel)
                                         throws IOException

Create a one-part chunked response body to be written to a specific RestChannel from a ChunkedToXContent.

Parameters:

chunkedToXContent - chunked x-content instance to serialize

params - parameters to use for serialization

channel - channel the response will be written to

Returns:

chunked rest response body

Throws:

IOException

fromTextChunks

static ChunkedRestResponseBodyPart fromTextChunks(String contentType,
 Iterator<CheckedConsumer<Writer,IOException>> chunkIterator)

Create a one-part chunked response body to be written to a specific RestChannel from a stream of UTF-8-encoded text chunks, each represented as a consumer of a Writer.