Jakarta EE 11.0.0 · jakarta.servlet.http.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 current HttpServletRequest, 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(), 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.
The Referer(sic) header will be set to HttpServletRequest#getRequestURL() plus any HttpServletRequest#getQueryString()
If 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 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().

Method Summary

Modifier and Type	Method and Description
public PushBuilder	Returns: this builder. addHeader(String The header name to add name, String The header value to add value) References Deprecated `PushBuilder` is deprecated or references (maybe indirectly) at least one deprecated element. Add a request header to be used for the push.
public String	Returns: the header of the given name to be used for the push. getHeader(String the name of the header name) Return the header of the given name to be used for the push.
public Set<String>	Returns: the set of header to be used for the push. getHeaderNames() Return the set of header to be used for the push.
public String	Returns: the method to be used for the push. getMethod() Return the method to be used for the push.
public String	Returns: the URI path to be used for the push. getPath() Return the URI path to be used for the push.
public String	Returns: the query string to be used for the push. getQueryString() Return the query string to be used for the push.
public String	Returns: the SessionID to be used for the push. getSessionId() Return the SessionID to be used for the push.
public PushBuilder	Returns: this builder. method(String the method to be used for the push. method) References Deprecated `PushBuilder` is deprecated or references (maybe indirectly) at least one deprecated element. Set the method to be used for the push.
public PushBuilder	Returns: this builder. path(String the URI path to be used for the push, which may include a query string. path) References Deprecated `PushBuilder` is deprecated or references (maybe indirectly) at least one deprecated element. Set the URI path to be used for the push.
public void	push() Push a resource given the current state of the builder, the method must be non-blocking.
public PushBuilder	Returns: this builder. queryString(String the query string to be used for the push. queryString) References Deprecated `PushBuilder` is deprecated or references (maybe indirectly) at least one deprecated element. Set the query string to be used for the push.
public PushBuilder	Returns: this builder. removeHeader(String The name of the header to remove name) References Deprecated `PushBuilder` is deprecated or references (maybe indirectly) at least one deprecated element. Remove the named request header.
public PushBuilder	Returns: this builder. sessionId(String the SessionID to be used for the push. sessionId) References Deprecated `PushBuilder` is deprecated or references (maybe indirectly) at least one deprecated element. Set the SessionID to be used for the push.
public PushBuilder	Returns: this builder. setHeader(String The header name to set name, String The header value to set value) References Deprecated `PushBuilder` is deprecated or references (maybe indirectly) at least one deprecated element. Set a request header to be used for the push.

Method Detail

addHeader back to summary

addHeader	back to summary
public PushBuilder addHeader(String name, String value) References Deprecated `PushBuilder` is deprecated or references (maybe indirectly) at least one deprecated element. See corresponding docs for further information. Add a request header to be used for the push. Parameters name:String The header name to add value:String The header value to add Returns:PushBuilder this builder.

public PushBuilder addHeader(String name, String value)

References Deprecated

PushBuilder is deprecated or references (maybe indirectly) at least one deprecated element.

See corresponding docs for further information.

Add a request header to be used for the push.

Parameters

name:String: The header name to add
value:String: The header value to add

Returns:PushBuilder

this builder.

getHeader	back to summary
public String getHeader(String name) Return the header of the given name to be used for the push. Parameters name:String the name of the header Returns:String the header of the given name to be used for the push.

getHeader

back to summary

public String getHeader(String name)

Return the header of the given name to be used for the push.

Parameters

name:String: the name of the header

Returns:String

the header of the given name to be used for the push.

getHeaderNames back to summary

getHeaderNames	back to summary
public 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 the `PushBuilder` object, and vice-versa. Returns:Set<String> the set of header to be used for the push.

public 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 the PushBuilder object, and vice-versa.

Returns:Set<String>: the set of header to be used for the push.

getMethod	back to summary
public String getMethod() Return the method to be used for the push. Returns:String the method to be used for the push.

getMethod

back to summary

public String getMethod()

Return the method to be used for the push.

Returns:String: the method to be used for the push.

getPath	back to summary
public String getPath() Return the URI path to be used for the push. Returns:String the URI path to be used for the push.

getPath

back to summary

public String getPath()

Return the URI path to be used for the push.

Returns:String: the URI path to be used for the push.

getQueryString	back to summary
public String getQueryString() Return the query string to be used for the push. Returns:String the query string to be used for the push.

getQueryString

back to summary

public String getQueryString()

Return the query string to be used for the push.

Returns:String: the query string to be used for the push.

getSessionId	back to summary
public String getSessionId() Return the SessionID to be used for the push. Returns:String the SessionID to be used for the push.

getSessionId

back to summary

public String getSessionId()

Return the SessionID to be used for the push.

Returns:String: the SessionID to be used for the push.

method back to summary

method	back to summary
public PushBuilder method(String method) References Deprecated `PushBuilder` is deprecated or references (maybe indirectly) at least one deprecated element. See corresponding docs for further information. Set the method to be used for the push. Parameters method:String the method to be used for the push. Returns:PushBuilder this builder. Exceptions 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.

public PushBuilder method(String method)

References Deprecated

PushBuilder is deprecated or references (maybe indirectly) at least one deprecated element.

See corresponding docs for further information.

Set the method to be used for the push.

Parameters

method:String: the method to be used for the push.

Returns:PushBuilder

this builder.

Exceptions

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.

path back to summary

path	back to summary
public PushBuilder path(String path) References Deprecated `PushBuilder` is deprecated or references (maybe indirectly) at least one deprecated element. See corresponding docs for further information. 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 and `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`, preserving duplicates. Parameters path:String the URI path to be used for the push, which may include a query string. Returns:PushBuilder this builder.

public PushBuilder path(String path)

References Deprecated

PushBuilder is deprecated or references (maybe indirectly) at least one deprecated element.

See corresponding docs for further information.

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 and 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, preserving duplicates.

Parameters

path:String: the URI path to be used for the push, which may include a query string.

Returns:PushBuilder

this builder.

push back to summary

push	back to summary
public 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. Exceptions IllegalStateException: if there was no call to `path` on this instance either between its instantiation or the last call to `push()` that did not throw an IllegalStateException.

public 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.

Exceptions

IllegalStateException:: if there was no call to path on this instance either between its instantiation or the last call to push() that did not throw an IllegalStateException.

queryString back to summary

queryString	back to summary
public PushBuilder queryString(String queryString) References Deprecated `PushBuilder` is deprecated or references (maybe indirectly) at least one deprecated element. See corresponding docs for further information. Set the query string to be used for the push. The query string will be appended to any query String included in a call to `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. Parameters queryString:String the query string to be used for the push. Returns:PushBuilder this builder.

public PushBuilder queryString(String queryString)

References Deprecated

PushBuilder is deprecated or references (maybe indirectly) at least one deprecated element.

See corresponding docs for further information.

Set the query string to be used for the push. The query string will be appended to any query String included in a call to 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.

Parameters

queryString:String: the query string to be used for the push.

Returns:PushBuilder

this builder.

removeHeader back to summary

removeHeader	back to summary
public PushBuilder removeHeader(String name) References Deprecated `PushBuilder` is deprecated or references (maybe indirectly) at least one deprecated element. See corresponding docs for further information. Remove the named request header. If the header does not exist, take no action. Parameters name:String The name of the header to remove Returns:PushBuilder this builder.

public PushBuilder removeHeader(String name)

References Deprecated

PushBuilder is deprecated or references (maybe indirectly) at least one deprecated element.

See corresponding docs for further information.

Remove the named request header. If the header does not exist, take no action.

Parameters

name:String: The name of the header to remove

Returns:PushBuilder

this builder.

sessionId back to summary

sessionId	back to summary
public PushBuilder sessionId(String sessionId) References Deprecated `PushBuilder` is deprecated or references (maybe indirectly) at least one deprecated element. See corresponding docs for further information. 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:String the SessionID to be used for the push. Returns:PushBuilder this builder.

public PushBuilder sessionId(String sessionId)

References Deprecated

PushBuilder is deprecated or references (maybe indirectly) at least one deprecated element.

See corresponding docs for further information.

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:String: the SessionID to be used for the push.

Returns:PushBuilder

this builder.

setHeader back to summary

setHeader	back to summary
public PushBuilder setHeader(String name, String value) References Deprecated `PushBuilder` is deprecated or references (maybe indirectly) at least one deprecated element. See corresponding docs for further information. 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:String The header name to set value:String The header value to set Returns:PushBuilder this builder.

public PushBuilder setHeader(String name, String value)

References Deprecated

PushBuilder is deprecated or references (maybe indirectly) at least one deprecated element.

See corresponding docs for further information.

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:String: The header name to set
value:String: The header value to set

Returns:PushBuilder

this builder.

public Interface PushBuilder

Method Summary

Method Detail