Polish CORS documentation in the reference manual

Author: sbrannen

src/asciidoc/web-cors.adoc

@@ -5,19 +5,19 @@
 
 For security reasons, browsers prohibit AJAX calls to resources residing outside the
 current origin. For example, as you're checking your bank account in one tab, you
-could have the evil.com website in another tab. The scripts from evil.com should not
-be able to make AJAX requests to your bank API  (withdrawing money from your account!)
+could have the evil.com website open in another tab. The scripts from evil.com should not
+be able to make AJAX requests to your bank API (e.g., withdrawing money from your account!)
 using your credentials.
 
 http://en.wikipedia.org/wiki/Cross-origin_resource_sharing[Cross-origin resource sharing]
 (CORS) is a http://www.w3.org/TR/cors/[W3C specification] implemented by
 http://caniuse.com/#feat=cors[most browsers] that allows you to specify in a flexible
 way what kind of cross domain requests are authorized, instead of using some less secured
-and less powerful hacks like IFrame or JSONP.
+and less powerful hacks like IFRAME or JSONP.
 
 As of Spring Framework 4.2, CORS is supported out of the box. CORS requests
 (https://github.com/spring-projects/spring-framework/blob/master/spring-webmvc/src/main/java/org/springframework/web/servlet/FrameworkServlet.java#L906[including preflight ones with an `OPTIONS` method])
-are automatically dispatched to the various `HandlerMapping` registered. They handle
+are automatically dispatched to the various registered ++HandlerMapping++s. They handle
 CORS preflight requests and intercept CORS simple and actual requests thanks to a
 http://docs.spring.io/spring/docs/4.2.x/javadoc-api/org/springframework/web/cors/CorsProcessor.html[CorsProcessor]
 implementation (https://github.com/spring-projects/spring-framework/blob/master/spring-web/src/main/java/org/springframework/web/cors/DefaultCorsProcessor.java[DefaultCorsProcessor]
@@ -26,17 +26,18 @@ based on the CORS configuration you have provided.
 
 [NOTE]
 ====
-Since CORS requests are automatically dispatched, you *do not need* to change
-`DispatcherServlet` `dispatchOptionsRequest` init parameter value, using its default value
+Since CORS requests are automatically dispatched, you *do not need* to change the
+`DispatcherServlet` `dispatchOptionsRequest` init parameter value; using its default value
 (`false`) is the recommended approach.
 ====
 
 == Controller method CORS configuration
 
-You can add to your `@RequestMapping` annotated handler method a
+You can add an
 http://docs.spring.io/spring/docs/4.2.x/javadoc-api/org/springframework/web/bind/annotation/CrossOrigin.html[`@CrossOrigin`]
-annotation in order to enable CORS on it (by default `@CrossOrigin` allows all origins
-and the HTTP methods specified in the `@RequestMapping` annotation):
+annotation to your `@RequestMapping` annotated handler method in order to enable CORS on
+it. By default `@CrossOrigin` allows all origins and the HTTP methods specified in the
+`@RequestMapping` annotation:
 
 [source,java,indent=0]
 [subs="verbatim,quotes"]
@@ -51,7 +52,7 @@ public class AccountController {
 		// ...
 	}
 
-	@RequestMapping(method = RequestMethod.DELETE, value = "/{id}")
+	@RequestMapping(method = RequestMethod.DELETE, path = "/{id}")
 	public void remove(@PathVariable Long id) {
 		// ...
 	}
@@ -73,16 +74,19 @@ public class AccountController {
 		// ...
 	}
 
-	@RequestMapping(method = RequestMethod.DELETE, value = "/{id}")
+	@RequestMapping(method = RequestMethod.DELETE, path = "/{id}")
 	public void remove(@PathVariable Long id) {
 		// ...
 	}
 }
 ----
 
-In this example CORS support is enabled for both `retrieve()` and `remove()` handler methods, and you can also see how you can customize the CORS configuration using `@CrossOrigin` attributes.
+In the above example CORS support is enabled for both the `retrieve()` and the `remove()`
+handler methods, and you can also see how you can customize the CORS configuration using
+`@CrossOrigin` attributes.
 
-You can even use both controller and method level CORS configurations, Spring will then combine both annotation attributes to create a merged CORS configuration.
+You can even use both controller-level and method-level CORS configurations; Spring will
+then combine attributes from both annotations to create merged CORS configuration.
 
 [source,java,indent=0]
 [subs="verbatim,quotes"]
@@ -98,7 +102,7 @@ public class AccountController {
 		// ...
 	}
 
-	@RequestMapping(method = RequestMethod.DELETE, value = "/{id}")
+	@RequestMapping(method = RequestMethod.DELETE, path = "/{id}")
 	public void remove(@PathVariable Long id) {
 		// ...
 	}
@@ -109,8 +113,8 @@ public class AccountController {
 
 In addition to fine-grained, annotation-based configuration you'll probably want to
 define some global CORS configuration as well. This is similar to using filters but can
-be declared withing Spring MVC and combined with fine-grained `@CrossOrigin` configuration.
-By default all origins and `GET`, `HEAD` and `POST` methods are allowed.
+be declared within Spring MVC and combined with fine-grained `@CrossOrigin` configuration.
+By default all origins and `GET`, `HEAD`, and `POST` methods are allowed.
 
 === JavaConfig
 
@@ -154,7 +158,8 @@ public class WebConfig extends WebMvcConfigurerAdapter {
 
 === XML namespace
 
-This minimal XML configuration enable CORS on `/**` path pattern with the same default properties than the JavaConfig one:
+The following minimal XML configuration enables CORS for the `/**` path pattern with
+the same default properties as with the aforementioned JavaConfig examples:
 
 [source,xml,indent=0]
 [subs="verbatim"]
@@ -184,18 +189,18 @@ It is also possible to declare several CORS mappings with customized properties:
 </mvc:cors>
 ----
 
-== Advanced Customizations
+== Advanced Customization
 
 http://docs.spring.io/spring/docs/4.2.x/javadoc-api/org/springframework/web/cors/CorsConfiguration.html[CorsConfiguration]
 allows you to specify how the CORS requests should be processed: allowed origins, headers, methods, etc.
 It can be provided in various ways:
 
  * http://docs.spring.io/spring/docs/4.2.x/javadoc-api/org/springframework/web/servlet/handler/AbstractHandlerMapping.html#setCorsConfiguration-java.util.Map-[`AbstractHandlerMapping#setCorsConfiguration()`]
    allows to specify a `Map` with several http://docs.spring.io/spring/docs/4.2.x/javadoc-api/org/springframework/web/cors/CorsConfiguration.html[CorsConfiguration]
-   mapped on path patterns like `/api/**`
- * Subclasses can provide their own `CorsConfiguration` by overriding
-   `AbstractHandlerMapping#getCorsConfiguration(Object, HttpServletRequest)` method
- * Handlers can implement http://docs.spring.io/spring/docs/4.2.x/javadoc-api/org/springframework/web/cors/CorsConfigurationSource.html[`CorsConfigurationSource`]
+   instances mapped to path patterns like `/api/**`.
+ * Subclasses can provide their own `CorsConfiguration` by overriding the
+   `AbstractHandlerMapping#getCorsConfiguration(Object, HttpServletRequest)` method.
+ * Handlers can implement the http://docs.spring.io/spring/docs/4.2.x/javadoc-api/org/springframework/web/cors/CorsConfigurationSource.html[`CorsConfigurationSource`]
    interface (like https://github.com/spring-projects/spring-framework/blob/master/spring-webmvc/src/main/java/org/springframework/web/servlet/resource/ResourceHttpRequestHandler.java[`ResourceHttpRequestHandler`]
    now does) in order to provide a http://docs.spring.io/spring/docs/4.2.x/javadoc-api/org/springframework/web/cors/CorsConfiguration.html[CorsConfiguration]
-   for each request.
+   instance for each request.