PushBuilder (Servlet 4.0 API Documentation

```
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().
- If either of the headers If-Modified-Since or If-None-Match were present then isConditional() will be set to true.
Since:

Servlet 4.0

Method Summary

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

- Method Detail
  - method
```
PushBuilder method(java.lang.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
  - queryString
```
PushBuilder queryString(java.lang.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(java.lang.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
  - conditional
```
PushBuilder conditional(boolean conditional)
```
    Sets if the request will be conditional. If true the values from getEtag() and getLastModified() will be used to construct appropriate headers.
    
    Parameters:
    
    conditional - Should generated push requests be conditional
    
    Returns:
    
    This builder instance
  - setHeader
```
PushBuilder setHeader(java.lang.String name,
                      java.lang.String value)
```
    Sets a 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(java.lang.String name,
                      java.lang.String value)
```
    Adds a 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(java.lang.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(java.lang.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
  - etag
```
PushBuilder etag(java.lang.String etag)
```
    Sets the etag to be used for conditional push requests. This will be set to null after a call to push() so it must be explicitly set for every push request that requires it.
    
    Parameters:
    
    etag - The etag use for the push request
    
    Returns:
    
    This builder instance
  - lastModified
```
PushBuilder lastModified(java.lang.String lastModified)
```
    Sets the last modified to be used for conditional push requests. This will be set to null after a call to push() so it must be explicitly set for every push request that requires it.
    
    Parameters:
    
    lastModified - The last modified value to use for the push request
    
    Returns:
    
    This builder instance
  - push
```
boolean 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
    - etag
    - lastModified
    Returns:
    
    true if the push request was sent to the client, otherwise false
    
    Throws:
    
    java.lang.IllegalStateException - If this method is called when path is null
    
    java.lang.IllegalArgumentException - If the request to push requires a body
  - getMethod
```
java.lang.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
```
java.lang.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
```
java.lang.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.
  - isConditional
```
boolean isConditional()
```
    Will push requests generated by future calls to push() be conditional.
    
    Returns:
    
    true if push requests will be conditional
  - getHeaderNames
```
java.util.Set<java.lang.String> getHeaderNames()
```
    Returns:
    
    The current set of names of HTTP headers to be used the next time push() is called.
  - getHeader
```
java.lang.String getHeader(java.lang.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
```
java.lang.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
  - getEtag
```
java.lang.String getEtag()
```
    Obtain the etag that will be used for the push request that will be generated by the next call to push().
    
    Returns:
    
    The etag value that will be associated with the next push request
  - getLastModified
```
java.lang.String getLastModified()
```
    Obtain the last modified that will be used for the push request that will be generated by the next call to push().
    
    Returns:
    
    The last modified value that will be associated with the next push request

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