| // |
| // ======================================================================== |
| // Copyright (c) 1995-2016 Mort Bay Consulting Pty. Ltd. |
| // ------------------------------------------------------------------------ |
| // All rights reserved. This program and the accompanying materials |
| // are made available under the terms of the Eclipse Public License v1.0 |
| // and Apache License v2.0 which accompanies this distribution. |
| // |
| // The Eclipse Public License is available at |
| // http://www.eclipse.org/legal/epl-v10.html |
| // |
| // The Apache License v2.0 is available at |
| // http://www.opensource.org/licenses/apache2.0.php |
| // |
| // You may elect to redistribute this code under either of these licenses. |
| // ======================================================================== |
| // |
| |
| package org.eclipse.jetty.server; |
| |
| import java.util.Set; |
| |
| import javax.servlet.http.Cookie; |
| import javax.servlet.http.HttpServletRequest; |
| import javax.servlet.http.HttpServletResponse; |
| import javax.servlet.http.HttpSession; |
| |
| /** Build a request to be pushed. |
| * <p> |
| * A PushBuilder is obtained by calling {@link Request#getPushBuilder()} |
| * which creates an initializes the builder as follows: |
| * <ul> |
| * <li> Each call to getPushBuilder() will return a new instance of a |
| * PushBuilder based off the Request. Any mutations to the |
| * returned PushBuilder are not reflected on future returns.</li> |
| * <li>The method is initialized to "GET"</li> |
| * <li>The requests headers are added to the Builder, except for:<ul> |
| * <li>Conditional headers (eg. If-Modified-Since) |
| * <li>Range headers |
| * <li>Expect headers |
| * <li>Authorization headers |
| * <li>Referrer headers |
| * </ul></li> |
| * <li>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</li> |
| * <li>The query string from {@link HttpServletRequest#getQueryString()} |
| * <li>The {@link HttpServletRequest#getRequestedSessionId()} value, unless at the time |
| * of the call {@link HttpServletRequest#getSession(boolean)} |
| * has previously been called to create a new {@link HttpSession}, in |
| * which case the new session ID will be used as the PushBuilders |
| * requested session ID. The source of the requested session id will be the |
| * same as for the request</li> |
| * <li>The Referer header will be set to {@link HttpServletRequest#getRequestURL()} |
| * plus any {@link HttpServletRequest#getQueryString()} </li> |
| * <li>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.</li> |
| * <li>If this request has has the conditional headers If-Modified-Since or |
| * If-None-Match then the {@link #isConditional()} header is set to true.</li> |
| * </ul> |
| * <p>A PushBuilder can be customized by chained calls to mutator methods before the |
| * {@link #push()} method is called to initiate a 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 {@link #path(String)}, {@link #etag(String)} and |
| * {@link #lastModified(String)} values will have been nulled. All other |
| * values are retained over calls to {@link #push()}. |
| */ |
| public interface PushBuilder |
| { |
| /** Set the method to be used for the push. |
| * Defaults to GET. |
| * @param method the method to be used for the push. |
| * @return this builder. |
| */ |
| public abstract PushBuilder method(String method); |
| |
| /** Set the query string to be used for the push. |
| * Defaults to the requests query string. |
| * Will be appended to any query String included in a call to {@link #path(String)}. 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, or to remove a |
| * query string obtained from the associated request. |
| * @param queryString the query string to be used for the push. |
| * @return this builder. |
| */ |
| public abstract 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 abstract PushBuilder sessionId(String sessionId); |
| |
| /** Set if the request is to be conditional. |
| * If the request is conditional, any available values from {@link #etag(String)} or |
| * {@link #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. |
| * @param conditional true if the push request is conditional |
| * @return this builder. |
| */ |
| public abstract PushBuilder conditional(boolean conditional); |
| |
| /** Set a header to be used for the push. |
| * @param name The header name to set |
| * @param value The header value to set |
| * @return this builder. |
| */ |
| public abstract PushBuilder setHeader(String name, String value); |
| |
| /** Add a 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 abstract PushBuilder addHeader(String name, String value); |
| |
| /** 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()} |
| * @param path the URI path to be used for the push, which may include a |
| * query string. |
| * @return this builder. |
| */ |
| public abstract PushBuilder path(String path); |
| |
| /** Set the etag to be used for conditional pushes. |
| * The etag will be used only if {@link #isConditional()} is true. |
| * Defaults to no etag. The value is nulled after every call to |
| * {@link #push()} |
| * @param etag the etag to be used for the push. |
| * @return this builder. |
| */ |
| public abstract PushBuilder etag(String etag); |
| |
| /** Set the last modified date to be used for conditional pushes. |
| * The last modified date will be used only if {@link #isConditional()} is true. |
| * Defaults to no date. The value is nulled after every call to |
| * {@link #push()} |
| * @param lastModified the last modified date to be used for the push. |
| * @return this builder. |
| * */ |
| public abstract PushBuilder lastModified(String lastModified); |
| |
| |
| /** Push a resource. |
| * Push a resource based on the current state of the PushBuilder. If {@link #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. |
| * After initiating the push, the builder has its path, etag and lastModified fields nulled. All |
| * other fields are left as is for possible reuse in another push. |
| * @throws IllegalArgumentException if the method set expects a request body (eg POST) |
| */ |
| public abstract void push(); |
| |
| |
| |
| |
| |
| public abstract String getMethod(); |
| public abstract String getQueryString(); |
| public abstract String getSessionId(); |
| public abstract boolean isConditional(); |
| public abstract Set<String> getHeaderNames(); |
| public abstract String getHeader(String name); |
| public abstract String getPath(); |
| public abstract String getEtag(); |
| public abstract String getLastModified(); |
| |
| |
| |
| } |
