Index: 3rdParty_sources/servlet-api/javax/servlet/http/HttpServletRequest.java =================================================================== diff -u -r7475d08afc280b5e2e5ddf04e8bf35e3166aaf80 -r188531e2b734df509672788d897e1030e4b1a24a --- 3rdParty_sources/servlet-api/javax/servlet/http/HttpServletRequest.java (.../HttpServletRequest.java) (revision 7475d08afc280b5e2e5ddf04e8bf35e3166aaf80) +++ 3rdParty_sources/servlet-api/javax/servlet/http/HttpServletRequest.java (.../HttpServletRequest.java) (revision 188531e2b734df509672788d897e1030e4b1a24a) @@ -1,7 +1,7 @@ /* * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. * - * Copyright (c) 1997-2013 Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1997-2017 Oracle and/or its affiliates. All rights reserved. * * The contents of this file are subject to the terms of either the GNU * General Public License Version 2 only ("GPL") or the Common Development @@ -60,15 +60,16 @@ import java.io.IOException; import java.util.*; +import javax.servlet.RequestDispatcher; import javax.servlet.ServletException; import javax.servlet.ServletRequest; /** * - * Extends the {@link javax.servlet.ServletRequest} interface - * to provide request information for HTTP servlets. + * Extends the {@link javax.servlet.ServletRequest} interface to provide + * request information for HTTP servlets. * - *

The servlet container creates an HttpServletRequest + *

The servlet container creates an HttpServletRequest * object and passes it as an argument to the servlet's service * methods (doGet, doPost, etc). * @@ -100,23 +101,23 @@ /** * Returns the name of the authentication scheme used to protect - * the servlet. All servlet containers support basic, form and client - * certificate authentication, and may additionally support digest + * the servlet. All servlet containers support basic, form and client + * certificate authentication, and may additionally support digest * authentication. - * If the servlet is not authenticated null is returned. + * If the servlet is not authenticated null is returned. * *

Same as the value of the CGI variable AUTH_TYPE. * - * @return one of the static members BASIC_AUTH, + * @return one of the static members BASIC_AUTH, * FORM_AUTH, CLIENT_CERT_AUTH, DIGEST_AUTH * (suitable for == comparison) or * the container-specific string indicating * the authentication scheme, or - * null if the request was - * not authenticated. + * null if the request was + * not authenticated. */ public String getAuthType(); - + /** * Returns an array containing all of the Cookie * objects the client sent with this request. @@ -130,10 +131,10 @@ /** * Returns the value of the specified request header - * as a long value that represents a + * as a long value that represents a * Date object. Use this method with * headers that contain dates, such as - * If-Modified-Since. + * If-Modified-Since. * *

The date is returned as * the number of milliseconds since January 1, 1970 GMT. @@ -179,8 +180,8 @@ * header, or null * if the request does not * have a header of that name - */ - public String getHeader(String name); + */ + public String getHeader(String name); /** * Returns all the values of the specified request header @@ -203,12 +204,12 @@ * the values of the requested header. If * the request does not have any headers of * that name return an empty - * enumeration. If + * enumeration. If * the container does not allow access to * header information, return null - */ - public Enumeration getHeaders(String name); - + */ + public Enumeration getHeaders(String name); + /** * Returns an enumeration of all the header names * this request contains. If the request has no @@ -227,7 +228,7 @@ * null */ public Enumeration getHeaderNames(); - + /** * Returns the value of the specified request header * as an int. If the request does not have a header @@ -240,7 +241,7 @@ * @param name a String specifying the name * of a request header * - * @return an integer expressing the value + * @return an integer expressing the value * of the request header or -1 * if the request doesn't have a * header of this name @@ -250,19 +251,99 @@ * to an int */ public int getIntHeader(String name); + + /** + *

Return the {@link HttpServletMapping} by which the {@link + * HttpServlet} for this {@code HttpServletRequest} was invoked. + * The mappings for any applicable {@link javax.servlet.Filter}s are + * not indicated in the result. If the currently active {@link + * javax.servlet.Servlet} invocation was obtained by a call to + * {@link ServletRequest#getRequestDispatcher} followed by a call to + * {@link RequestDispatcher#forward}, the returned {@code + * HttpServletMapping} is the one corresponding to the path used to + * obtain the {@link RequestDispatcher}. If the currently active + * {@code Servlet} invocation was obtained by a call to {@link + * ServletRequest#getRequestDispatcher} followed by a call to {@link + * RequestDispatcher#include}, the returned {@code + * HttpServletMapping} is the one corresponding to the path that + * caused the first {@code Servlet} in the invocation sequence to be + * invoked. If the currently active {@code Servlet} invocation was + * obtained by a call to {@link + * javax.servlet.AsyncContext#dispatch}, the returned {@code + * HttpServletMapping} is the one corresponding to the path that + * caused the first {@code Servlet} in the invocation sequence to be + * invoked. See {@link + * javax.servlet.RequestDispatcher#FORWARD_MAPPING}, {@link + * javax.servlet.RequestDispatcher#INCLUDE_MAPPING} and {@link + * javax.servlet.AsyncContext#ASYNC_MAPPING} for additional request + * attributes related to {@code HttpServletMapping}. If the + * currently active {@code Servlet} invocation was obtained by a + * call to {@link javax.servlet.ServletContext#getNamedDispatcher}, + * the returned {@code HttpServletMapping} is the one corresponding + * to the path for the mapping last applied to this request.

+ * + *

The returned object is immutable. Servlet 4.0 compliant + * implementations must override this method.

+ * + * @implSpec The default implementation returns a {@code + * HttpServletMapping} that returns the empty string for the match + * value, pattern and servlet name and {@code null} for the match + * type. + * + * @return An instance of {@code HttpServletMapping} describing the manner in which + * the current request was invoked. + * + * @since 4.0 + */ + default public HttpServletMapping getHttpServletMapping() { + return new HttpServletMapping() { + @Override + public String getMatchValue() { + return ""; + } + + @Override + public String getPattern() { + return ""; + } + + @Override + public String getServletName() { + return ""; + } + + @Override + public MappingMatch getMappingMatch() { + return null; + } + + @Override + public String toString() { + return "MappingImpl{" + "matchValue=" + getMatchValue() + + ", pattern=" + getPattern() + ", servletName=" + + getServletName() + ", mappingMatch=" + getMappingMatch() + + "} HttpServletRequest {" + HttpServletRequest.this.toString() + + '}'; + } + + + + }; + } + /** - * Returns the name of the HTTP method with which this + * Returns the name of the HTTP method with which this * request was made, for example, GET, POST, or PUT. * Same as the value of the CGI variable REQUEST_METHOD. * - * @return a String + * @return a String * specifying the name * of the method with which * this request was made */ public String getMethod(); - + /** * Returns any extra path information associated with * the URL the client sent when it made this request. @@ -276,7 +357,7 @@ *

Same as the value of the CGI variable PATH_INFO. * * @return a String, decoded by the - * web container, specifying + * web container, specifying * extra path information that comes * after the servlet path but before * the query string in the request URL; @@ -305,6 +386,25 @@ public String getPathTranslated(); /** + * Instantiates a new instance of {@link PushBuilder} for issuing server + * push responses from the current request. This method returns null + * if the current connection does not support server push, or server + * push has been disabled by the client via a + * {@code SETTINGS_ENABLE_PUSH} settings frame value of {@code 0} (zero). + * + * @implSpec + * The default implementation returns null. + * + * @return a {@link PushBuilder} for issuing server push responses + * from the current request, or null if push is not supported + * + * @since Servlet 4.0 + */ + default public PushBuilder newPushBuilder() { + return null; + } + + /** * Returns the portion of the request URI that indicates the context * of the request. The context path always comes first in a request * URI. The path starts with a "/" character but does not end with a "/" @@ -328,46 +428,46 @@ * @see javax.servlet.ServletContext#getContextPath() */ public String getContextPath(); - + /** * Returns the query string that is contained in the request * URL after the path. This method returns null * if the URL does not have a query string. Same as the value - * of the CGI variable QUERY_STRING. + * of the CGI variable QUERY_STRING. * * @return a String containing the query - * string or null if the URL + * string or null if the URL * contains no query string. The value is not * decoded by the container. */ public String getQueryString(); - + /** * Returns the login of the user making this request, if the - * user has been authenticated, or null if the user + * user has been authenticated, or null if the user * has not been authenticated. * Whether the user name is sent with each subsequent request - * depends on the browser and type of authentication. Same as the + * depends on the browser and type of authentication. Same as the * value of the CGI variable REMOTE_USER. * * @return a String specifying the login * of the user making this request, or null * if the user login is not known */ public String getRemoteUser(); - + /** * Returns a boolean indicating whether the authenticated user is included * in the specified logical "role". Roles and role membership can be * defined using deployment descriptors. If the user has not been * authenticated, the method returns false. * - *

The role name “*” should never be used as an argument in calling + *

The role name "*" should never be used as an argument in calling * isUserInRole. Any call to isUserInRole with - * “*” must return false. - * If the role-name of the security-role to be tested is “**”, and + * "*" must return false. + * If the role-name of the security-role to be tested is "**", and * the application has NOT declared an application security-role with - * role-name “**”, isUserInRole must only return true if + * role-name "**", isUserInRole must only return true if * the user has been authenticated; that is, only when * {@link #getRemoteUser} and {@link #getUserPrincipal} would both return * a non-null value. Otherwise, the container must check @@ -378,23 +478,23 @@ * * @return a boolean indicating whether * the user making this request belongs to a given role; - * false if the user has not been + * false if the user has not been * authenticated */ public boolean isUserInRole(String role); - + /** * Returns a java.security.Principal object containing * the name of the current authenticated user. If the user has not been * authenticated, the method returns null. * * @return a java.security.Principal containing * the name of the user making this request; - * null if the user has not been + * null if the user has not been * authenticated */ public java.security.Principal getUserPrincipal(); - + /** * Returns the session ID specified by the client. This may * not be the same as the ID of the current valid session @@ -409,13 +509,13 @@ * @see #isRequestedSessionIdValid */ public String getRequestedSessionId(); - + /** * Returns the part of this request's URL from the protocol * name up to the query string in the first line of the HTTP request. * The web container does not decode this String. * For example: - * + * * * * @@ -429,13 +529,13 @@ * {@link HttpUtils#getRequestURL}. * * @return a String containing - * the part of the URL from the + * the part of the URL from the * protocol name up to the query string * * @see HttpUtils#getRequestURL */ public String getRequestURI(); - + /** * Reconstructs the URL the client used to make the request. * The returned URL contains a protocol, server name, port @@ -479,29 +579,29 @@ * using the "/*" pattern. */ public String getServletPath(); - + /** * Returns the current HttpSession * associated with this request or, if there is no - * current session and create is true, returns + * current session and create is true, returns * a new session. * *

If create is false * and the request has no valid HttpSession, * this method returns null. * *

To make sure the session is properly maintained, - * you must call this method before + * you must call this method before * the response is committed. If the container is using cookies * to maintain session integrity and is asked to create a new session * when the response is committed, an IllegalStateException is thrown. * * @param create true to create - * a new session for this request if necessary; + * a new session for this request if necessary; * false to return null * if there's no current session * - * @return the HttpSession associated + * @return the HttpSession associated * with this request or null if * create is false * and the request has no valid session @@ -513,7 +613,7 @@ /** * Returns the current session associated with this request, * or if the request does not have a session, creates one. - * + * * @return the HttpSession associated * with this request * @@ -523,7 +623,7 @@ /** * Change the session id of the current session associated with this - * request and return the new session id. + * request and return the new session id. * * @return the new session id * @@ -533,12 +633,12 @@ * @since Servlet 3.1 */ public String changeSessionId(); - + /** * Checks whether the requested session ID is still valid. * *

If the client did not specify any session ID, this method returns - * false. + * false. * * @return true if this * request has an id for a valid session @@ -550,114 +650,120 @@ * @see HttpSessionContext */ public boolean isRequestedSessionIdValid(); - + /** - * Checks whether the requested session ID came in as a cookie. + *

Checks whether the requested session ID was conveyed to the + * server as an HTTP cookie.

* * @return true if the session ID - * came in as a + * was conveyed to the server an an HTTP * cookie; otherwise, false * * @see #getSession - */ + */ public boolean isRequestedSessionIdFromCookie(); - + /** - * Checks whether the requested session ID came in as part of the - * request URL. + *

Checks whether the requested session ID was conveyed to the + * server as part of the request URL.

* - * @return true if the session ID - * came in as part of a URL; otherwise, + * @return true if the session ID was conveyed to the + * server as part of a URL; otherwise, * false * * @see #getSession */ public boolean isRequestedSessionIdFromURL(); - + /** * @deprecated As of Version 2.1 of the Java Servlet * API, use {@link #isRequestedSessionIdFromURL} * instead. + * + * @return true if the session ID was conveyed to the + * server as part of a URL; otherwise, + * false */ + @Deprecated public boolean isRequestedSessionIdFromUrl(); /** - * Use the container login mechanism configured for the - * ServletContext to authenticate the user making - * this request. - * - *

This method may modify and commit the argument + * Use the container login mechanism configured for the + * ServletContext to authenticate the user making + * this request. + * + *

This method may modify and commit the argument * HttpServletResponse. - * - * @param response The HttpServletResponse + * + * @param response The HttpServletResponse * associated with this HttpServletRequest - * + * * @return true when non-null values were or have been - * established as the values returned by getUserPrincipal, - * getRemoteUser, and getAuthType. Return - * false if authentication is incomplete and the underlying - * login mechanism has committed, in the response, the message (e.g., + * established as the values returned by getUserPrincipal, + * getRemoteUser, and getAuthType. Return + * false if authentication is incomplete and the underlying + * login mechanism has committed, in the response, the message (e.g., * challenge) and HTTP status code to be returned to the user. * * @throws IOException if an input or output error occurred while * reading from this request or writing to the given response * * @throws IllegalStateException if the login mechanism attempted to * modify the response and it was already committed - * + * * @throws ServletException if the authentication failed and - * the caller is responsible for handling the error (i.e., the - * underlying login mechanism did NOT establish the message and + * the caller is responsible for handling the error (i.e., the + * underlying login mechanism did NOT establish the message and * HTTP status code to be returned to the user) * * @since Servlet 3.0 */ - public boolean authenticate(HttpServletResponse response) + public boolean authenticate(HttpServletResponse response) throws IOException,ServletException; /** - * Validate the provided username and password in the password validation - * realm used by the web container login mechanism configured for the + * Validate the provided username and password in the password validation + * realm used by the web container login mechanism configured for the * ServletContext. - * - *

This method returns without throwing a ServletException - * when the login mechanism configured for the ServletContext + * + *

This method returns without throwing a ServletException + * when the login mechanism configured for the ServletContext * supports username password validation, and when, at the time of the * call to login, the identity of the caller of the request had - * not been established (i.e, all of getUserPrincipal, - * getRemoteUser, and getAuthType return null), - * and when validation of the provided credentials is successful. + * not been established (i.e, all of getUserPrincipal, + * getRemoteUser, and getAuthType return null), + * and when validation of the provided credentials is successful. * Otherwise, this method throws a ServletException as * described below. - * + * *

When this method returns without throwing an exception, it must * have established non-null values as the values returned by - * getUserPrincipal, getRemoteUser, and + * getUserPrincipal, getRemoteUser, and * getAuthType. - * + * * @param username The String value corresponding to * the login identifier of the user. - * + * * @param password The password String corresponding * to the identified user. * - * @exception ServletException if the configured login mechanism - * does not support username - * password authentication, or if a - * non-null caller identity had - * already been established (prior - * to the call to login), or if - * validation of the provided + * @exception ServletException if the configured login mechanism + * does not support username + * password authentication, or if a + * non-null caller identity had + * already been established (prior + * to the call to login), or if + * validation of the provided * username and password fails. * * @since Servlet 3.0 */ - public void login(String username, String password) + public void login(String username, String password) throws ServletException; - + /** - * Establish null as the value returned when - * getUserPrincipal, getRemoteUser, + * Establish null as the value returned when + * getUserPrincipal, getRemoteUser, * and getAuthType is called on the request. * * @exception ServletException if logout fails @@ -674,7 +780,7 @@ * does not contain any Part components, the returned * Collection will be empty. * - *

Any changes to the returned Collection must not + *

Any changes to the returned Collection must not * affect this HttpServletRequest. * * @return a (possibly empty) Collection of the @@ -727,9 +833,12 @@ public Part getPart(String name) throws IOException, ServletException; /** - * Create an instance of HttpUpgradeHandler for an given + * Creates an instance of HttpUpgradeHandler for a given * class and uses it for the http protocol upgrade processing. * + * @param The {@code Class}, which extends {@link + * HttpUpgradeHandler}, of the {@code handlerClass}. + * @param handlerClass The HttpUpgradeHandler class used for the upgrade. * * @return an instance of the HttpUpgradeHandler @@ -745,4 +854,59 @@ */ public T upgrade(Class handlerClass) throws IOException, ServletException; + + /** + * Get the request trailer fields. + * + *

The returned map is not backed by the {@code HttpServletRequest} object, + * so changes in the returned map are not reflected in the + * {@code HttpServletRequest} object, and vice-versa.

+ * + *

{@link #isTrailerFieldsReady()} should be called first to determine + * if it is safe to call this method without causing an exception.

+ * + * @implSpec + * The default implementation returns an empty map. + * + * @return A map of trailer fields in which all the keys are in lowercase, + * regardless of the case they had at the protocol level. If there are no + * trailer fields, yet {@link #isTrailerFieldsReady} is returning true, + * the empty map is returned. + * + * @throws IllegalStateException if {@link #isTrailerFieldsReady()} is false + * + * @since Servlet 4.0 + */ + default public Map getTrailerFields() { + return Collections.emptyMap(); + } + + /** + * Return a boolean indicating whether trailer fields are ready to read + * using {@link #getTrailerFields}. + * + * This methods returns true immediately if it is known that there is no + * trailer in the request, for instance, the underlying protocol (such + * as HTTP 1.0) does not supports the trailer fields, or the request is + * not in chunked encoding in HTTP 1.1. + * And the method also returns true if both of the following conditions + * are satisfied: + *
    + *
  1. the application has read all the request data and an EOF + * indication has been returned from the {@link #getReader} + * or {@link #getInputStream}. + *
  2. all the trailer fields sent by the client have been received. + * Note that it is possible that the client has sent no trailer fields. + *
+ * + * @implSpec + * The default implementation returns false. + * + * @return a boolean whether trailer fields are ready to read + * + * @since Servlet 4.0 + */ + default public boolean isTrailerFieldsReady() { + return true; + } }
First line of HTTP request Returned Value