Polish

spring-web/src/main/java/org/springframework/web/bind/annotation/CrossOrigin.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2016 the original author or authors.
+ * Copyright 2002-2017 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.
@@ -26,17 +26,15 @@ import org.springframework.core.annotation.AliasFor;
 import org.springframework.web.cors.CorsConfiguration;
 
 /**
- * Marks the annotated method or type as permitting cross origin requests.
+ * Annotation for permitting cross-origin requests on specific handler classes
+ * and/or handler methods. Processed if an appropriate {@code HandlerMapping}
+ * is configured.
  *
- * <p>By default all origins and headers are permitted, credentials are not allowed,
+ * <p>Both Spring Web MVC and Spring WebFlux support this annotation through the
- * and the maximum age is set to 1800 seconds (30 minutes). The list of HTTP
+ * {@code RequestMappingHandlerMapping} in their respective modules. The values
- * methods is set to the methods on the {@code @RequestMapping} if not
+ * from each type and method level pair of annotations are added to a
- * explicitly set on {@code @CrossOrigin}.
+ * {@link CorsConfiguration} and then default values are applied via
- *
+ * {@link CorsConfiguration#applyPermitDefaultValues()}.
- * <p><b>NOTE:</b> {@code @CrossOrigin} is processed if an appropriate
- * {@code HandlerMapping}-{@code HandlerAdapter} pair is configured such as the
- * {@code RequestMappingHandlerMapping}-{@code RequestMappingHandlerAdapter}
- * pair which are the default in the MVC Java config and the MVC namespace.
  *
  * @author Russell Allen
  * @author Sebastien Deleuze
@@ -48,27 +46,19 @@ import org.springframework.web.cors.CorsConfiguration;
 @Documented
 public @interface CrossOrigin {
 
-	/**
+	/** @deprecated as of Spring 5.0, in favor {@link CorsConfiguration#applyPermitDefaultValues} */
-	 * @deprecated as of Spring 5.0, in favor of using {@link CorsConfiguration#applyPermitDefaultValues}
-	 */
 	@Deprecated
 	String[] DEFAULT_ORIGINS = { "*" };
 
-	/**
+	/** @deprecated as of Spring 5.0, in favor {@link CorsConfiguration#applyPermitDefaultValues} */
-	 * @deprecated as of Spring 5.0, in favor of using {@link CorsConfiguration#applyPermitDefaultValues}
-	 */
 	@Deprecated
 	String[] DEFAULT_ALLOWED_HEADERS = { "*" };
 
-	/**
+	/** @deprecated as of Spring 5.0, in favor {@link CorsConfiguration#applyPermitDefaultValues} */
-	 * @deprecated as of Spring 5.0, in favor of using {@link CorsConfiguration#applyPermitDefaultValues}
-	 */
 	@Deprecated
 	boolean DEFAULT_ALLOW_CREDENTIALS = false;
 
-	/**
+	/** @deprecated as of Spring 5.0, in favor {@link CorsConfiguration#applyPermitDefaultValues} */
-	 * @deprecated as of Spring 5.0, in favor of using {@link CorsConfiguration#applyPermitDefaultValues}
-	 */
 	@Deprecated
 	long DEFAULT_MAX_AGE = 1800;
 
@@ -80,62 +70,69 @@ public @interface CrossOrigin {
 	String[] value() default {};
 
 	/**
-	 * List of allowed origins, e.g. {@code "http://domain1.com"}.
+	 * The list of allowed origins that be specific origins, e.g.
-	 * <p>These values are placed in the {@code Access-Control-Allow-Origin}
+	 * {@code "http://domain1.com"}, or {@code "*"} for all origins.
-	 * header of both the pre-flight response and the actual response.
+	 * <p>A matched origin is listed in the {@code Access-Control-Allow-Origin}
-	 * {@code "*"} means that all origins are allowed.
+	 * response header of preflight actual CORS requests.
-	 * <p>If undefined, all origins are allowed.
+	 * <p>By default all origins are allowed.
 	 * @see #value
 	 */
 	@AliasFor("value")
 	String[] origins() default {};
 
 	/**
-	 * List of request headers that can be used during the actual request.
+	 * The list of request headers that are permitted in actual requests,
-	 * <p>This property controls the value of the pre-flight response's
+	 * possibly {@code "*"}  to allow all headers.
-	 * {@code Access-Control-Allow-Headers} header.
+	 * <p>Allowed headers are listed in the {@code Access-Control-Allow-Headers}
-	 * {@code "*"}  means that all headers requested by the client are allowed.
+	 * response header of preflight requests.
-	 * <p>If undefined, all requested headers are allowed.
+	 * <p>A header name is not required to be listed if it is one of:
+	 * {@code Cache-Control}, {@code Content-Language}, {@code Expires},
+	 * {@code Last-Modified}, or {@code Pragma} as per the CORS spec.
+	 * <p>By default all requested headers are allowed.
 	 */
 	String[] allowedHeaders() default {};
 
 	/**
-	 * List of response headers that the user-agent will allow the client to access.
+	 * The List of response headers that the user-agent will allow the client
-	 * <p>This property controls the value of actual response's
+	 * to access on an actual response, other than "simple" headers, i.e.
-	 * {@code Access-Control-Expose-Headers} header.
+	 * {@code Cache-Control}, {@code Content-Language}, {@code Content-Type},
-	 * <p>If undefined, an empty exposed header list is used.
+	 * {@code Expires}, {@code Last-Modified}, or {@code Pragma},
+	 * <p>Exposed headers are listed in the {@code Access-Control-Expose-Headers}
+	 * response header of actual CORS requests.
+	 * <p>By default no headers are listed as exposed.
 	 */
 	String[] exposedHeaders() default {};
 
 	/**
-	 * List of supported HTTP request methods, e.g.
+	 * The list of supported HTTP request methods.
-	 * {@code "{RequestMethod.GET, RequestMethod.POST}"}.
+	 * <p>By default the supported methods are the same as the ones to which a
-	 * <p>Methods specified here override those specified via {@code RequestMapping}.
+	 * controller method is mapped.
-	 * <p>If undefined, methods defined by {@link RequestMapping} annotation
-	 * are used.
 	 */
 	RequestMethod[] methods() default {};
 
 	/**
-	 * Whether the browser should include any cookies associated with the
+	 * Whether the browser should send credentials, such as cookies along with
-	 * domain of the request being annotated. Be aware that enabling this option could
+	 * cross domain requests, to the annotated endpoint. The configured value is
-	 * increase the surface attack of the web application (for example via exposing
+	 * set on the {@code Access-Control-Allow-Credentials} response header of
-	 * sensitive user-specific information like CSRF tokens).
+	 * preflight requests.
-	 * <p>Set to {@code "true"} means that the pre-flight response will include the header
+	 * <p><strong>NOTE:</strong> Be aware that this option establishes a high
-	 * {@code Access-Control-Allow-Credentials=true} so such cookies should be included.
+	 * level of trust with the configured domains and also increases the surface
-	 * <p>If undefined or set to {@code "false"}, such header is not included and
+	 * attack of the web application by exposing sensitive user-specific
-	 * credentials are not allowed.
+	 * information such as cookies and CSRF tokens.
+	 * <p>By default this is not set in which case the
+	 * {@code Access-Control-Allow-Credentials} header is also not set and
+	 * credentials are therefore not allowed.
 	 */
 	String allowCredentials() default "";
 
 	/**
-	 * The maximum age (in seconds) of the cache duration for pre-flight responses.
+	 * The maximum age (in seconds) of the cache duration for preflight responses.
 	 * <p>This property controls the value of the {@code Access-Control-Max-Age}
-	 * header in the pre-flight response.
+	 * response header of preflight requests.
-	 * <p>Setting this to a reasonable value can reduce the number of pre-flight
+	 * <p>Setting this to a reasonable value can reduce the number of preflight
 	 * request/response interactions required by the browser.
 	 * A negative value means <em>undefined</em>.
-	 * <p>If undefined, max age is set to {@code 1800} seconds (i.e., 30 minutes).
+	 * <p>By default this is set to {@code 1800} seconds (30 minutes).
 	 */
 	long maxAge() default -1;
 

spring-web/src/main/java/org/springframework/web/cors/CorsConfiguration.java

@@ -35,24 +35,20 @@ import org.springframework.util.StringUtils;
  *
  * <p>By default a newly created {@code CorsConfiguration} does not permit any
  * cross-origin requests and must be configured explicitly to indicate what
- * should be allowed.
+ * should be allowed. Use {@link #applyPermitDefaultValues()} to flip the
- *
+ * initialization model to start with open defaults that permit all cross-origin
- * <p>Use {@link #applyPermitDefaultValues()} to flip the initialization model
+ * requests for GET, HEAD, and POST requests.
- * to start with open defaults that permit all cross-origin requests for GET,
- * HEAD, and POST requests.
  *
  * @author Sebastien Deleuze
  * @author Rossen Stoyanchev
  * @author Juergen Hoeller
  * @author Sam Brannen
  * @since 4.2
- * @see <a href="http://www.w3.org/TR/cors/">CORS W3C recommendation</a>
+ * @see <a href="http://www.w3.org/TR/cors/">CORS spec</a>
  */
 public class CorsConfiguration {
 
-	/**
+	/** Wildcard representing <em>all</em> origins, methods, or headers. */
-	 * Wildcard representing <em>all</em> origins, methods, or headers.
-	 */
 	public static final String ALL = "*";
 
 	private static final List<HttpMethod> DEFAULT_METHODS;
@@ -321,7 +317,7 @@ public class CorsConfiguration {
 	 *
 	 * <p>The following defaults are applied if not already set:
 	 * <ul>
-	 *     <li>Allow all origins, i.e. {@code "*"}.</li>
+	 *     <li>Allow all origins.</li>
 	 *     <li>Allow "simple" methods {@code GET}, {@code HEAD} and {@code POST}.</li>
 	 *     <li>Allow all headers.</li>
 	 *     <li>Set max age to 1800 seconds (30 minutes).</li>

spring-webflux/src/main/java/org/springframework/web/reactive/config/CorsRegistration.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2016 the original author or authors.
+ * Copyright 2002-2017 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.
@@ -22,10 +22,8 @@ import java.util.Arrays;
 import org.springframework.web.cors.CorsConfiguration;
 
 /**
- * Assists with the creation of a {@link CorsConfiguration} instance mapped to
+ * Assists with the creation of a {@link CorsConfiguration} instance for a given
- * a path pattern. By default all origins, headers, and credentials for
+ * URL path pattern.
- * {@code GET}, {@code HEAD}, and {@code POST} requests are allowed while the
- * max age is set to 30 minutes.
  *
  * @author Sebastien Deleuze
  * @author Rossen Stoyanchev
@@ -39,15 +37,6 @@ public class CorsRegistration {
 	private final CorsConfiguration config;
 
 
-	/**
-	 * Create a new {@link CorsRegistration} that allows all origins, headers, and
-	 * credentials for {@code GET}, {@code HEAD}, and {@code POST} requests with
-	 * max age set to 1800 seconds (30 minutes) for the specified path.
-	 *
-	 * @param pathPattern the path that the CORS configuration should apply to;
-	 * exact path mapping URIs (such as {@code "/admin"}) are supported as well
-	 * as Ant-style path patterns (such as {@code "/admin/**"}).
-	 */
 	public CorsRegistration(String pathPattern) {
 		this.pathPattern = pathPattern;
 		this.config = new CorsConfiguration().applyPermitDefaultValues();
@@ -55,8 +44,10 @@ public class CorsRegistration {
 
 
 	/**
-	 * Set the origins to allow, e.g. {@code "http://domain1.com"}.
+	 * The list of allowed origins that be specific origins, e.g.
-	 * <p>The special value {@code "*"} allows all domains.
+	 * {@code "http://domain1.com"}, or {@code "*"} for all origins.
+	 * <p>A matched origin is listed in the {@code Access-Control-Allow-Origin}
+	 * response header of preflight actual CORS requests.
 	 * <p>By default all origins are allowed.
 	 */
 	public CorsRegistration allowedOrigins(String... origins) {
@@ -102,6 +93,24 @@ public class CorsRegistration {
 		return this;
 	}
 
+	/**
+	 * Whether the browser should send credentials, such as cookies along with
+	 * cross domain requests, to the annotated endpoint. The configured value is
+	 * set on the {@code Access-Control-Allow-Credentials} response header of
+	 * preflight requests.
+	 * <p><strong>NOTE:</strong> Be aware that this option establishes a high
+	 * level of trust with the configured domains and also increases the surface
+	 * attack of the web application by exposing sensitive user-specific
+	 * information such as cookies and CSRF tokens.
+	 * <p>By default this is not set in which case the
+	 * {@code Access-Control-Allow-Credentials} header is also not set and
+	 * credentials are therefore not allowed.
+	 */
+	public CorsRegistration allowCredentials(boolean allowCredentials) {
+		this.config.setAllowCredentials(allowCredentials);
+		return this;
+	}
+
 	/**
 	 * Configure how long in seconds the response from a pre-flight request
 	 * can be cached by clients.
@@ -112,17 +121,6 @@ public class CorsRegistration {
 		return this;
 	}
 
-	/**
-	 * Whether user credentials are supported. Be aware that enabling this option
-	 * could increase the surface attack of the web application (for example via
-	 * exposing sensitive user-specific information like CSRF tokens).
-	 * <p>By default credentials are not allowed.
-	 */
-	public CorsRegistration allowCredentials(boolean allowCredentials) {
-		this.config.setAllowCredentials(allowCredentials);
-		return this;
-	}
-
 	protected String getPathPattern() {
 		return this.pathPattern;
 	}

spring-webflux/src/main/java/org/springframework/web/reactive/config/CorsRegistry.java

@@ -24,10 +24,11 @@ import java.util.Map;
 import org.springframework.web.cors.CorsConfiguration;
 
 /**
- * {@code CorsRegistry} assists with the registration of {@link CorsConfiguration}
+ * Assists with the registration of global, URL pattern based
- * mapped to a path pattern.
+ * {@link CorsConfiguration} mappings.
  *
  * @author Sebastien Deleuze
+ * @author Rossen Stoyanchev
  * @since 5.0
  */
 public class CorsRegistry {
@@ -41,9 +42,13 @@ public class CorsRegistry {
 	 * <p>Exact path mapping URIs (such as {@code "/admin"}) are supported as
 	 * well as Ant-style path patterns (such as {@code "/admin/**"}).
 	 *
-	 * <p>By default, all origins, all headers, credentials and {@code GET},
+	 * <p>The following defaults are applied to the {@link CorsRegistration}:
-	 * {@code HEAD}, and {@code POST} methods are allowed, and the max age
+	 * <ul>
-	 * is set to 30 minutes.
+	 *     <li>Allow all origins.</li>
+	 *     <li>Allow "simple" methods {@code GET}, {@code HEAD} and {@code POST}.</li>
+	 *     <li>Allow all headers.</li>
+	 *     <li>Set max age to 1800 seconds (30 minutes).</li>
+	 * </ul>
 	 */
 	public CorsRegistration addMapping(String pathPattern) {
 		CorsRegistration registration = new CorsRegistration(pathPattern);

spring-webmvc/src/main/java/org/springframework/web/servlet/config/annotation/CorsRegistration.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2016 the original author or authors.
+ * Copyright 2002-2017 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.
@@ -21,10 +21,8 @@ import java.util.Arrays;
 import org.springframework.web.cors.CorsConfiguration;
 
 /**
- * Assists with the creation of a {@link CorsConfiguration} instance mapped to
+ * Assists with the creation of a {@link CorsConfiguration} instance for a given
- * a path pattern. By default all origins, headers, and credentials for
+ * URL path pattern.
- * {@code GET}, {@code HEAD}, and {@code POST} requests are allowed while the
- * max age is set to 30 minutes.
  *
  * @author Sebastien Deleuze
  * @author Rossen Stoyanchev
@@ -40,14 +38,6 @@ public class CorsRegistration {
 	private final CorsConfiguration config;
 
 
-	/**
-	 * Create a new {@link CorsRegistration} that allows all origins, headers, and
-	 * credentials for {@code GET}, {@code HEAD}, and {@code POST} requests with
-	 * max age set to 1800 seconds (30 minutes) for the specified path.
-	 * @param pathPattern the path that the CORS configuration should apply to;
-	 * exact path mapping URIs (such as {@code "/admin"}) are supported as well
-	 * as Ant-style path patterns (such as {@code "/admin/**"}).
-	 */
 	public CorsRegistration(String pathPattern) {
 		this.pathPattern = pathPattern;
 		// Same implicit default values as the @CrossOrigin annotation + allows simple methods
@@ -56,8 +46,10 @@ public class CorsRegistration {
 
 
 	/**
-	 * Set the origins to allow, e.g. {@code "http://domain1.com"}.
+	 * The list of allowed origins that be specific origins, e.g.
-	 * <p>The special value {@code "*"} allows all domains.
+	 * {@code "http://domain1.com"}, or {@code "*"} for all origins.
+	 * <p>A matched origin is listed in the {@code Access-Control-Allow-Origin}
+	 * response header of preflight actual CORS requests.
 	 * <p>By default, all origins are allowed.
 	 */
 	public CorsRegistration allowedOrigins(String... origins) {
@@ -68,9 +60,9 @@ public class CorsRegistration {
 
 	/**
 	 * Set the HTTP methods to allow, e.g. {@code "GET"}, {@code "POST"}, etc.
-	 * <p>The special value {@code "*"} allows all methods.
+	 * The special value {@code "*"} allows all methods.
-	 * <p>By default "simple" methods {@code GET}, {@code HEAD}, and {@code POST}
+	 * <p>By default "simple" methods, i.e. {@code GET}, {@code HEAD}, and
-	 * are allowed.
+	 * {@code POST} are allowed.
 	 */
 	public CorsRegistration allowedMethods(String... methods) {
 		this.config.setAllowedMethods(Arrays.asList(methods));
@@ -78,9 +70,9 @@ public class CorsRegistration {
 	}
 
 	/**
-	 * Set the list of headers that a pre-flight request can list as allowed
+	 * Set the list of headers that a preflight request can list as allowed
-	 * for use during an actual request.
+	 * for use during an actual request. The special value {@code "*"} may be
-	 * <p>The special value {@code "*"} may be used to allow all headers.
+	 * used to allow all headers.
 	 * <p>A header name is not required to be listed if it is one of:
 	 * {@code Cache-Control}, {@code Content-Language}, {@code Expires},
 	 * {@code Last-Modified}, or {@code Pragma} as per the CORS spec.
@@ -104,6 +96,24 @@ public class CorsRegistration {
 		return this;
 	}
 
+	/**
+	 * Whether the browser should send credentials, such as cookies along with
+	 * cross domain requests, to the annotated endpoint. The configured value is
+	 * set on the {@code Access-Control-Allow-Credentials} response header of
+	 * preflight requests.
+	 * <p><strong>NOTE:</strong> Be aware that this option establishes a high
+	 * level of trust with the configured domains and also increases the surface
+	 * attack of the web application by exposing sensitive user-specific
+	 * information such as cookies and CSRF tokens.
+	 * <p>By default this is not set in which case the
+	 * {@code Access-Control-Allow-Credentials} header is also not set and
+	 * credentials are therefore not allowed.
+	 */
+	public CorsRegistration allowCredentials(boolean allowCredentials) {
+		this.config.setAllowCredentials(allowCredentials);
+		return this;
+	}
+
 	/**
 	 * Configure how long in seconds the response from a pre-flight request
 	 * can be cached by clients.
@@ -114,17 +124,6 @@ public class CorsRegistration {
 		return this;
 	}
 
-	/**
-	 * Whether user credentials are supported. Be aware that enabling this option
-	 * could increase the surface attack of the web application (for example via
-	 * exposing sensitive user-specific information like CSRF tokens).
-	 * <p>By default credentials are not allowed.
-	 */
-	public CorsRegistration allowCredentials(boolean allowCredentials) {
-		this.config.setAllowCredentials(allowCredentials);
-		return this;
-	}
-
 	protected String getPathPattern() {
 		return this.pathPattern;
 	}

spring-webmvc/src/main/java/org/springframework/web/servlet/config/annotation/CorsRegistry.java

@@ -24,10 +24,11 @@ import java.util.Map;
 import org.springframework.web.cors.CorsConfiguration;
 
 /**
- * {@code CorsRegistry} assists with the registration of {@link CorsConfiguration}
+ * Assists with the registration of global, URL pattern based
- * mapped to a path pattern.
+ * {@link CorsConfiguration} mappings.
  *
  * @author Sebastien Deleuze
+ * @author Rossen Stoyanchev
  * @since 4.2
  * @see CorsRegistration
  */
@@ -38,14 +39,20 @@ public class CorsRegistry {
 
 	/**
 	 * Enable cross-origin request handling for the specified path pattern.
+	 *
 	 * <p>Exact path mapping URIs (such as {@code "/admin"}) are supported as
 	 * well as Ant-style path patterns (such as {@code "/admin/**"}).
 	 * <p>By default, all origins, all headers, credentials and {@code GET},
 	 * {@code HEAD}, and {@code POST} methods are allowed, and the max age
 	 * is set to 30 minutes.
-	 * @param pathPattern the path pattern to enable CORS handling for
+	 *
-	 * @return CorsRegistration the corresponding registration object,
+	 * <p>The following defaults are applied to the {@link CorsRegistration}:
-	 * allowing for further fine-tuning
+	 * <ul>
+	 *     <li>Allow all origins.</li>
+	 *     <li>Allow "simple" methods {@code GET}, {@code HEAD} and {@code POST}.</li>
+	 *     <li>Allow all headers.</li>
+	 *     <li>Set max age to 1800 seconds (30 minutes).</li>
+	 * </ul>
 	 */
 	public CorsRegistration addMapping(String pathPattern) {
 		CorsRegistration registration = new CorsRegistration(pathPattern);

spring-webmvc/src/main/resources/org/springframework/web/servlet/config/spring-mvc.xsd

@@ -1310,8 +1310,11 @@
 					<xsd:annotation>
 						<xsd:documentation><![CDATA[
 	Enable cross origin requests processing on the specified path pattern.
-	By default, all origins, GET HEAD POST methods, all headers and credentials
+	The following defaults are applied to the resulting CorsRegistration:
-	are allowed and max age is set to 30 minutes.
+	 - Allow all origins.
+	 - Allow "simple" methods {@code GET}, {@code HEAD} and {@code POST}.
+	 - Allow all headers.
+	 - Set max age to 1800 seconds (30 minutes).
 						]]></xsd:documentation>
 					</xsd:annotation>
 					<xsd:complexType>
@@ -1361,7 +1364,19 @@
 						<xsd:attribute name="allow-credentials" type="xsd:boolean">
 							<xsd:annotation>
 								<xsd:documentation><![CDATA[
-	Whether user credentials are supported (true by default).
+	Whether the browser should send credentials, such as cookies along with
+	cross domain requests, to the annotated endpoint. The configured value is
+	set on the "Access-Control-Allow-Credentials" response header of
+	preflight requests.
+
+	NOTE: Be aware that this option establishes a high
+	level of trust with the configured domains and also increases the surface
+	attack of the web application by exposing sensitive user-specific
+	information such as cookies and CSRF tokens.
+
+	By default this is not set in which case the
+	"Access-Control-Allow-Credentials" header is also not set and
+	credentials are therefore not allowed.
 								]]></xsd:documentation>
 							</xsd:annotation>
 						</xsd:attribute>

src/docs/asciidoc/web/webflux-cors.adoc

@@ -59,11 +59,14 @@ all global and all local origins. The only exception are those attributes where
 single value can be accepted such as `allowCredentials` and `maxAge`, in which case the
 local overrides the global value.
 
+[TIP]
+====
 To learn more from the source or make advanced customizations, check:
 
 * `CorsConfiguration`
 * `CorsProcessor`, `DefaultCorsProcessor`
 * `AbstractHandlerMapping`
+====
 
 
 

src/docs/asciidoc/web/webmvc-cors.adoc

@@ -59,11 +59,14 @@ all global and all local origins. The only exception are those attributes where
 single value can be accepted such as `allowCredentials` and `maxAge`, in which case the
 local overrides the global value.
 
+[TIP]
+====
 To learn more from the source or make advanced customizations, check:
 
 * `CorsConfiguration`
 * `CorsProcessor`, `DefaultCorsProcessor`
 * `AbstractHandlerMapping`
+====