PushBuilder (Servlet 4.0 API Documentation - Apache Tomcat 9.0.111)
Description: declaration: package: javax.servlet.http, interface: PushBuilder

# Interface PushBuilder

public interface PushBuilder
Builds a push request based on the `HttpServletRequest` from which this builder was obtained. The push request will be constructed on the following basis:

- The request method is set to `GET`.
- The path will not be set. This must be set explicitly via a call to `path(String)`.
- Conditional, range, expectation, authorization and referer headers will be removed.
- Cookies added to the associated response will be added to the push request unless maxAge <= 0 in which case any request cookie with the same name will be removed.
- The referer header will be set to `HttpServletRequest.getRequestURL()` plus, if present, the query string from `HttpServletRequest.getQueryString()`.

Since:
  Servlet 4.0

- ## Method Summary

  Modifier and Type
  Method
  Description
  `PushBuilder`
  `addHeader(String name, String value)`
  Adds an HTTP header to the request.
  `String`
  `getHeader(String name)`
  Obtain a value for the given HTTP header.
  `Set<String>`
  `getHeaderNames()`
  `String`
  `getMethod()`
  Obtain the name of the HTTP method that will be used for push requests generated by future calls to `push()`.
  `String`
  `getPath()`
  Obtain the path that will be used for the push request that will be generated by the next call to `push()`.
  `String`
  `getQueryString()`
  Obtain the query string that will be used for push requests generated by future calls to `push()`.
  `String`
  `getSessionId()`
  Obtain the session ID that will be used for push requests generated by future calls to `push()`.
  `PushBuilder`
  `method(String method)`
  Specify the HTTP method to use for the push request.
  `PushBuilder`
  `path(String path)`
  Sets the URI path to be used for the push request.
  `void`
  `push()`
  Generates the push request and sends it to the client unless pushes are not available for some reason.
  `PushBuilder`
  `queryString(String queryString)`
  Specifies the query string to use in subsequent push requests generated by a call to `push()`.
  `PushBuilder`
  `removeHeader(String name)`
  Removes an HTTP header from the request.
  `PushBuilder`
  `sessionId(String sessionId)`
  Specifies the session ID to use in subsequent push requests generated by a call to `push()`.
  `PushBuilder`
  `setHeader(String name, String value)`
  Sets an HTTP header on the request.

- ## Method Details

  - ### method

    PushBuilder method(String method)
    Specify the HTTP method to use for the push request.
    Parameters:
      `method` - The method to use for the push request
    Returns:
      This builder instance
    Throws:
      `IllegalArgumentException` - if an HTTP method is specified that is known not to be cacheable and safe. POST, PUT, DELETE, CONNECT, OPTIONS and TRACE will trigger the exception.

  - ### queryString

    PushBuilder queryString(String queryString)
    Specifies the query string to use in subsequent push requests generated by a call to `push()`. This will be appended to any query string specified in the call to `path(String)`.
    Parameters:
      `queryString` - The query string to use to generate push requests
    Returns:
      This builder instance

  - ### sessionId

    PushBuilder sessionId(String sessionId)
    Specifies the session ID to use in subsequent push requests generated by a call to `push()`. The session ID will be presented the same way as it is on the original request (cookie or URL parameter). The default is determined in the following order:
    - the requested session ID for the originating request
    - the session ID generated in the originated request
    - `null`
    Parameters:
      `sessionId` - The session ID to use to generate push requests
    Returns:
      This builder instance

  - ### setHeader

    PushBuilder setHeader(String name, String value)
    Sets an HTTP header on the request. Any existing headers of the same name are first remove.
    Parameters:
      `name` - The name of the header to set
      `value` - The value of the header to set
    Returns:
      This builder instance

  - ### addHeader

    PushBuilder addHeader(String name, String value)
    Adds an HTTP header to the request.
    Parameters:
      `name` - The name of the header to add
      `value` - The value of the header to add
    Returns:
      This builder instance

  - ### removeHeader

    PushBuilder removeHeader(String name)
    Removes an HTTP header from the request.
    Parameters:
      `name` - The name of the header to remove
    Returns:
      This builder instance

  - ### path

    PushBuilder path(String path)
    Sets the URI path to be used for the push request. This must be called before every call to `push()`. If the path includes a query string, the query string will be appended to the existing query string (if any) and no de-duplication will occur.
    Parameters:
      `path` - Paths beginning with '/' are treated as absolute paths. All other paths are treated as relative to the context path of the request used to create this builder instance. The path may include a query string.
    Returns:
      This builder instance

  - ### push

    void push()
    Generates the push request and sends it to the client unless pushes are not available for some reason. After calling this method the following fields are set to `null`:
    - `path`
    - conditional request headers (`if-none-match` and `if-modified-since`)
    Throws:
      `IllegalStateException` - If this method is called when `path` is `null`
      `IllegalArgumentException` - If the request to push requires a body

  - ### getMethod

    String getMethod()
    Obtain the name of the HTTP method that will be used for push requests generated by future calls to `push()`.
    Returns:
      The HTTP method to be used for future push requests

  - ### getQueryString

    String getQueryString()
    Obtain the query string that will be used for push requests generated by future calls to `push()`.
    Returns:
      The query string that will be appended to push requests.

  - ### getSessionId

    String getSessionId()
    Obtain the session ID that will be used for push requests generated by future calls to `push()`.
    Returns:
      The session that will be used for push requests.

  - ### getHeaderNames

    Set<String> getHeaderNames()
    Returns:
      The current set of names of HTTP headers to be used the next time `push()` is called.

  - ### getHeader

    String getHeader(String name)
    Obtain a value for the given HTTP header. TODO Servlet 4.0 Clarify the behaviour of this method
    Parameters:
      `name` - The name of the header whose value is to be returned
    Returns:
      The value of the given header. If multiple values are defined then any may be returned

  - ### getPath

    String getPath()
    Obtain the path that will be used for the push request that will be generated by the next call to `push()`.
    Returns:
      The path value that will be associated with the next push request