public interface PushBuilder
A PushBuilder is obtained by calling HttpServletRequest.newPushBuilder()
. Each call to this method will a new
instance of a PushBuilder based off the current HttpServletRequest
, or null. Any mutations to the returned PushBuilder are not reflected on future returns.
The instance is initialized as follows:
HttpServletRequest
are added to the builder, except for:
HttpServletRequest.getRequestedSessionId()
, unless
HttpServletRequest.getSession(boolean)
has previously been called to create a new HttpSession
prior
to the call to create the PushBuilder
, in which case the new session ID will be used as the PushBuilder's
requested session ID. Note that the session ID returned from the request can effectively come from one of two
"sources": a cookie or the URL (as specified in HttpServletRequest.isRequestedSessionIdFromCookie()
and
HttpServletRequest.isRequestedSessionIdFromURL()
, respectively). The session ID for the PushBuilder
will also come from the same source as the request.HttpServletRequest.getRequestURL()
plus any
HttpServletRequest.getQueryString()
HttpServletResponse.addCookie(Cookie)
has been called on the associated response, then a corresponding
Cookie header will be added to the PushBuilder, unless the Cookie.getMaxAge()
is <=0, in which case the
Cookie will be removed from the builder.
The path(java.lang.String)
method must be called on the PushBuilder
instance before the call to push()
. Failure
to do so must cause an exception to be thrown from push()
, as specified in that method.
A PushBuilder can be customized by chained calls to mutator methods before the push()
method is called to
initiate an asynchronous push request with the current state of the builder. After the call to push()
, the
builder may be reused for another push, however the implementation must make it so the path(String)
and
conditional headers (defined in RFC 7232) values are cleared before returning from push()
. All other values
are retained over calls to push()
.
Modifier and Type | Method and Description |
---|---|
PushBuilder |
addHeader(String name,
String value)
Add a request header to be used for the push.
|
String |
getHeader(String name)
Return the header of the given name to be used for the push.
|
Set<String> |
getHeaderNames()
Return the set of header to be used for the push.
|
String |
getMethod()
Return the method to be used for the push.
|
String |
getPath()
Return the URI path to be used for the push.
|
String |
getQueryString()
Return the query string to be used for the push.
|
String |
getSessionId()
Return the SessionID to be used for the push.
|
PushBuilder |
method(String method)
Set the method to be used for the push.
|
PushBuilder |
path(String path)
Set the URI path to be used for the push.
|
void |
push()
Push a resource given the current state of the builder, the method must be non-blocking.
|
PushBuilder |
queryString(String queryString)
Set the query string to be used for the push.
|
PushBuilder |
removeHeader(String name)
Remove the named request header.
|
PushBuilder |
sessionId(String sessionId)
Set the SessionID to be used for the push.
|
PushBuilder |
setHeader(String name,
String value)
Set a request header to be used for the push.
|
PushBuilder method(String method)
Set the method to be used for the push.
method
- the method to be used for the push.NullPointerException
- if the argument is null
IllegalArgumentException
- if the argument is the empty String, or any non-cacheable or unsafe methods
defined in RFC 7231, which are POST, PUT, DELETE, CONNECT, OPTIONS and TRACE.PushBuilder queryString(String queryString)
path(String)
. Any duplicate
parameters must be preserved. This method should be used instead of a query in path(String)
when
multiple push()
calls are to be made with the same query string.queryString
- the query string to be used for the push.PushBuilder sessionId(String sessionId)
sessionId
- the SessionID to be used for the push.PushBuilder setHeader(String name, String value)
Set a request header to be used for the push. If the builder has an existing header with the same name, its value is overwritten.
name
- The header name to setvalue
- The header value to setPushBuilder addHeader(String name, String value)
Add a request header to be used for the push.
name
- The header name to addvalue
- The header value to addPushBuilder removeHeader(String name)
Remove the named request header. If the header does not exist, take no action.
name
- The name of the header to removePushBuilder path(String path)
path(String)
must be called before every call to push()
. If a query string is present in the
argument path
, its contents must be merged with the contents previously passed to queryString(java.lang.String)
,
preserving duplicates.path
- the URI path to be used for the push, which may include a query string.void push()
Push a resource based on the current state of the PushBuilder. Calling this method does not guarantee the resource will actually be pushed, since it is possible the client can decline acceptance of the pushed resource using the underlying HTTP/2 protocol.
If the builder has a session ID, then the pushed request will include the session ID either as a Cookie or as a URI parameter as appropriate. The builders query string is merged with any passed query string.
Before returning from this method, the builder has its path, conditional headers (defined in RFC 7232) nulled. All other fields are left as is for possible reuse in another push.
IllegalStateException
- if there was no call to path(java.lang.String)
on this instance either between its
instantiation or the last call to push()
that did not throw an
IllegalStateException.String getMethod()
String getQueryString()
String getSessionId()
Set<String> getHeaderNames()
The returned set is not backed by the PushBuilder
object, so changes in the returned set are not
reflected in the PushBuilder
object, and vice-versa.
String getHeader(String name)
name
- the name of the headerString getPath()
Copyright © 2021 JBoss by Red Hat. All rights reserved.