Interface PushBuilder
-
public interface PushBuilder
Build a request to be pushed. According section 8.2 of RFC 7540, a promised request must be cacheable and safe without a request body.A PushBuilder is obtained by calling
HttpServletRequest.newPushBuilder()
. Each call to this method will a new instance of a PushBuilder based off the currentHttpServletRequest
, or null. Any mutations to the returned PushBuilder are not reflected on future returns.The instance is initialized as follows:
- The method is initialized to "GET"
- The existing request headers of the current
HttpServletRequest
are added to the builder, except for:- Conditional headers (defined in RFC 7232)
- Range headers
- Expect headers
- Authorization headers
- Referrer headers
- If the request was authenticated, an Authorization header will be set with a container generated token that will result in equivalent Authorization for the pushed request.
- The session ID will be the value returned from
HttpServletRequest.getRequestedSessionId()
, unlessHttpServletRequest.getSession(boolean)
has previously been called to create a newHttpSession
prior to the call to create thePushBuilder
, 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 inHttpServletRequest.isRequestedSessionIdFromCookie()
andHttpServletRequest.isRequestedSessionIdFromURL()
, respectively). The session ID for thePushBuilder
will also come from the same source as the request. - The Referer(sic) header will be set to
HttpServletRequest.getRequestURL()
plus anyHttpServletRequest.getQueryString()
- If
HttpServletResponse.addCookie(Cookie)
has been called on the associated response, then a corresponding Cookie header will be added to the PushBuilder, unless theCookie.getMaxAge()
is <=0, in which case the Cookie will be removed from the builder.
The
path(java.lang.String)
method must be called on thePushBuilder
instance before the call topush()
. Failure to do so must cause an exception to be thrown frompush()
, 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 topush()
, the builder may be reused for another push, however the implementation must make it so thepath(String)
and conditional headers (defined in RFC 7232) values are cleared before returning frompush()
. All other values are retained over calls topush()
.- Since:
- Servlet 4.0
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method 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.
-
-
-
Method Detail
-
method
PushBuilder method(String method)
Set the method to be used for the push.
- Parameters:
method
- the method to be used for the push.- Returns:
- this builder.
- Throws:
NullPointerException
- if the argument isnull
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.
-
queryString
PushBuilder queryString(String queryString)
Set the query string to be used for the push. The query string will be appended to any query String included in a call topath(String)
. Any duplicate parameters must be preserved. This method should be used instead of a query inpath(String)
when multiplepush()
calls are to be made with the same query string.- Parameters:
queryString
- the query string to be used for the push.- Returns:
- this builder.
-
sessionId
PushBuilder sessionId(String sessionId)
Set the SessionID to be used for the push. The session ID will be set in the same way it was on the associated request (ie as a cookie if the associated request used a cookie, or as a url parameter if the associated request used a url parameter). Defaults to the requested session ID or any newly assigned session id from a newly created session.- Parameters:
sessionId
- the SessionID to be used for the push.- Returns:
- this builder.
-
setHeader
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.
- Parameters:
name
- The header name to setvalue
- The header value to set- Returns:
- this builder.
-
addHeader
PushBuilder addHeader(String name, String value)
Add a request header to be used for the push.
- Parameters:
name
- The header name to addvalue
- The header value to add- Returns:
- this builder.
-
removeHeader
PushBuilder removeHeader(String name)
Remove the named request header. If the header does not exist, take no action.
- Parameters:
name
- The name of the header to remove- Returns:
- this builder.
-
path
PushBuilder path(String path)
Set the URI path to be used for the push. The path may start with "/" in which case it is treated as an absolute path, otherwise it is relative to the context path of the associated request. There is no path default andpath(String)
must be called before every call topush()
. If a query string is present in the argumentpath
, its contents must be merged with the contents previously passed toqueryString(java.lang.String)
, preserving duplicates.- Parameters:
path
- the URI path to be used for the push, which may include a query string.- Returns:
- this builder.
-
push
void push()
Push a resource given the current state of the builder, the method must be non-blocking.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.
- Throws:
IllegalStateException
- if there was no call topath(java.lang.String)
on this instance either between its instantiation or the last call topush()
that did not throw an IllegalStateException.
-
getMethod
String getMethod()
Return the method to be used for the push.- Returns:
- the method to be used for the push.
-
getQueryString
String getQueryString()
Return the query string to be used for the push.- Returns:
- the query string to be used for the push.
-
getSessionId
String getSessionId()
Return the SessionID to be used for the push.- Returns:
- the SessionID to be used for the push.
-
getHeaderNames
Set<String> getHeaderNames()
Return the set of header to be used for the push.The returned set is not backed by the
PushBuilder
object, so changes in the returned set are not reflected in thePushBuilder
object, and vice-versa.- Returns:
- the set of header to be used for the push.
-
getHeader
String getHeader(String name)
Return the header of the given name to be used for the push.- Parameters:
name
- the name of the header- Returns:
- the header of the given name to be used for the push.
-
getPath
String getPath()
Return the URI path to be used for the push.- Returns:
- the URI path to be used for the push.
-
-