PushBuilder (Jakarta EE 8 Specification API)

```
public interface PushBuilder
```
プッシュするリクエストを作成します。RFC 7540 のセクション 8.2 によると、約束されたリクエストはリクエストボディなしでキャッシュ可能で安全でなければなりません。
PushBuilder は、HttpServletRequest.newPushBuilder() を呼び出すことによって取得されます。このメソッドを呼び出すたびに、現在の HttpServletRequest または null に基づいて PushBuilder の新しいインスタンスが生成されます。返された PushBuilder への変更は、将来のリターンには反映されません。
インスタンスは次のように初期化されます。
- メソッドは "GET" に初期化されます
- 以下を除いて、現在の HttpServletRequest の既存のリクエストヘッダーがビルダーに追加されます。
  - 条件付きヘッダー (RFC 7232 で定義)
  - 範囲ヘッダー
  - ヘッダーを期待する
  - 認可ヘッダー
  - リファラーヘッダー
- リクエストが認証された場合は、認可ヘッダーにコンテナー生成トークンが設定され、プッシュされたリクエストと同等の認可が得られます。
- PushBuilder を作成する呼び出しの前に HttpServletRequest.getSession(boolean) が以前に呼び出されて新しい HttpSession を作成していない限り、セッション ID は HttpServletRequest.getRequestedSessionId() から返される値になります。この場合、新しいセッション ID は PushBuilder のリクエストされたセッション ID として使用されます。リクエストから返されるセッション ID は、Cookie または URL（それぞれ HttpServletRequest.isRequestedSessionIdFromCookie() および HttpServletRequest.isRequestedSessionIdFromURL() で指定されている）の 2 つの「ソース」のいずれかから効果的に取得できることに注意してください。PushBuilder のセッション ID も、リクエストと同じソースから取得されます。
- Referer（sic）ヘッダーは、HttpServletRequest.getRequestURL() と任意の HttpServletRequest.getQueryString() に設定されます
- 関連するレスポンスで HttpServletResponse.addCookie(Cookie) が呼び出された場合、Cookie.getMaxAge() が <= 0 でない限り、対応する Cookie ヘッダーが PushBuilder に追加されます。この場合、Cookie はビルダーから削除されます。
push() を呼び出す前に、PushBuilder インスタンスで path(java.lang.String) メソッドを呼び出す必要があります。そうしないと、そのメソッドで指定されているように、push() から例外がスローされる必要があります。
PushBuilder は、push() メソッドが呼び出されてビルダーの現在の状態で非同期プッシュリクエストを開始する前に、ミューテーターメソッドのチェーン呼び出しによってカスタマイズできます。push() の呼び出し後、ビルダーは別のプッシュに再利用できますが、実装は path(String) および条件付きヘッダー（RFC 7232 で定義）の値が push() から戻る前にクリアされるようにする必要があります。他のすべての値は、push() の呼び出しを介して保持されます。
導入:
Servlet 4.0

メソッドのサマリー

すべてのメソッドインスタンスメソッド抽象メソッド
修飾子と型	メソッドと説明
`PushBuilder`	`addHeader(StringSE name, StringSE value)` プッシュに使用するリクエストヘッダーを追加します。
`StringSE`	`getHeader(StringSE name)` プッシュに使用される指定された名前のヘッダーを返します。
`SetSE<StringSE>`	`getHeaderNames()` プッシュに使用されるヘッダーのセットを返します。
`StringSE`	`getMethod()` プッシュに使用するメソッドを返します。
`StringSE`	`getPath()` プッシュに使用する URI パスを返します。
`StringSE`	`getQueryString()` プッシュに使用するクエリ文字列を返します。
`StringSE`	`getSessionId()` プッシュに使用する SessionID を返します。
`PushBuilder`	`method(StringSE method)` プッシュに使用するメソッドを設定します。
`PushBuilder`	`path(StringSE path)` プッシュに使用する URI パスを設定します。
`void`	`push()` ビルダーの現在の状態を指定してリソースをプッシュします。メソッドはノンブロッキングでなければなりません。
`PushBuilder`	`queryString(StringSE queryString)` プッシュに使用するクエリ文字列を設定します。
`PushBuilder`	`removeHeader(StringSE name)` 名前付きリクエストヘッダーを削除します。
`PushBuilder`	`sessionId(StringSE sessionId)` プッシュに使用する SessionID を設定します。
`PushBuilder`	`setHeader(StringSE name, StringSE value)` プッシュに使用するリクエストヘッダーを設定します。

- メソッドの詳細
  - method
```
PushBuilder method(StringSE method)
```
    プッシュに使用するメソッドを設定します。
    パラメーター:
    method - プッシュに使用されるメソッド。
    戻り値:
    このビルダー。
    例外:
    NullPointerExceptionSE - 引数が null の場合
    IllegalArgumentExceptionSE - 引数が空の文字列、または RFC 7231 で定義されているキャッシュ不可または安全でないメソッド（POST、PUT、DELETE、CONNECT、OPTIONS、TRACE）の場合。
  - queryString
```
PushBuilder queryString(StringSE queryString)
```
    プッシュに使用するクエリ文字列を設定します。クエリ文字列は、path(String) の呼び出しに含まれるクエリ文字列に追加されます。重複するパラメーターは保持する必要があります。同じクエリ文字列を使用して複数の push() 呼び出しを行う場合、path(String) でクエリの代わりにこのメソッドを使用する必要があります。
    パラメーター:
    queryString - プッシュに使用されるクエリ文字列。
    戻り値:
    このビルダー。
  - sessionId
```
PushBuilder sessionId(StringSE sessionId)
```
    プッシュに使用する SessionID を設定します。セッション ID は、関連付けられたリクエストと同じ方法で設定されます（つまり、関連付けられたリクエストが cookie を使用した場合は cookie として、または関連付けられたリクエストが url パラメーターを使用した場合は url パラメーターとして）。デフォルトは、リクエストされたセッション ID、または新しく作成されたセッションから新しく割り当てられたセッション ID です。
    パラメーター:
    sessionId - プッシュに使用される SessionID。
    戻り値:
    このビルダー。
  - setHeader
```
PushBuilder setHeader(StringSE name,
                      StringSE value)
```
    プッシュに使用するリクエストヘッダーを設定します。ビルダーに同じ名前の既存のヘッダーがある場合、その値は上書きされます。
    パラメーター:
    name - 設定するヘッダー名
    value - 設定するヘッダー値
    戻り値:
    このビルダー。
  - addHeader
```
PushBuilder addHeader(StringSE name,
                      StringSE value)
```
    プッシュに使用するリクエストヘッダーを追加します。
    パラメーター:
    name - 追加するヘッダー名
    value - 追加するヘッダー値
    戻り値:
    このビルダー。
  - removeHeader
```
PushBuilder removeHeader(StringSE name)
```
    名前付きリクエストヘッダーを削除します。ヘッダーが存在しない場合は、何もしないでください。
    パラメーター:
    name - 削除するヘッダーの名前
    戻り値:
    このビルダー。
  - path
```
PushBuilder path(StringSE path)
```
    プッシュに使用する URI パスを設定します。パスは "/" で始まる場合があり、その場合は絶対パスとして扱われます。それ以外の場合は、関連するリクエストのコンテキストパスからの相対パスです。デフォルトのパスはなく、push() を呼び出す前に path(String) を呼び出す必要があります。引数 path にクエリ文字列が存在する場合、その内容は、以前に queryString(java.lang.String) に渡された内容とマージして、重複を保持する必要があります。
    パラメーター:
    path - プッシュに使用する URI パス。クエリ文字列を含めることができます。
    戻り値:
    このビルダー。
  - push
```
void push()
```
    ビルダーの現在の状態を指定してリソースをプッシュします。メソッドはノンブロッキングでなければなりません。
    PushBuilder の現在の状態に基づいてリソースをプッシュします。クライアントが基になる HTTP/2 プロトコルを使用して、プッシュされたリソースの受け入れを拒否する可能性があるため、このメソッドを呼び出しても、リソースが実際にプッシュされることは保証されません。
    ビルダーにセッション ID がある場合、プッシュされたリクエストには、必要に応じて Cookie または URI パラメーターとしてセッション ID が含まれます。Builder のクエリ文字列は、渡されたクエリ文字列とマージされます。
    このメソッドから戻る前に、ビルダーのパス、条件付きヘッダー（RFC 7232 で定義）は null になっています。他のすべてのフィールドは、別のプッシュで再利用できるようにそのまま残されます。
    例外:
    IllegalStateExceptionSE - このインスタンスで、インスタンス化から、IllegalStateException をスローしなかった push() への最後の呼び出しの間に、path(java.lang.String) への呼び出しがなかった場合。
  - getMethod
```
StringSE getMethod()
```
    プッシュに使用するメソッドを返します。
    戻り値:
    プッシュに使用されるメソッド。
  - getQueryString
```
StringSE getQueryString()
```
    プッシュに使用するクエリ文字列を返します。
    戻り値:
    プッシュに使用されるクエリ文字列。
  - getSessionId
```
StringSE getSessionId()
```
    プッシュに使用する SessionID を返します。
    戻り値:
    プッシュに使用される SessionID。
  - getHeaderNames
```
SetSE<StringSE> getHeaderNames()
```
    プッシュに使用されるヘッダーのセットを返します。
    返されたセットは PushBuilder オブジェクトによって支援されないため、返されたセットの変更は PushBuilder オブジェクトに反映されず、その逆も同様です。
    戻り値:
    プッシュに使用されるヘッダーのセット。
  - getHeader
```
StringSE getHeader(StringSE name)
```
    プッシュに使用される指定された名前のヘッダーを返します。
    パラメーター:
    name - ヘッダーの名前
    戻り値:
    プッシュに使用される特定の名前のヘッダー。
  - getPath
```
StringSE getPath()
```
    プッシュに使用する URI パスを返します。
    戻り値:
    プッシュに使用される URI パス。

インターフェース PushBuilder

メソッドのサマリー

メソッドの詳細

method

queryString

sessionId

setHeader

addHeader

removeHeader

path

push

getMethod

getQueryString

getSessionId

getHeaderNames

getHeader

getPath