ドキュメント

§Play HTTP API の概要

§EssentialAction とは？

EssentialAction は、Play の HTTP API で使用される基盤となる関数型です。これは Java の Action 型とは異なり、Request を受け取り CompletionStage<Result> を返すより高レベルの型です。ほとんどの場合、Java アプリケーションで EssentialAction を直接使用する必要はありませんが、フィルタの作成や他の低レベル Play API との連携に役立つ場合があります。

EssentialAction を理解するには、Play のアーキテクチャを理解する必要があります。

Play のコアは非常に小さく、Web プログラミングのタスクを容易にするための多くの便利な API、サービス、構造によって囲まれています。

基本的に、Play のアクション API は抽象的に次の型を持ちます。

RequestHeader -> byte[] -> Result

上記は、リクエストヘッダー RequestHeader を受け取り、リクエストボディを byte[] として受け取り、Result を生成します。

この型は、値を計算するだけの場合でも、または Amazon S3 のようなストレージサービスに転送する場合でも、リクエストボディ全体をメモリ（またはディスク）に格納することを前提としています。

むしろ、リクエストボディのチャンクをストリームとして受け取り、必要に応じて段階的に処理できるようにしたいと考えています。

変更する必要があるのは、2 番目の矢印で、チャンクで入力を受け取り、最終的に結果を生成するようにします。これを行う型があり、それは Accumulator と呼ばれ、2 つの型パラメーターを取ります。

Accumulator<E,R> は、E 型のチャンクで入力を受け取り、最終的に R を返すアローの一種です。私たちの API では、ByteString のチャンク（基本的にバイト配列のより効率的なラッパー）を受け取り、最終的に Result を返す Accumulator が必要です。そのため、型をわずかに変更して

RequestHeader -> Accumulator<ByteString, Result>

最終的に、Java の型は次のようになります。

Function<RequestHeader, Accumulator<ByteString, Result>>

これは次のように解釈されます。リクエストヘッダーを受け取り、リクエストボディを表す ByteString のチャンクを受け取り、最終的に Result を返します。これは、EssentialAction の apply メソッドが定義されている方法とまったく同じです。

public abstract Accumulator<ByteString, Result> apply(RequestHeader requestHeader);

一方、Result 型は、レスポンスヘッダーとレスポンスのボディとして抽象的に考えることができます。

Result(ResponseHeader header, ByteString body)

しかし、レスポンスボディをメモリに完全に格納せずに、クライアントに段階的に送信したい場合はどうでしょうか？型を改善する必要があります。ボディの型を ByteString から ByteString のチャンクを生成するものに変更する必要があります。

すでにこのための型があり、Source<E, ?> と呼ばれ、E のチャンク、つまりこの場合は Source<ByteString, ?> を生成できることを意味します。

Result(ResponseHeader header, Source<ByteString, ?> body)

レスポンスを段階的に送信する必要がない場合でも、ボディ全体を単一のチャンクとして送信できます。実際の API では、Play はストリーミングされたエンティティ、チャンクされたエンティティ、厳密なエンティティをサポートする HttpEntity ラッパー型を使用して、さまざまなタイプのエンティティをサポートしています。

§結論

Play の基本的な HTTP API は非常にシンプルです。

RequestHeader -> Accumulator<ByteString, Result>

これは次のように解釈されます。RequestHeader を受け取り、ByteString のチャンクを受け取り、レスポンスを返します。レスポンスは、ResponseHeaders と、Source<E, ?> 型で表されるソケットに書き込まれる ByteString に変換可能な値のチャンクであるボディで構成されています。

次へ: HTTP フィルタ

このドキュメントに誤りを見つけましたか？このページのソースコードはこちらにあります。ドキュメントガイドラインを読んだ後、プルリクエストを自由に送ってください。ご質問やアドバイスがありましたら、コミュニティフォーラムにアクセスして、コミュニティとの会話を始めてください。