1 /*
2 * Copyright 2002-2014 the original author or authors.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17 package org.springframework.web.context.request;
18
19 import java.security.Principal;
20 import java.util.Iterator;
21 import java.util.Locale;
22 import java.util.Map;
23
24 /**
25 * Generic interface for a web request. Mainly intended for generic web
26 * request interceptors, giving them access to general request metadata,
27 * not for actual handling of the request.
28 *
29 * @author Juergen Hoeller
30 * @since 2.0
31 * @see WebRequestInterceptor
32 */
33 public interface WebRequest extends RequestAttributes {
34
35 /**
36 * Return the request header of the given name, or {@code null} if none.
37 * <p>Retrieves the first header value in case of a multi-value header.
38 * @since 3.0
39 * @see javax.servlet.http.HttpServletRequest#getHeader(String)
40 */
41 String getHeader(String headerName);
42
43 /**
44 * Return the request header values for the given header name,
45 * or {@code null} if none.
46 * <p>A single-value header will be exposed as an array with a single element.
47 * @since 3.0
48 * @see javax.servlet.http.HttpServletRequest#getHeaders(String)
49 */
50 String[] getHeaderValues(String headerName);
51
52 /**
53 * Return a Iterator over request header names.
54 * @since 3.0
55 * @see javax.servlet.http.HttpServletRequest#getHeaderNames()
56 */
57 Iterator<String> getHeaderNames();
58
59 /**
60 * Return the request parameter of the given name, or {@code null} if none.
61 * <p>Retrieves the first parameter value in case of a multi-value parameter.
62 * @see javax.servlet.http.HttpServletRequest#getParameter(String)
63 */
64 String getParameter(String paramName);
65
66 /**
67 * Return the request parameter values for the given parameter name,
68 * or {@code null} if none.
69 * <p>A single-value parameter will be exposed as an array with a single element.
70 * @see javax.servlet.http.HttpServletRequest#getParameterValues(String)
71 */
72 String[] getParameterValues(String paramName);
73
74 /**
75 * Return a Iterator over request parameter names.
76 * @see javax.servlet.http.HttpServletRequest#getParameterNames()
77 * @since 3.0
78 */
79 Iterator<String> getParameterNames();
80
81 /**
82 * Return a immutable Map of the request parameters, with parameter names as map keys
83 * and parameter values as map values. The map values will be of type String array.
84 * <p>A single-value parameter will be exposed as an array with a single element.
85 * @see javax.servlet.http.HttpServletRequest#getParameterMap()
86 */
87 Map<String, String[]> getParameterMap();
88
89 /**
90 * Return the primary Locale for this request.
91 * @see javax.servlet.http.HttpServletRequest#getLocale()
92 */
93 Locale getLocale();
94
95 /**
96 * Return the context path for this request
97 * (usually the base path that the current web application is mapped to).
98 * @see javax.servlet.http.HttpServletRequest#getContextPath()
99 */
100 String getContextPath();
101
102 /**
103 * Return the remote user for this request, if any.
104 * @see javax.servlet.http.HttpServletRequest#getRemoteUser()
105 */
106 String getRemoteUser();
107
108 /**
109 * Return the user principal for this request, if any.
110 * @see javax.servlet.http.HttpServletRequest#getUserPrincipal()
111 */
112 Principal getUserPrincipal();
113
114 /**
115 * Determine whether the user is in the given role for this request.
116 * @see javax.servlet.http.HttpServletRequest#isUserInRole(String)
117 */
118 boolean isUserInRole(String role);
119
120 /**
121 * Return whether this request has been sent over a secure transport
122 * mechanism (such as SSL).
123 * @see javax.servlet.http.HttpServletRequest#isSecure()
124 */
125 boolean isSecure();
126
127 /**
128 * Check whether the request qualifies as not modified given the
129 * supplied last-modified timestamp (as determined by the application).
130 * <p>This will also transparently set the appropriate response headers,
131 * for both the modified case and the not-modified case.
132 * <p>Typical usage:
133 * <pre class="code">
134 * public String myHandleMethod(WebRequest webRequest, Model model) {
135 * long lastModified = // application-specific calculation
136 * if (request.checkNotModified(lastModified)) {
137 * // shortcut exit - no further processing necessary
138 * return null;
139 * }
140 * // further request processing, actually building content
141 * model.addAttribute(...);
142 * return "myViewName";
143 * }</pre>
144 * <p><strong>Note:</strong> that you typically want to use either
145 * this {@code #checkNotModified(long)} method; or
146 * {@link #checkNotModified(String)}, but not both.
147 * <p>If the "If-Modified-Since" header is set but cannot be parsed
148 * to a date value, this method will ignore the header and proceed
149 * with setting the last-modified timestamp on the response.
150 * @param lastModifiedTimestamp the last-modified timestamp that
151 * the application determined for the underlying resource
152 * @return whether the request qualifies as not modified,
153 * allowing to abort request processing and relying on the response
154 * telling the client that the content has not been modified
155 */
156 boolean checkNotModified(long lastModifiedTimestamp);
157
158 /**
159 * Check whether the request qualifies as not modified given the
160 * supplied {@code ETag} (entity tag), as determined by the application.
161 * <p>This will also transparently set the appropriate response headers,
162 * for both the modified case and the not-modified case.
163 * <p>Typical usage:
164 * <pre class="code">
165 * public String myHandleMethod(WebRequest webRequest, Model model) {
166 * String eTag = // application-specific calculation
167 * if (request.checkNotModified(eTag)) {
168 * // shortcut exit - no further processing necessary
169 * return null;
170 * }
171 * // further request processing, actually building content
172 * model.addAttribute(...);
173 * return "myViewName";
174 * }</pre>
175 * <p><strong>Note:</strong> that you typically want to use either
176 * this {@code #checkNotModified(String)} method; or
177 * {@link #checkNotModified(long)}, but not both.
178 * @param etag the entity tag that the application determined
179 * for the underlying resource. This parameter will be padded
180 * with quotes (") if necessary.
181 * @return whether the request qualifies as not modified,
182 * allowing to abort request processing and relying on the response
183 * telling the client that the content has not been modified
184 */
185 boolean checkNotModified(String etag);
186
187 /**
188 * Get a short description of this request,
189 * typically containing request URI and session id.
190 * @param includeClientInfo whether to include client-specific
191 * information such as session id and user name
192 * @return the requested description as String
193 */
194 String getDescription(boolean includeClientInfo);
195
196 }