インターフェース PushBuilder
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 パス。