PushBuilder (Java Servlet 4.0)

```
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.getPushBuilder(). Each call to this method will return a new instance of a PushBuilder based off the current HttpServletRequest. 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 (eg. If-Modified-Since)
  - 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 HttpServletRequest.getRequestedSessionId() value, unless at the time of the call HttpServletRequest.getSession(boolean) has previously been called to create a new HttpSession, in which case the new session ID will be used as the PushBuilder's requested session ID. The source of the requested session id will be the same as for 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.
- If this request has either of the conditional headers "If-Modified-Since" or "If-None-Match", then isConditional() must return true.
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), eTag(String) and lastModified(String) values are cleared before returning from push(). All other values are retained over calls to push().
Since:

Servlet 4.0

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`PushBuilder`	`addHeader(String name, String value)` Add a request header to be used for the push.
`PushBuilder`	`conditional(boolean conditional)` Set if the request is to be conditional.
`PushBuilder`	`eTag(String eTag)` Set the eTag to be used for conditional pushes.
`String`	`getETag()` Return the eTag to be used for conditional pushes.
`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`	`getLastModified()` Return the last modified date to be used for conditional pushes.
`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.
`boolean`	`isConditional()` Return if the request is to be conditional.
`PushBuilder`	`lastModified(String lastModified)` Set the last modified date to be used for conditional pushes.
`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 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.
  - queryString
```
PushBuilder queryString(String queryString)
```
    Set the query string to be used for the push. 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 - 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.
  - conditional
```
PushBuilder conditional(boolean conditional)
```
    Set if the request is to be conditional. If the request is conditional, any available values from eTag(String) or lastModified(String) will be set in the appropriate headers. If the request is not conditional, then eTag and lastModified values are ignored. Defaults to true if the associated request was conditional.
    
    Parameters:
    
    conditional - true if the push request is conditional
    
    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 set
    
    value - 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 add
    
    value - 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 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(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.
  - eTag
```
PushBuilder eTag(String eTag)
```
    Set the eTag to be used for conditional pushes. The eTag will be used only if isConditional() is true. Defaults to no eTag. The value is nulled after every call to push()
    
    Parameters:
    
    eTag - the eTag to be used for the push.
    
    Returns:
    
    this builder.
  - lastModified
```
PushBuilder lastModified(String lastModified)
```
    Set the last modified date to be used for conditional pushes. The last modified date will be used only if isConditional() is true. Defaults to no date. The value is nulled after every call to push()
    
    Parameters:
    
    lastModified - the last modified date to be used for the push.
    
    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 isConditional() is true and an eTag or lastModified value is provided, then an appropriate conditional header will be generated. If both an eTag and lastModified value are provided only an If-None-Match header will be generated. 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, eTag and lastModified fields nulled. All other fields are left as is for possible reuse in another push.
    
    Throws:
    
    IllegalArgumentException - if the method set expects a request body (eg POST)
    
    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.
  - 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.
  - isConditional
```
boolean isConditional()
```
    Return if the request is to be conditional.
    
    Returns:
    
    if the request is to be conditional.
  - getHeaderNames
```
Set<String> getHeaderNames()
```
    Return the set of header to be used for the push.
    
    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.
    
    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.
  - getETag
```
String getETag()
```
    Return the eTag to be used for conditional pushes.
    
    Returns:
    
    the eTag to be used for conditional pushes.
  - getLastModified
```
String getLastModified()
```
    Return the last modified date to be used for conditional pushes.
    
    Returns:
    
    the last modified date to be used for conditional pushes.

Interface PushBuilder

Method Summary

Method Detail

method

queryString

sessionId

conditional

setHeader

addHeader

removeHeader

path

eTag

lastModified

push

getMethod

getQueryString

getSessionId

isConditional

getHeaderNames

getHeader

getPath

getETag

getLastModified