Grizzly NIO 5.0.2 · org.glassfish.grizzly.http.server.http2.PushBuilder

Build a request to be pushed. This is based on Servlet 4.0's PushBuilder. According section 8.2 of RFC 7540, a promised request must be cacheable and safe without a request body.

A PushBuilder is obtained by calling Request#newPushBuilder(). 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 request headers of the current Request are added to the builder, except for:
- Conditional headers (eg. If-Modified-Since)
- Range headers
- Expect headers
- Authorization headers
- Referrer headers
The Request#getRequestedSessionId() value, unless at the time of the call Request#getSession(boolean) has previously been called to create a new Session, 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 Request#getRequestURL() plus any Request#getQueryString()
If Response#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.

The path 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 path and conditional headers are cleared before returning from push. All other values are retained over calls to push().

Field Summary

Modifier and Type	Field and Description
private static final Header[]	CONDITIONAL_HEADERS
pack-priv List<Cookie>	cookies
pack-priv MimeHeaders	headers
pack-priv String	method
pack-priv String	path
pack-priv String	queryString
private static final Header[]	REMOVE_HEADERS
pack-priv Request	request
pack-priv boolean	sessionFromURL
pack-priv String	sessionId

Constructor Summary

Access	Constructor and Description
public	PushBuilder(final Request request)

Method Summary

Modifier and Type	Method and Description
public PushBuilder	Returns: this builder. addHeader(String The header name to add name, String The header value to add value) Add a request header to be used for the push.
public PushBuilder	Returns: this builder. addHeader(Header The `Header` to add name, String The header value to add value) Add a request header to be used for the push.
private String	composeReferrerHeader(final Request request)
public String	Returns: the header of the given name to be used for the push. getHeader(String name) Return the header of the given name to be used for the push.
public Iterable<String>	Returns: the set of header to be used for the push. getHeaderNames() Return the set of header to be used for the push.
public String	Returns: the method to be used for the push. getMethod() Return the method to be used for the push.
public String	Returns: the URI path to be used for the push. getPath() Return the URI path to be used for the push.
public String	Returns: the query string to be used for the push. getQueryString() Return the query string to be used for the push.
public String	Returns: the SessionID to be used for the push. getSessionId() Return the SessionID to be used for the push.
public PushBuilder	Returns: this builder. method(final String the method to be used for the push. method) Set the method to be used for the push.
private static boolean	nameAndValueValid(final String name, final String value)
public PushBuilder	Returns: this builder. path(String the URI path to be used for the push, which may include a query string. path) Set the URI path to be used for the push.
public void	push() Push a resource given the current state of the builder without blocking.
public PushBuilder	Returns: this builder. queryString(String the query string to be used for the push. queryString) Set the query string to be used for the push.
public PushBuilder	Returns: this builder. removeHeader(String The name of the header to remove name) Remove the named request header.
public PushBuilder	Returns: this builder. removeHeader(Header The `Header` to remove name) Remove the named request header.
public PushBuilder	Returns: this builder. sessionId(String the SessionID to be used for the push. sessionId) Set the SessionID to be used for the push.
public PushBuilder	Returns: this builder. setHeader(String The header name to set name, String The header value to set value) Set a request header to be used for the push.
public PushBuilder	Returns: this builder. setHeader(Header The `Header` to set name, String The header value to set value) Set a request header to be used for the push.
private static String	validate(final String value)
private static boolean	validValue(final String value)

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

CONDITIONAL_HEADERS	back to summary
private static final Header[] CONDITIONAL_HEADERS

cookies	back to summary
pack-priv List<Cookie> cookies

headers	back to summary
pack-priv MimeHeaders headers

method	back to summary
pack-priv String method

path	back to summary
pack-priv String path

queryString	back to summary
pack-priv String queryString

REMOVE_HEADERS	back to summary
private static final Header[] REMOVE_HEADERS

request	back to summary
pack-priv Request request

sessionFromURL	back to summary
pack-priv boolean sessionFromURL

sessionId	back to summary
pack-priv String sessionId

Constructor Detail

PushBuilder	back to summary
public PushBuilder(final Request request)

Method Detail

addHeader	back to summary
public PushBuilder addHeader(String name, String value) Add a request header to be used for the push. Parameters name:String The header name to add value:String The header value to add Returns:PushBuilder this builder.

addHeader

back to summary

public PushBuilder addHeader(String name, String value)

Add a request header to be used for the push.

Parameters

name:String: The header name to add
value:String: The header value to add

Returns:PushBuilder

this builder.

addHeader back to summary

addHeader	back to summary
public PushBuilder addHeader(Header name, String value) Add a request header to be used for the push. Parameters name:Header The `Header` to add value:String The header value to add Returns:PushBuilder this builder.

public PushBuilder addHeader(Header name, String value)

Add a request header to be used for the push.

Parameters

name:Header: The Header to add
value:String: The header value to add

Returns:PushBuilder

this builder.

composeReferrerHeader	back to summary
private String composeReferrerHeader(final Request request)

getHeader	back to summary
public String getHeader(String name) Return the header of the given name to be used for the push. Returns:String the header of the given name to be used for the push.

getHeader

back to summary

public String getHeader(String name)

Return the header of the given name to be used for the push.

Returns:String: the header of the given name to be used for the push.

getHeaderNames	back to summary
public Iterable<String> getHeaderNames() Return the set of header to be used for the push. Returns:Iterable<String> the set of header to be used for the push.

getHeaderNames

back to summary

public Iterable<String> getHeaderNames()

Return the set of header to be used for the push.

Returns:Iterable<String>: the set of header to be used for the push.

getMethod	back to summary
public String getMethod() Return the method to be used for the push. Returns:String the method to be used for the push.

getMethod

back to summary

public String getMethod()

Return the method to be used for the push.

Returns:String: the method to be used for the push.

getPath	back to summary
public String getPath() Return the URI path to be used for the push. Returns:String the URI path to be used for the push.

getPath

back to summary

public String getPath()

Return the URI path to be used for the push.

Returns:String: the URI path to be used for the push.

getQueryString	back to summary
public String getQueryString() Return the query string to be used for the push. Returns:String the query string to be used for the push.

getQueryString

back to summary

public String getQueryString()

Return the query string to be used for the push.

Returns:String: the query string to be used for the push.

getSessionId	back to summary
public String getSessionId() Return the SessionID to be used for the push. Returns:String the SessionID to be used for the push.

getSessionId

back to summary

public String getSessionId()

Return the SessionID to be used for the push.

Returns:String: the SessionID to be used for the push.

method back to summary

method	back to summary
public PushBuilder method(final String method) Set the method to be used for the push. Parameters method:String the method to be used for the push. Returns:PushBuilder this builder. Exceptions NullPointerException: if the argument is `null` IllegalArgumentException: if the argument is the empty String, or any non-cacheable or unsafe methods defined in RFC 7231, which are POST, PUT, DELETE, CONNECT, OPTIONS and TRACE.

public PushBuilder method(final String method)

Set the method to be used for the push.

Parameters

method:String: the method to be used for the push.

Returns:PushBuilder

this builder.

Exceptions

NullPointerException:: if the argument is null
IllegalArgumentException:: if the argument is the empty String, or any non-cacheable or unsafe methods defined in RFC 7231, which are POST, PUT, DELETE, CONNECT, OPTIONS and TRACE.

nameAndValueValid	back to summary
private static boolean nameAndValueValid(final String name, final String value)

path back to summary

path	back to summary
public PushBuilder path(String path) 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`, preserving duplicates. Parameters path:String the URI path to be used for the push, which may include a query string. Returns:PushBuilder this builder.

public PushBuilder path(String path)

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, preserving duplicates.

Parameters

path:String: the URI path to be used for the push, which may include a query string.

Returns:PushBuilder

this builder.

push back to summary

push	back to summary
public void push() Push a resource given the current state of the builder without blocking. Push a resource based on the current state of the PushBuilder. Calling this method does not guarantee the resource will actually be pushed, since it is possible the client can decline acceptance of the pushed resource using the underlying HTTP/2 protocol. Before returning from this method, the builder has its path set to null and all conditional headers removed. All other fields are left as is for possible reuse in another push. Exceptions IllegalStateException: if there was no call to `path` on this instance either between its instantiation or the last call to `push()` that did not throw an IllegalStateException.

public void push()

Push a resource given the current state of the builder without blocking.

Push a resource based on the current state of the PushBuilder. Calling this method does not guarantee the resource will actually be pushed, since it is possible the client can decline acceptance of the pushed resource using the underlying HTTP/2 protocol.

Before returning from this method, the builder has its path set to null and all conditional headers removed. All other fields are left as is for possible reuse in another push.

Exceptions

IllegalStateException:: if there was no call to path on this instance either between its instantiation or the last call to push() that did not throw an IllegalStateException.

queryString back to summary

queryString	back to summary
public PushBuilder queryString(String queryString) 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:String the query string to be used for the push. Returns:PushBuilder this builder.

public PushBuilder queryString(String queryString)

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:String: the query string to be used for the push.

Returns:PushBuilder

this builder.

removeHeader	back to summary
public PushBuilder removeHeader(String name) Remove the named request header. If the header does not exist, take no action. Parameters name:String The name of the header to remove Returns:PushBuilder this builder.

removeHeader

back to summary

public PushBuilder removeHeader(String name)

Remove the named request header. If the header does not exist, take no action.

Parameters

name:String: The name of the header to remove

Returns:PushBuilder

this builder.

removeHeader back to summary

removeHeader	back to summary
public PushBuilder removeHeader(Header name) Remove the named request header. If the header does not exist, take no action. Parameters name:Header The `Header` to remove Returns:PushBuilder this builder.

public PushBuilder removeHeader(Header name)

Remove the named request header. If the header does not exist, take no action.

Parameters

name:Header: The Header to remove

Returns:PushBuilder

this builder.

sessionId	back to summary
public PushBuilder sessionId(String sessionId) 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:String the SessionID to be used for the push. Returns:PushBuilder this builder.

sessionId

back to summary

public PushBuilder sessionId(String sessionId)

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:String: the SessionID to be used for the push.

Returns:PushBuilder

this builder.

setHeader	back to summary
public PushBuilder setHeader(String name, String value) Set a request header to be used for the push. If the builder has an existing header with the same name, its value is overwritten. Parameters name:String The header name to set value:String The header value to set Returns:PushBuilder this builder.

setHeader

back to summary

public PushBuilder setHeader(String name, String value)

Set a request header to be used for the push. If the builder has an existing header with the same name, its value is overwritten.

Parameters

name:String: The header name to set
value:String: The header value to set

Returns:PushBuilder

this builder.

setHeader back to summary

setHeader	back to summary
public PushBuilder setHeader(Header name, String value) Set a request header to be used for the push. If the builder has an existing header with the same name, its value is overwritten. Parameters name:Header The `Header` to set value:String The header value to set Returns:PushBuilder this builder.

public PushBuilder setHeader(Header name, String value)

Set a request header to be used for the push. If the builder has an existing header with the same name, its value is overwritten.

Parameters

name:Header: The Header to set
value:String: The header value to set

Returns:PushBuilder

this builder.

validate	back to summary
private static String validate(final String value)

validValue	back to summary
private static boolean validValue(final String value)

public final Class PushBuilder

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail