Package org.apache.pekko.http.scaladsl.common

Class EntityStreamingSupport

java.lang.Object
org.apache.pekko.http.javadsl.common.EntityStreamingSupport
org.apache.pekko.http.scaladsl.common.EntityStreamingSupport
Direct Known Subclasses:
CsvEntityStreamingSupport, JsonEntityStreamingSupport
public abstract class EntityStreamingSupport extends EntityStreamingSupport
Entity streaming support trait allowing rendering and receiving incoming Source[T, _] from HTTP entities.

See JsonEntityStreamingSupport or CsvEntityStreamingSupport for default implementations.

  • Constructor Summary

    Constructors
    Constructor
    Description
    EntityStreamingSupport()
     

  • Method Summary

    Modifier and Type
    Method
    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.scaladsl.Flow<org.apache.pekko.util.ByteString,org.apache.pekko.util.ByteString,org.apache.pekko.NotUsed>
    framingDecoder()
    Read-side, decode incoming framed entity.
    abstract org.apache.pekko.stream.scaladsl.Flow<org.apache.pekko.util.ByteString,org.apache.pekko.util.ByteString,org.apache.pekko.NotUsed>
    framingRenderer()
    Write-side, apply framing to outgoing entity stream.
    final 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.
    final 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 should preserve ordering of incoming stream elements.
    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.

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • EntityStreamingSupport

      public EntityStreamingSupport()

  • Method Details

    • json

      public static JsonEntityStreamingSupport json()
      Default 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.

      See also https://en.wikipedia.org/wiki/JSON_Streaming

      Returns:
      (undocumented)

    • json

      public static JsonEntityStreamingSupport json(int maxObjectLength)
      Default 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.

      See also https://en.wikipedia.org/wiki/JSON_Streaming

      Parameters:
      maxObjectLength - (undocumented)
      Returns:
      (undocumented)

    • csv

      public static CsvEntityStreamingSupport csv()
      Default 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.

      Returns:
      (undocumented)

    • csv

      public static CsvEntityStreamingSupport csv(int maxLineLength)
      Default text/csv(UTF-8) entity streaming support. Provides framing and rendering of \n separated lines and marshalling Sources into such values.
      Parameters:
      maxLineLength - (undocumented)
      Returns:
      (undocumented)

    • supported

      public abstract ContentTypeRange supported()
      Read-side, what content types it is able to frame and unmarshall.
      Specified by:
      supported in class EntityStreamingSupport

    • contentType

      public abstract ContentType contentType()
      Write-side, defines what Content-Type the Marshaller should offer and the final Content-Type of the response.
      Specified by:
      contentType in class EntityStreamingSupport

    • framingDecoder

      public abstract org.apache.pekko.stream.scaladsl.Flow<org.apache.pekko.util.ByteString,org.apache.pekko.util.ByteString,org.apache.pekko.NotUsed> framingDecoder()
      Read-side, decode incoming framed entity. For example with an incoming JSON array, chunk it up into JSON objects contained within that array.
      Returns:
      (undocumented)

    • getFramingDecoder

      public final org.apache.pekko.stream.javadsl.Flow<org.apache.pekko.util.ByteString,org.apache.pekko.util.ByteString,org.apache.pekko.NotUsed> getFramingDecoder()
      Description copied from class: EntityStreamingSupport
      Read-side, decode incoming framed entity. For example with an incoming JSON array, chunk it up into JSON objects contained within that array.
      Specified by:
      getFramingDecoder in class EntityStreamingSupport
      Returns:
      (undocumented)

    • framingRenderer

      public abstract org.apache.pekko.stream.scaladsl.Flow<org.apache.pekko.util.ByteString,org.apache.pekko.util.ByteString,org.apache.pekko.NotUsed> framingRenderer()
      Write-side, apply framing to outgoing entity stream.

      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")).

      Returns:
      (undocumented)

    • getFramingRenderer

      public final org.apache.pekko.stream.javadsl.Flow<org.apache.pekko.util.ByteString,org.apache.pekko.util.ByteString,org.apache.pekko.NotUsed> getFramingRenderer()
      Description copied from class: EntityStreamingSupport
      Write-side, apply framing to outgoing entity stream.

      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")).

      Specified by:
      getFramingRenderer in class EntityStreamingSupport
      Returns:
      (undocumented)

    • withSupported

      public abstract EntityStreamingSupport withSupported(ContentTypeRange range)
      Read-side, allows changing what content types are accepted by this framing.

      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!

      Specified by:
      withSupported in class EntityStreamingSupport
      Parameters:
      range - (undocumented)
      Returns:
      (undocumented)

    • withContentType

      public abstract EntityStreamingSupport withContentType(ContentType range)
      Write-side, defines what Content-Type the Marshaller should offer and the final Content-Type of the response.

      EntityStreamingSupport traits MUST support re-configuring the offered ContentType. This is due to the need integrating with existing systems which sometimes expect 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!

      Specified by:
      withContentType in class EntityStreamingSupport
      Parameters:
      range - (undocumented)
      Returns:
      (undocumented)

    • parallelism

      public abstract int parallelism()
      Write-side / read-side, defines if (un)marshalling should be done in parallel.

      This may be beneficial marshalling the bottleneck in the pipeline.

      See also parallelism() and withParallelMarshalling(int,boolean).

      Specified by:
      parallelism in class EntityStreamingSupport
      Returns:
      (undocumented)

    • unordered

      public abstract boolean unordered()
      Write-side / read-side, defines if (un)marshalling should preserve ordering of incoming stream elements.

      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(int,boolean).

      Specified by:
      unordered in class EntityStreamingSupport
      Returns:
      (undocumented)

    • withParallelMarshalling

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

      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!

      Specified by:
      withParallelMarshalling in class EntityStreamingSupport
      Parameters:
      parallelism - (undocumented)
      unordered - (undocumented)
      Returns:
      (undocumented)