jakarta.servlet.http.PushBuilder Maven / Gradle / Ivy
/*
* Copyright (c) 2017, 2020 Oracle and/or its affiliates and others.
* All rights reserved.
*
* This program and the accompanying materials are made available under the
* terms of the Eclipse Public License v. 2.0, which is available at
* http://www.eclipse.org/legal/epl-2.0.
*
* This Source Code may also be made available under the following Secondary
* Licenses when the conditions for such availability set forth in the
* Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
* version 2 with the GNU Classpath Exception, which is available at
* https://www.gnu.org/software/classpath/license.html.
*
* SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
*/
package jakarta.servlet.http;
import java.util.Set;
/**
* Build a request to be pushed.
*
* 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 {@link HttpServletRequest#newPushBuilder()}. Each call to this method will a new
* instance of a PushBuilder based off the current {@code
* HttpServletRequest}, or null. 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 {@link HttpServletRequest} are added to the builder, except for:
*
*
* - Conditional headers (defined in RFC 7232)
*
- 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 session ID will be the value returned from {@link HttpServletRequest#getRequestedSessionId()}, unless
* {@link HttpServletRequest#getSession(boolean)} has previously been called to create a new {@link HttpSession} prior
* to the call to create the {@code PushBuilder}, in which case the new session ID will be used as the PushBuilder's
* requested session ID. Note that the session ID returned from the request can effectively come from one of two
* "sources": a cookie or the URL (as specified in {@link HttpServletRequest#isRequestedSessionIdFromCookie} and
* {@link HttpServletRequest#isRequestedSessionIdFromURL}, respectively). The session ID for the {@code PushBuilder}
* will also come from the same source as the request.
*
* - The Referer(sic) header will be set to {@link HttpServletRequest#getRequestURL()} plus any
* {@link HttpServletRequest#getQueryString()}
*
* - If {@link HttpServletResponse#addCookie(Cookie)} has been called on the associated response, then a corresponding
* Cookie header will be added to the PushBuilder, unless the {@link Cookie#getMaxAge()} is <=0, in which case the
* Cookie will be removed from the builder.
*
*
*
*
* The {@link #path} method must be called on the {@code PushBuilder} instance before the call to {@link #push}. Failure
* to do so must cause an exception to be thrown from {@link #push}, as specified in that method.
*
*
*
* A PushBuilder can be customized by chained calls to mutator methods before the {@link #push()} method is called to
* initiate an asynchronous push request with the current state of the builder. After the call to {@link #push()}, the
* builder may be reused for another push, however the implementation must make it so the {@link #path(String)} and
* conditional headers (defined in RFC 7232) values are cleared before returning from {@link #push}. All other values
* are retained over calls to {@link #push()}.
*
* @since Servlet 4.0
*/
public interface PushBuilder {
/**
*
* Set the method to be used for the push.
*
*
* @param method the method to be used for the push.
*
* @throws NullPointerException if the argument is {@code null}
*
* @throws 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.
*
* @return this builder.
*/
public PushBuilder method(String method);
/**
* Set the query string to be used for the push.
*
* The query string will be appended to any query String included in a call to {@link #path(String)}. Any duplicate
* parameters must be preserved. This method should be used instead of a query in {@link #path(String)} when multiple
* {@link #push()} calls are to be made with the same query string.
*
* @param queryString the query string to be used for the push.
* @return this builder.
*/
public PushBuilder queryString(String queryString);
/**
* 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.
*
* @param sessionId the SessionID to be used for the push.
* @return this builder.
*/
public PushBuilder sessionId(String sessionId);
/**
*
* 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.
*
*
* @param name The header name to set
* @param value The header value to set
* @return this builder.
*/
public PushBuilder setHeader(String name, String value);
/**
*
* Add a request header to be used for the push.
*
*
* @param name The header name to add
* @param value The header value to add
* @return this builder.
*/
public PushBuilder addHeader(String name, String value);
/**
*
* Remove the named request header. If the header does not exist, take no action.
*
*
* @param name The name of the header to remove
* @return this builder.
*/
public PushBuilder removeHeader(String name);
/**
* 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
* {@link #path(String)} must be called before every call to {@link #push()}. If a query string is present in the
* argument {@code path}, its contents must be merged with the contents previously passed to {@link #queryString},
* preserving duplicates.
*
* @param path the URI path to be used for the push, which may include a query string.
* @return this builder.
*/
public PushBuilder path(String path);
/**
* Push a resource given the current state of the builder, the method must be non-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.
*
*
*
* 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, conditional headers (defined in RFC 7232) nulled. All
* other fields are left as is for possible reuse in another push.
*
*
* @throws IllegalStateException if there was no call to {@link #path} on this instance either between its instantiation
* or the last call to {@code push()} that did not throw an IllegalStateException.
*/
public void push();
/**
* Return the method to be used for the push.
*
* @return the method to be used for the push.
*/
public String getMethod();
/**
* Return the query string to be used for the push.
*
* @return the query string to be used for the push.
*/
public String getQueryString();
/**
* Return the SessionID to be used for the push.
*
* @return the SessionID to be used for the push.
*/
public String getSessionId();
/**
* Return the set of header to be used for the push.
*
*
* The returned set is not backed by the {@code PushBuilder} object, so changes in the returned set are not reflected in
* the {@code PushBuilder} object, and vice-versa.
*
*
* @return the set of header to be used for the push.
*/
public Set getHeaderNames();
/**
* Return the header of the given name to be used for the push.
*
* @param name the name of the header
*
* @return the header of the given name to be used for the push.
*/
public String getHeader(String name);
/**
* Return the URI path to be used for the push.
*
* @return the URI path to be used for the push.
*/
public String getPath();
}