Package org.eclipse.jetty.server

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 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 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 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 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:

4.0

Method Summary

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 is null

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 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(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 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(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 set

value - 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 add

value - 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 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(java.lang.String etag)

Deprecated.

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(java.lang.String lastModified)

Deprecated.

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()

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 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

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.