/*
 * Copyright 2002-2020 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.springframework.web.context.request;

import java.security.Principal;
import java.util.Iterator;
import java.util.Locale;
import java.util.Map;

import org.springframework.lang.Nullable;

Generic interface for a web request. Mainly intended for generic web
request interceptors, giving them access to general request metadata,
not for actual handling of the request.
Author:
Juergen Hoeller, Brian Clozel
See Also:
WebRequestInterceptor
Since:
2.0/**
 * Generic interface for a web request. Mainly intended for generic web
 * request interceptors, giving them access to general request metadata,
 * not for actual handling of the request.
 *
 * @author Juergen Hoeller
 * @author Brian Clozel
 * @since 2.0
 * @see WebRequestInterceptor
 */
public interface WebRequest extends RequestAttributes {

	
Return the request header of the given name, or null if none. 
Retrieves the first header value in case of a multi-value header.
See Also:
getHeader.getHeader(String)
Since:
3.0/**
	 * Return the request header of the given name, or {@code null} if none.
	 * <p>Retrieves the first header value in case of a multi-value header.
	 * @since 3.0
	 * @see javax.servlet.http.HttpServletRequest#getHeader(String)
	 */
	@Nullable
	String getHeader(String headerName);

	
Return the request header values for the given header name, or null if none. 
A single-value header will be exposed as an array with a single element.
See Also:
getHeaders.getHeaders(String)
Since:
3.0/**
	 * Return the request header values for the given header name,
	 * or {@code null} if none.
	 * <p>A single-value header will be exposed as an array with a single element.
	 * @since 3.0
	 * @see javax.servlet.http.HttpServletRequest#getHeaders(String)
	 */
	@Nullable
	String[] getHeaderValues(String headerName);

	
Return a Iterator over request header names.
See Also:
getHeaderNames.getHeaderNames()
Since:
3.0/**
	 * Return a Iterator over request header names.
	 * @since 3.0
	 * @see javax.servlet.http.HttpServletRequest#getHeaderNames()
	 */
	Iterator<String> getHeaderNames();

	
Return the request parameter of the given name, or null if none. 
Retrieves the first parameter value in case of a multi-value parameter.
See Also:
getParameter.getParameter(String)/**
	 * Return the request parameter of the given name, or {@code null} if none.
	 * <p>Retrieves the first parameter value in case of a multi-value parameter.
	 * @see javax.servlet.http.HttpServletRequest#getParameter(String)
	 */
	@Nullable
	String getParameter(String paramName);

	
Return the request parameter values for the given parameter name, or null if none. 
A single-value parameter will be exposed as an array with a single element.
See Also:
getParameterValues.getParameterValues(String)/**
	 * Return the request parameter values for the given parameter name,
	 * or {@code null} if none.
	 * <p>A single-value parameter will be exposed as an array with a single element.
	 * @see javax.servlet.http.HttpServletRequest#getParameterValues(String)
	 */
	@Nullable
	String[] getParameterValues(String paramName);

	
Return a Iterator over request parameter names.
See Also:
getParameterNames.getParameterNames()
Since:
3.0/**
	 * Return a Iterator over request parameter names.
	 * @since 3.0
	 * @see javax.servlet.http.HttpServletRequest#getParameterNames()
	 */
	Iterator<String> getParameterNames();

	
Return a immutable Map of the request parameters, with parameter names as map keys
and parameter values as map values. The map values will be of type String array.
A single-value parameter will be exposed as an array with a single element.
See Also:
getParameterMap.getParameterMap()/**
	 * Return a immutable Map of the request parameters, with parameter names as map keys
	 * and parameter values as map values. The map values will be of type String array.
	 * <p>A single-value parameter will be exposed as an array with a single element.
	 * @see javax.servlet.http.HttpServletRequest#getParameterMap()
	 */
	Map<String, String[]> getParameterMap();

	
Return the primary Locale for this request.
See Also:
getLocale.getLocale()/**
	 * Return the primary Locale for this request.
	 * @see javax.servlet.http.HttpServletRequest#getLocale()
	 */
	Locale getLocale();

	
Return the context path for this request
(usually the base path that the current web application is mapped to).
See Also:
getContextPath.getContextPath()/**
	 * Return the context path for this request
	 * (usually the base path that the current web application is mapped to).
	 * @see javax.servlet.http.HttpServletRequest#getContextPath()
	 */
	String getContextPath();

	
Return the remote user for this request, if any.
See Also:
getRemoteUser.getRemoteUser()/**
	 * Return the remote user for this request, if any.
	 * @see javax.servlet.http.HttpServletRequest#getRemoteUser()
	 */
	@Nullable
	String getRemoteUser();

	
Return the user principal for this request, if any.
See Also:
getUserPrincipal.getUserPrincipal()/**
	 * Return the user principal for this request, if any.
	 * @see javax.servlet.http.HttpServletRequest#getUserPrincipal()
	 */
	@Nullable
	Principal getUserPrincipal();

	
Determine whether the user is in the given role for this request.
See Also:
isUserInRole.isUserInRole(String)/**
	 * Determine whether the user is in the given role for this request.
	 * @see javax.servlet.http.HttpServletRequest#isUserInRole(String)
	 */
	boolean isUserInRole(String role);

	
Return whether this request has been sent over a secure transport
mechanism (such as SSL).
See Also:
isSecure.isSecure()/**
	 * Return whether this request has been sent over a secure transport
	 * mechanism (such as SSL).
	 * @see javax.servlet.http.HttpServletRequest#isSecure()
	 */
	boolean isSecure();

	
Check whether the requested resource has been modified given the
supplied last-modified timestamp (as determined by the application).
This will also transparently set the "Last-Modified" response header
and HTTP status when applicable.
Typical usage:
public String myHandleMethod(WebRequest request, Model model) {
  long lastModified = // application-specific calculation
  if (request.checkNotModified(lastModified)) {
    // shortcut exit - no further processing necessary
    return null;
  }
  // further request processing, actually building content
  model.addAttribute(...);
  return "myViewName";
}
This method works with conditional GET/HEAD requests, but
also with conditional POST/PUT/DELETE requests.
Note: you can use either this #checkNotModified(long) method; or checkNotModified(String). If you want enforce both a strong entity tag and a Last-Modified value, as recommended by the HTTP specification, then you should use checkNotModified(String, long). 
If the "If-Modified-Since" header is set but cannot be parsed
to a date value, this method will ignore the header and proceed
with setting the last-modified timestamp on the response.
Params:
lastModifiedTimestamp – the last-modified timestamp in
milliseconds that the application determined for the underlying
resource
Returns:
whether the request qualifies as not modified,
allowing to abort request processing and relying on the response
telling the client that the content has not been modified/**
	 * Check whether the requested resource has been modified given the
	 * supplied last-modified timestamp (as determined by the application).
	 * <p>This will also transparently set the "Last-Modified" response header
	 * and HTTP status when applicable.
	 * <p>Typical usage:
	 * <pre class="code">
	 * public String myHandleMethod(WebRequest request, Model model) {
	 *   long lastModified = // application-specific calculation
	 *   if (request.checkNotModified(lastModified)) {
	 *     // shortcut exit - no further processing necessary
	 *     return null;
	 *   }
	 *   // further request processing, actually building content
	 *   model.addAttribute(...);
	 *   return "myViewName";
	 * }</pre>
	 * <p>This method works with conditional GET/HEAD requests, but
	 * also with conditional POST/PUT/DELETE requests.
	 * <p><strong>Note:</strong> you can use either
	 * this {@code #checkNotModified(long)} method; or
	 * {@link #checkNotModified(String)}. If you want enforce both
	 * a strong entity tag and a Last-Modified value,
	 * as recommended by the HTTP specification,
	 * then you should use {@link #checkNotModified(String, long)}.
	 * <p>If the "If-Modified-Since" header is set but cannot be parsed
	 * to a date value, this method will ignore the header and proceed
	 * with setting the last-modified timestamp on the response.
	 * @param lastModifiedTimestamp the last-modified timestamp in
	 * milliseconds that the application determined for the underlying
	 * resource
	 * @return whether the request qualifies as not modified,
	 * allowing to abort request processing and relying on the response
	 * telling the client that the content has not been modified
	 */
	boolean checkNotModified(long lastModifiedTimestamp);

	
Check whether the requested resource has been modified given the supplied ETag (entity tag), as determined by the application. 
This will also transparently set the "ETag" response header
and HTTP status when applicable.
Typical usage:
public String myHandleMethod(WebRequest request, Model model) {
  String eTag = // application-specific calculation
  if (request.checkNotModified(eTag)) {
    // shortcut exit - no further processing necessary
    return null;
  }
  // further request processing, actually building content
  model.addAttribute(...);
  return "myViewName";
}
Note: you can use either this #checkNotModified(String) method; or checkNotModified(long). If you want enforce both a strong entity tag and a Last-Modified value, as recommended by the HTTP specification, then you should use checkNotModified(String, long). 
Params:
etag – the entity tag that the application determined
for the underlying resource. This parameter will be padded
with quotes (") if necessary.
Returns:
true if the request does not require further processing./**
	 * Check whether the requested resource has been modified given the
	 * supplied {@code ETag} (entity tag), as determined by the application.
	 * <p>This will also transparently set the "ETag" response header
	 * and HTTP status when applicable.
	 * <p>Typical usage:
	 * <pre class="code">
	 * public String myHandleMethod(WebRequest request, Model model) {
	 *   String eTag = // application-specific calculation
	 *   if (request.checkNotModified(eTag)) {
	 *     // shortcut exit - no further processing necessary
	 *     return null;
	 *   }
	 *   // further request processing, actually building content
	 *   model.addAttribute(...);
	 *   return "myViewName";
	 * }</pre>
	 * <p><strong>Note:</strong> you can use either
	 * this {@code #checkNotModified(String)} method; or
	 * {@link #checkNotModified(long)}. If you want enforce both
	 * a strong entity tag and a Last-Modified value,
	 * as recommended by the HTTP specification,
	 * then you should use {@link #checkNotModified(String, long)}.
	 * @param etag the entity tag that the application determined
	 * for the underlying resource. This parameter will be padded
	 * with quotes (") if necessary.
	 * @return true if the request does not require further processing.
	 */
	boolean checkNotModified(String etag);

	
Check whether the requested resource has been modified given the supplied ETag (entity tag) and last-modified timestamp, as determined by the application. 
This will also transparently set the "ETag" and "Last-Modified"
response headers, and HTTP status when applicable.
Typical usage:
public String myHandleMethod(WebRequest request, Model model) {
  String eTag = // application-specific calculation
  long lastModified = // application-specific calculation
  if (request.checkNotModified(eTag, lastModified)) {
    // shortcut exit - no further processing necessary
    return null;
  }
  // further request processing, actually building content
  model.addAttribute(...);
  return "myViewName";
}
This method works with conditional GET/HEAD requests, but
also with conditional POST/PUT/DELETE requests.
Note: The HTTP specification recommends setting both ETag and Last-Modified values, but you can also use #checkNotModified(String) or checkNotModified(long). 
Params:
etag – the entity tag that the application determined
for the underlying resource. This parameter will be padded
with quotes (") if necessary.
lastModifiedTimestamp – the last-modified timestamp in
milliseconds that the application determined for the underlying
resource
Returns:
true if the request does not require further processing.
Since:
4.2/**
	 * Check whether the requested resource has been modified given the
	 * supplied {@code ETag} (entity tag) and last-modified timestamp,
	 * as determined by the application.
	 * <p>This will also transparently set the "ETag" and "Last-Modified"
	 * response headers, and HTTP status when applicable.
	 * <p>Typical usage:
	 * <pre class="code">
	 * public String myHandleMethod(WebRequest request, Model model) {
	 *   String eTag = // application-specific calculation
	 *   long lastModified = // application-specific calculation
	 *   if (request.checkNotModified(eTag, lastModified)) {
	 *     // shortcut exit - no further processing necessary
	 *     return null;
	 *   }
	 *   // further request processing, actually building content
	 *   model.addAttribute(...);
	 *   return "myViewName";
	 * }</pre>
	 * <p>This method works with conditional GET/HEAD requests, but
	 * also with conditional POST/PUT/DELETE requests.
	 * <p><strong>Note:</strong> The HTTP specification recommends
	 * setting both ETag and Last-Modified values, but you can also
	 * use {@code #checkNotModified(String)} or
	 * {@link #checkNotModified(long)}.
	 * @param etag the entity tag that the application determined
	 * for the underlying resource. This parameter will be padded
	 * with quotes (") if necessary.
	 * @param lastModifiedTimestamp the last-modified timestamp in
	 * milliseconds that the application determined for the underlying
	 * resource
	 * @return true if the request does not require further processing.
	 * @since 4.2
	 */
	boolean checkNotModified(@Nullable String etag, long lastModifiedTimestamp);

	
Get a short description of this request,
typically containing request URI and session id.
Params:
includeClientInfo – whether to include client-specific
information such as session id and user name
Returns:
the requested description as String/**
	 * Get a short description of this request,
	 * typically containing request URI and session id.
	 * @param includeClientInfo whether to include client-specific
	 * information such as session id and user name
	 * @return the requested description as String
	 */
	String getDescription(boolean includeClientInfo);

}