Interface PushBuilder
-
- All Known Implementing Classes:
PushBuilderImpl
@Deprecated(since="2021-05-27") public interface PushBuilder
Deprecated.The Eclipse Jetty and Apache Felix Http Jetty packages are no longer supported.Build a request to be pushed.A PushBuilder is obtained by calling
Request.getPushBuilder()
(Eventually HttpServletRequest.getPushBuilder()
). Each call to this method will return a new instance of a PushBuilder based off the currentHttpServletRequest
. 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 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 callHttpServletRequest.getSession(boolean)
has previously been called to create a newHttpSession
, 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 anyHttpServletRequest.getQueryString()
- If
HttpServletResponse.addCookie(Cookie)
has been called on the associated response, then a corresponding Cookie header will be added to the PushBuilder, unless theCookie.getMaxAge()
is <=0, in which case the Cookie will be removed from the builder. - If this request has has the conditional headers If-Modified-Since
or If-None-Match, then the
isConditional()
header is set to true.
The
path(java.lang.String)
method must be called on thePushBuilder
instance before the call topush()
. Failure to do so must cause an exception to be thrown frompush()
, 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 topush()
, the builder may be reused for another push, however the implementation must make it so thepath(String)
,etag(String)
andlastModified(String)
values are cleared before returning frompush()
. All other values are retained over calls topush()
.- Since:
- 4.0
-
-
Method Summary
All Methods Instance Methods Abstract Methods Deprecated Methods Modifier and Type Method Description PushBuilder
addHeader(java.lang.String name, java.lang.String value)
Deprecated.Add a header to be used for the push.PushBuilder
conditional(boolean conditional)
Deprecated.Set if the request is to be conditional.PushBuilder
etag(java.lang.String etag)
Deprecated.Set the etag to be used for conditional pushes.java.lang.String
getEtag()
Deprecated.java.lang.String
getHeader(java.lang.String name)
Deprecated.java.util.Set<java.lang.String>
getHeaderNames()
Deprecated.java.lang.String
getLastModified()
Deprecated.java.lang.String
getMethod()
Deprecated.java.lang.String
getPath()
Deprecated.java.lang.String
getQueryString()
Deprecated.java.lang.String
getSessionId()
Deprecated.boolean
isConditional()
Deprecated.PushBuilder
lastModified(java.lang.String lastModified)
Deprecated.Set the last modified date to be used for conditional pushes.PushBuilder
method(java.lang.String method)
Deprecated.Set the method to be used for the push.PushBuilder
path(java.lang.String path)
Deprecated.Set the URI path to be used for the push.void
push()
Deprecated.Push a resource given the current state of the builder, returning immediately without blocking.PushBuilder
queryString(java.lang.String queryString)
Deprecated.Set the query string to be used for the push.PushBuilder
removeHeader(java.lang.String name)
Deprecated.Remove the named header.PushBuilder
sessionId(java.lang.String sessionId)
Deprecated.Set the SessionID to be used for the push.PushBuilder
setHeader(java.lang.String name, java.lang.String value)
Deprecated.Set a header to be used for the push.
-
-
-
Method Detail
-
method
PushBuilder method(java.lang.String method)
Deprecated.Set the method to be used for the push.
Any non-empty String may be used for the method.
- Parameters:
method
- the method to be used for the push.- Returns:
- this builder.
- Throws:
java.lang.NullPointerException
- if the argument isnull
java.lang.IllegalArgumentException
- if the argument is the empty String
-
queryString
PushBuilder queryString(java.lang.String queryString)
Deprecated.Set the query string to be used for the push. Will be appended to any query String included in a call topath(String)
. Any duplicate parameters must be preserved. This method should be used instead of a query inpath(String)
when multiplepush()
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(java.lang.String sessionId)
Deprecated.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)
Deprecated.Set if the request is to be conditional. If the request is conditional, any available values frometag(String)
orlastModified(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(java.lang.String name, java.lang.String value)
Deprecated.Set a 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 setvalue
- The header value to set- Returns:
- this builder.
-
addHeader
PushBuilder addHeader(java.lang.String name, java.lang.String value)
Deprecated.Add a header to be used for the push.
- Parameters:
name
- The header name to addvalue
- The header value to add- Returns:
- this builder.
-
removeHeader
PushBuilder removeHeader(java.lang.String name)
Deprecated.Remove the named 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(java.lang.String path)
Deprecated.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 andpath(String)
must be called before every call topush()
. If a query string is present in the argumentpath
, its contents must be merged with the contents previously passed toqueryString(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(java.lang.String etag)
Deprecated.Set the etag to be used for conditional pushes. The etag will be used only ifisConditional()
is true. Defaults to no etag. The value is nulled after every call topush()
- Parameters:
etag
- the etag to be used for the push.- Returns:
- this builder.
-
lastModified
PushBuilder lastModified(java.lang.String lastModified)
Deprecated.Set the last modified date to be used for conditional pushes. The last modified date will be used only ifisConditional()
is true. Defaults to no date. The value is nulled after every call topush()
- Parameters:
lastModified
- the last modified date to be used for the push.- Returns:
- this builder.
-
push
void push()
Deprecated.Push a resource given the current state of the builder, returning immediately without blocking.Push a resource based on the current state of the PushBuilder. 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:
java.lang.IllegalArgumentException
- if the method set expects a request body (eg POST)java.lang.IllegalStateException
- if there was no call topath(java.lang.String)
on this instance either between its instantiation or the last call topush()
that did not throw an IllegalStateException.
-
getMethod
java.lang.String getMethod()
Deprecated.
-
getQueryString
java.lang.String getQueryString()
Deprecated.
-
getSessionId
java.lang.String getSessionId()
Deprecated.
-
isConditional
boolean isConditional()
Deprecated.
-
getHeaderNames
java.util.Set<java.lang.String> getHeaderNames()
Deprecated.
-
getHeader
java.lang.String getHeader(java.lang.String name)
Deprecated.
-
getPath
java.lang.String getPath()
Deprecated.
-
getEtag
java.lang.String getEtag()
Deprecated.
-
getLastModified
java.lang.String getLastModified()
Deprecated.
-
-