public abstract class EntityStreamingSupport
extends java.lang.Object
Source[T, _]
from HTTP entities.
See JsonEntityStreamingSupport
or CsvEntityStreamingSupport
for default implementations.
Constructor and Description |
---|
EntityStreamingSupport() |
Modifier and Type | Method and Description |
---|---|
abstract ContentType |
contentType()
Write-side, defines what Content-Type the Marshaller should offer and the final Content-Type of the response.
|
static CsvEntityStreamingSupport |
csv()
Default
text/csv(UTF-8) entity streaming support. |
static CsvEntityStreamingSupport |
csv(int maxLineLength)
Default
text/csv(UTF-8) entity streaming support. |
abstract org.apache.pekko.stream.javadsl.Flow<org.apache.pekko.util.ByteString,org.apache.pekko.util.ByteString,org.apache.pekko.NotUsed> |
getFramingDecoder()
Read-side, decode incoming framed entity.
|
abstract org.apache.pekko.stream.javadsl.Flow<org.apache.pekko.util.ByteString,org.apache.pekko.util.ByteString,org.apache.pekko.NotUsed> |
getFramingRenderer()
Write-side, apply framing to outgoing entity stream.
|
static JsonEntityStreamingSupport |
json()
Default
application/json entity streaming support. |
static JsonEntityStreamingSupport |
json(int maxObjectLength)
Default
application/json entity streaming support. |
abstract int |
parallelism()
Write-side / read-side, defines if (un)marshalling should be done in parallel.
|
abstract ContentTypeRange |
supported()
Read-side, what content types it is able to frame and unmarshall.
|
abstract boolean |
unordered()
Write-side / read-side, defines if (un)marshalling of incoming stream elements should be preserved or not.
|
abstract EntityStreamingSupport |
withContentType(ContentType range)
Write-side, defines what Content-Type the Marshaller should offer and the final Content-Type of the response.
|
abstract EntityStreamingSupport |
withParallelMarshalling(int parallelism,
boolean unordered)
Write-side / read-side, defines parallelism and if ordering should be preserved or not of Source element marshalling.
|
abstract EntityStreamingSupport |
withSupported(ContentTypeRange range)
Read-side, allows changing what content types are accepted by this framing.
|
public static JsonEntityStreamingSupport json()
application/json
entity streaming support.
Provides framing (based on scanning the incoming dataBytes for valid JSON objects, so for example uploads using arrays or
new-line separated JSON objects are all parsed correctly) and rendering of Sources as JSON Arrays.
A different very popular style of returning streaming JSON is to separate JSON objects on a line-by-line basis,
you can configure the support trait to do so by calling withFramingRendererFlow
.
Limits the maximum JSON object length to 8KB, if you want to increase this limit provide a value explicitly.
public static JsonEntityStreamingSupport json(int maxObjectLength)
application/json
entity streaming support.
Provides framing (based on scanning the incoming dataBytes for valid JSON objects, so for example uploads using arrays or
new-line separated JSON objects are all parsed correctly) and rendering of Sources as JSON Arrays.
A different very popular style of returning streaming JSON is to separate JSON objects on a line-by-line basis,
you can configure the support trait to do so by calling withFramingRendererFlow
.
maxObjectLength
- (undocumented)public static CsvEntityStreamingSupport csv()
text/csv(UTF-8)
entity streaming support.
Provides framing and rendering of \n
separated lines and marshalling Sources into such values.
Limits the maximum line-length to 8KB, if you want to increase this limit provide a value explicitly.
public static CsvEntityStreamingSupport csv(int maxLineLength)
text/csv(UTF-8)
entity streaming support.
Provides framing and rendering of \n
separated lines and marshalling Sources into such values.maxLineLength
- (undocumented)public abstract ContentTypeRange supported()
public abstract ContentType contentType()
public abstract org.apache.pekko.stream.javadsl.Flow<org.apache.pekko.util.ByteString,org.apache.pekko.util.ByteString,org.apache.pekko.NotUsed> getFramingDecoder()
public abstract org.apache.pekko.stream.javadsl.Flow<org.apache.pekko.util.ByteString,org.apache.pekko.util.ByteString,org.apache.pekko.NotUsed> getFramingRenderer()
Most typical usage will be a variant of Flow[ByteString].intersperse
.
For example for rendering a JSON array one would return
Flow[ByteString].intersperse(ByteString("["), ByteString(","), ByteString("]"))
and for rendering a new-line separated CSV simply Flow[ByteString].intersperse(ByteString("\n"))
.
public abstract EntityStreamingSupport withSupported(ContentTypeRange range)
EntityStreamingSupport traits MUST support re-configuring the accepted ContentTypeRange
.
This is in order to support a-typical APIs which users still want to communicate with using
the provided support trait. Typical examples include APIs which return valid application/json
however advertise the content type as being application/javascript
or vendor specific content types,
which still parse correctly as JSON, CSV or something else that a provided support trait is built for.
NOTE: Implementations should specialize the return type to their own Type!
range
- (undocumented)public abstract EntityStreamingSupport withContentType(ContentType range)
EntityStreamingSupport traits MUST support re-configuring the offered ContentType
.
This is due to the need integrating with existing systems which sometimes excpect custom Content-Types,
however really are just plain JSON or something else internally (perhaps with slight extensions).
NOTE: Implementations should specialize the return type to their own Type!
range
- (undocumented)public abstract int parallelism()
This may be beneficial marshalling the bottleneck in the pipeline.
See also parallelism
and withParallelMarshalling
.
public abstract boolean unordered()
Allowing for parallel and unordered (un)marshalling often yields higher throughput and also allows avoiding head-of-line blocking if some elements are much larger than others.
See also parallelism
and withParallelMarshalling
.
public abstract EntityStreamingSupport withParallelMarshalling(int parallelism, boolean unordered)
Sometimes marshalling multiple elements at once (esp. when elements are not evenly sized, and ordering is not enforced) may yield in higher throughput.
NOTE: Implementations should specialize the return type to their own Type!
parallelism
- (undocumented)unordered
- (undocumented)