HttpServletRequest 学习，基于Servlet 4.0

官方API 基于Servlet 3.0

Servlet 4.0 的主要新功能

Servlet 4.0 的主要新功能为服务器推送和全新 API，该 API 可在运行时发现 servlet 的 URL 映射。

服务器推送是最直观的 HTTP/2 强化功能，通过 PushBuilder 接口在 servlet 中公开。服务器推送功能还在 JavaServer Faces API 中实现，并在 RenderResponsePhase 生命周期内调用，以便 JSF 页面可以利用其增强性能。

全新 servlet 映射发现接口 HttpServletMapping 使框架能够获取有关激活给定 servlet 请求的 URL 信息。这可能对框架尤为有用，这些框架需要这一信息来运行内部工作。

package javax.servlet.http;

import java.io.IOException;
import java.util.Collection;
import java.util.Collections;
import java.util.Enumeration;
import java.util.Map;

import javax.servlet.ServletException;
import javax.servlet.ServletRequest;

public interface HttpServletRequest extends ServletRequest {

    /**
     * 基本身份验证的字符串标识
     */
    public static final String BASIC_AUTH = "BASIC";
    /**
     * 表单身份验证的字符串标识
     */
    public static final String FORM_AUTH = "FORM";
    
    /**
     * Client Certificate身份验证的字符串标识符。
     */
    public static final String CLIENT_CERT_AUTH = "CLIENT_CERT";
    
    /**
     * 摘要式身份验证的字符串标识符
     */
    public static final String DIGEST_AUTH = "DIGEST";

    /**
     * 返回用于保护servlet的身份验证方案的名称。
     */
    public String getAuthType();

    /**
     *返回一个数组，其中包含Cookie客户端使用此请求发送的所有对象。
     */
    public Cookie[] getCookies();

    /**
     * 返回指定请求标头的long 值，作为表示Date对象的值。
     */
    public long getDateHeader(String name);

    /**
     * 以a的形式返回指定请求标头的值 String。
     * /
    public String getHeader(String name);

    /**
     * 返回此请求包含的所有标头名称的枚举。
     */
    public Enumeration<String> getHeaders(String name);

    /**
     * 以a的形式返回指定请求标头的值 String。
     */
    public Enumeration<String> getHeaderNames();

    /**
     * 返回此请求包含的所有标头名称的枚举。
     */
    public int getIntHeader(String name);

    public default HttpServletMapping getHttpServletMapping() {
        return new HttpServletMapping() {
        
        	// 返回部分 URI 路径，该路径会导致请求匹配。
            @Override
            public String getMatchValue() {
                return "";
            }
            // 返回 URL 模式的 String 表示形式。
            @Override
            public String getPattern() {
                return "";
            }
            // 返回 servlet 名称的 String 表示形式。
            @Override
            public String getServletName() {
                return "";
            }
            // 返回匹配的类型，表示为 MappingMatch 枚举值，
            // 该枚举值将为以下值之一：CONTEXT_ROOT、DEFAULT、EXACT、EXTENSION 或 PATH。
            @Override
            public MappingMatch getMappingMatch() {
                return null;
            }
        };
    }

    /**
     * 返回用于发出此请求的HTTP方法的名称，例如，GET，POST或PUT。
     */
    public String getMethod();

    /**
     * 返回与客户端发出此请求时发送的URL关联的任何额外路径信息。
     */
    public String getPathInfo();

    /**
     * 返回servlet名称之后但查询字符串之前的任何额外路径信息，并将其转换为实际路径。
     */
    public String getPathTranslated();

    /**
     * 获取服务器推送
     * Servlet 4.0 新增
     */
    public default PushBuilder newPushBuilder() {
        return null;
    }

    /**
     * 返回请求URI的一部分，指示请求的上下文。
     */
    public String getContextPath();

    /**
     * 返回路径后请求URL中包含的查询字符串。
     */
    public String getQueryString();

    /**
     * 如果用户已经过身份验证，或者null用户未经过身份验证，则返回发出此请求的用户的登录名。
     */
    public String getRemoteUser();

    /**
     * 返回一个布尔值，指示经过身份验证的用户是否包含在指定的逻辑“角色”中。
     */
    public boolean isUserInRole(String role);

    /**
     * 返回java.security.Principal包含当前经过身份验证的用户的名称的对象。
     */
    public java.security.Principal getUserPrincipal();

    /**
     * 返回客户端指定的会话ID。
     */
    public String getRequestedSessionId();

    /**
     * 将此请求的URL部分从协议名称返回到HTTP请求第一行中的查询字符串。
     */
    public String getRequestURI();

    /**
     * 重构客户端用于发出请求的URL。
     */
    public StringBuffer getRequestURL();

    /**
     * 返回此请求调用servlet的URL的一部分
     */
    public String getServletPath();

    /**
     * 返回HttpSession与此请求关联的当前值，如果没有当前会话且create为true，则返回新会话。
     */
    public HttpSession getSession(boolean create);

    /**
     * 返回与此请求关联的当前会话，或者如果请求没有会话，则创建一个会话。
     */
    public HttpSession getSession();

    /**
     * 更改与此请求关联的会话的会话ID。
     */
    public String changeSessionId();

    /**
     * 检查请求的会话ID是否仍然有效。
     */
    public boolean isRequestedSessionIdValid();

    /**
     * 检查所请求的会话ID是否作为cookie进入。
     */
    public boolean isRequestedSessionIdFromCookie();

    /**
     * 检查请求的会话ID是否作为请求URL的一部分进入。
     */
    public boolean isRequestedSessionIdFromURL();

    /**
     * 过时，使用isRequestedSessionIdFromURL()
     */
    @Deprecated
    public boolean isRequestedSessionIdFromUrl();

    /**
     * 如果请求是针对受安全性约束保护的资源，则触发相同的身份验证过程。
     */
    public boolean authenticate(HttpServletResponse response)
            throws IOException, ServletException;

    /**
     * 验证提供的用户名和密码，然后将经过身份验证的用户与请求相关联。
     */
    public void login(String username, String password) throws ServletException;

    /**
     * 从请求中删除任何经过身份验证的用户。
     */
    public void logout() throws ServletException;

    /**
     * 返回所有上传部分的集合。
     */
    public Collection<Part> getParts() throws IOException,
            ServletException;

    /**
     * 获取命名的Part，如果Part不存在，则返回null。
     */
    public Part getPart(String name) throws IOException,
            ServletException;

    /**
     * 启动HTTP升级过程，并在当前请求/响应对完成处理后将连接传递给提供的协议处理程序。
     */
    public <T extends HttpUpgradeHandler> T upgrade(
            Class<T> httpUpgradeHandlerClass) throws java.io.IOException, ServletException;

    /**
     * 获取trailer头
     */
    public default Map<String,String> getTrailerFields() {
        return Collections.emptyMap();
    }

    /**
     * 如果基础协议不支持trailer头，则永远返回true。
     * 否则trailer头已经准备好读取，返回true：
     */
    public default boolean isTrailerFieldsReady() {
        return false;
    }
}