001/* 002 * Copyright 2002-2020 the original author or authors. 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); 005 * you may not use this file except in compliance with the License. 006 * You may obtain a copy of the License at 007 * 008 * https://www.apache.org/licenses/LICENSE-2.0 009 * 010 * Unless required by applicable law or agreed to in writing, software 011 * distributed under the License is distributed on an "AS IS" BASIS, 012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 013 * See the License for the specific language governing permissions and 014 * limitations under the License. 015 */ 016 017package org.springframework.web.context.request; 018 019import java.security.Principal; 020import java.util.Iterator; 021import java.util.Locale; 022import java.util.Map; 023 024/** 025 * Generic interface for a web request. Mainly intended for generic web 026 * request interceptors, giving them access to general request metadata, 027 * not for actual handling of the request. 028 * 029 * @author Juergen Hoeller 030 * @author Brian Clozel 031 * @since 2.0 032 * @see WebRequestInterceptor 033 */ 034public interface WebRequest extends RequestAttributes { 035 036 /** 037 * Return the request header of the given name, or {@code null} if none. 038 * <p>Retrieves the first header value in case of a multi-value header. 039 * @since 3.0 040 * @see javax.servlet.http.HttpServletRequest#getHeader(String) 041 */ 042 String getHeader(String headerName); 043 044 /** 045 * Return the request header values for the given header name, 046 * or {@code null} if none. 047 * <p>A single-value header will be exposed as an array with a single element. 048 * @since 3.0 049 * @see javax.servlet.http.HttpServletRequest#getHeaders(String) 050 */ 051 String[] getHeaderValues(String headerName); 052 053 /** 054 * Return a Iterator over request header names. 055 * @since 3.0 056 * @see javax.servlet.http.HttpServletRequest#getHeaderNames() 057 */ 058 Iterator<String> getHeaderNames(); 059 060 /** 061 * Return the request parameter of the given name, or {@code null} if none. 062 * <p>Retrieves the first parameter value in case of a multi-value parameter. 063 * @see javax.servlet.http.HttpServletRequest#getParameter(String) 064 */ 065 String getParameter(String paramName); 066 067 /** 068 * Return the request parameter values for the given parameter name, 069 * or {@code null} if none. 070 * <p>A single-value parameter will be exposed as an array with a single element. 071 * @see javax.servlet.http.HttpServletRequest#getParameterValues(String) 072 */ 073 String[] getParameterValues(String paramName); 074 075 /** 076 * Return a Iterator over request parameter names. 077 * @since 3.0 078 * @see javax.servlet.http.HttpServletRequest#getParameterNames() 079 */ 080 Iterator<String> getParameterNames(); 081 082 /** 083 * Return a immutable Map of the request parameters, with parameter names as map keys 084 * and parameter values as map values. The map values will be of type String array. 085 * <p>A single-value parameter will be exposed as an array with a single element. 086 * @see javax.servlet.http.HttpServletRequest#getParameterMap() 087 */ 088 Map<String, String[]> getParameterMap(); 089 090 /** 091 * Return the primary Locale for this request. 092 * @see javax.servlet.http.HttpServletRequest#getLocale() 093 */ 094 Locale getLocale(); 095 096 /** 097 * Return the context path for this request 098 * (usually the base path that the current web application is mapped to). 099 * @see javax.servlet.http.HttpServletRequest#getContextPath() 100 */ 101 String getContextPath(); 102 103 /** 104 * Return the remote user for this request, if any. 105 * @see javax.servlet.http.HttpServletRequest#getRemoteUser() 106 */ 107 String getRemoteUser(); 108 109 /** 110 * Return the user principal for this request, if any. 111 * @see javax.servlet.http.HttpServletRequest#getUserPrincipal() 112 */ 113 Principal getUserPrincipal(); 114 115 /** 116 * Determine whether the user is in the given role for this request. 117 * @see javax.servlet.http.HttpServletRequest#isUserInRole(String) 118 */ 119 boolean isUserInRole(String role); 120 121 /** 122 * Return whether this request has been sent over a secure transport 123 * mechanism (such as SSL). 124 * @see javax.servlet.http.HttpServletRequest#isSecure() 125 */ 126 boolean isSecure(); 127 128 /** 129 * Check whether the requested resource has been modified given the 130 * supplied last-modified timestamp (as determined by the application). 131 * <p>This will also transparently set the "Last-Modified" response header 132 * and HTTP status when applicable. 133 * <p>Typical usage: 134 * <pre class="code"> 135 * public String myHandleMethod(WebRequest request, Model model) { 136 * long lastModified = // application-specific calculation 137 * if (request.checkNotModified(lastModified)) { 138 * // shortcut exit - no further processing necessary 139 * return null; 140 * } 141 * // further request processing, actually building content 142 * model.addAttribute(...); 143 * return "myViewName"; 144 * }</pre> 145 * <p>This method works with conditional GET/HEAD requests, but 146 * also with conditional POST/PUT/DELETE requests. 147 * <p><strong>Note:</strong> you can use either 148 * this {@code #checkNotModified(long)} method; or 149 * {@link #checkNotModified(String)}. If you want enforce both 150 * a strong entity tag and a Last-Modified value, 151 * as recommended by the HTTP specification, 152 * then you should use {@link #checkNotModified(String, long)}. 153 * <p>If the "If-Modified-Since" header is set but cannot be parsed 154 * to a date value, this method will ignore the header and proceed 155 * with setting the last-modified timestamp on the response. 156 * @param lastModifiedTimestamp the last-modified timestamp in 157 * milliseconds that the application determined for the underlying 158 * resource 159 * @return whether the request qualifies as not modified, 160 * allowing to abort request processing and relying on the response 161 * telling the client that the content has not been modified 162 */ 163 boolean checkNotModified(long lastModifiedTimestamp); 164 165 /** 166 * Check whether the requested resource has been modified given the 167 * supplied {@code ETag} (entity tag), as determined by the application. 168 * <p>This will also transparently set the "ETag" response header 169 * and HTTP status when applicable. 170 * <p>Typical usage: 171 * <pre class="code"> 172 * public String myHandleMethod(WebRequest request, Model model) { 173 * String eTag = // application-specific calculation 174 * if (request.checkNotModified(eTag)) { 175 * // shortcut exit - no further processing necessary 176 * return null; 177 * } 178 * // further request processing, actually building content 179 * model.addAttribute(...); 180 * return "myViewName"; 181 * }</pre> 182 * <p><strong>Note:</strong> you can use either 183 * this {@code #checkNotModified(String)} method; or 184 * {@link #checkNotModified(long)}. If you want enforce both 185 * a strong entity tag and a Last-Modified value, 186 * as recommended by the HTTP specification, 187 * then you should use {@link #checkNotModified(String, long)}. 188 * @param etag the entity tag that the application determined 189 * for the underlying resource. This parameter will be padded 190 * with quotes (") if necessary. 191 * @return true if the request does not require further processing. 192 */ 193 boolean checkNotModified(String etag); 194 195 /** 196 * Check whether the requested resource has been modified given the 197 * supplied {@code ETag} (entity tag) and last-modified timestamp, 198 * as determined by the application. 199 * <p>This will also transparently set the "ETag" and "Last-Modified" 200 * response headers, and HTTP status when applicable. 201 * <p>Typical usage: 202 * <pre class="code"> 203 * public String myHandleMethod(WebRequest request, Model model) { 204 * String eTag = // application-specific calculation 205 * long lastModified = // application-specific calculation 206 * if (request.checkNotModified(eTag, lastModified)) { 207 * // shortcut exit - no further processing necessary 208 * return null; 209 * } 210 * // further request processing, actually building content 211 * model.addAttribute(...); 212 * return "myViewName"; 213 * }</pre> 214 * <p>This method works with conditional GET/HEAD requests, but 215 * also with conditional POST/PUT/DELETE requests. 216 * <p><strong>Note:</strong> The HTTP specification recommends 217 * setting both ETag and Last-Modified values, but you can also 218 * use {@code #checkNotModified(String)} or 219 * {@link #checkNotModified(long)}. 220 * @param etag the entity tag that the application determined 221 * for the underlying resource. This parameter will be padded 222 * with quotes (") if necessary. 223 * @param lastModifiedTimestamp the last-modified timestamp in 224 * milliseconds that the application determined for the underlying 225 * resource 226 * @return true if the request does not require further processing. 227 * @since 4.2 228 */ 229 boolean checkNotModified(String etag, long lastModifiedTimestamp); 230 231 /** 232 * Get a short description of this request, 233 * typically containing request URI and session id. 234 * @param includeClientInfo whether to include client-specific 235 * information such as session id and user name 236 * @return the requested description as String 237 */ 238 String getDescription(boolean includeClientInfo); 239 240}