Package jakarta.servlet.http
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 fromHttpServletRequest.getQueryString()
.
- Since:
- Servlet 4.0
-
Method Summary
Modifier and TypeMethodDescriptionAdds an HTTP header to the request.Obtain a value for the given HTTP header.Obtain the name of the HTTP method that will be used for push requests generated by future calls topush()
.getPath()
Obtain the path that will be used for the push request that will be generated by the next call topush()
.Obtain the query string that will be used for push requests generated by future calls topush()
.Obtain the session ID that will be used for push requests generated by future calls topush()
.Specify the HTTP method to use for the push request.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.queryString
(String queryString) Specifies the query string to use in subsequent push requests generated by a call topush()
.removeHeader
(String name) Removes an HTTP header from the request.Specifies the session ID to use in subsequent push requests generated by a call topush()
.Sets an HTTP header on the request.
-
Method Details
-
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
Specifies the query string to use in subsequent push requests generated by a call topush()
. This will be appended to any query string specified in the call topath(String)
.- Parameters:
queryString
- The query string to use to generate push requests- Returns:
- This builder instance
-
sessionId
Specifies the session ID to use in subsequent push requests generated by a call topush()
. 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
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 setvalue
- The value of the header to set- Returns:
- This builder instance
-
addHeader
Adds an HTTP header to the request.- Parameters:
name
- The name of the header to addvalue
- The value of the header to add- Returns:
- This builder instance
-
removeHeader
Removes an HTTP header from the request.- Parameters:
name
- The name of the header to remove- Returns:
- This builder instance
-
path
Sets the URI path to be used for the push request. This must be called before every call topush()
. 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 tonull
:path
- conditional request headers (
if-none-match
andif-modified-since
)
- Throws:
IllegalStateException
- If this method is called whenpath
isnull
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 topush()
.- 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 topush()
.- 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 topush()
.- Returns:
- The session that will be used for push requests.
-
getHeaderNames
-
getHeader
-
getPath
String getPath()Obtain the path that will be used for the push request that will be generated by the next call topush()
.- Returns:
- The path value that will be associated with the next push request
-