Fix references and typos in Spring MVC Test Javadoc

This commit fixes numerous references to 'legacy' packages within the
Javadoc for the Spring MVC Test framework.

In addition, this commit improves examples in Javadoc, adds links to
related classes where appropriate, and removes unnecessary imports for
types that are only referenced within documentation.

Issue: SPR-13284

Author: sbrannen

spring-test/src/main/java/org/springframework/test/web/servlet/MockMvc.java

@@ -33,11 +33,14 @@
 /**
  * <strong>Main entry point for server-side Spring MVC test support.</strong>
  *
- * <p>Below is an example:
+ * <h3>Example</h3>
  *
  * <pre class="code">
- * static imports:
- * MockMvcBuilders.*, MockMvcRequestBuilders.*, MockMvcResultMatchers.*
+ * import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.*;
+ * import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*;
+ * import static org.springframework.test.web.servlet.setup.MockMvcBuilders.*;
+ *
+ * // ...
  *
  * WebApplicationContext wac = ...;
  *

spring-test/src/main/java/org/springframework/test/web/servlet/MockMvcBuilder.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2012 the original author or authors.
+ * Copyright 2002-2015 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.
@@ -17,10 +17,10 @@
 package org.springframework.test.web.servlet;
 
 /**
- * Builds a {@link MockMvc}.
+ * Builds a {@link MockMvc} instance.
  *
- * <p>See static, factory methods in
- * {@code org.springframework.test.web.server.setup.MockMvcBuilders}.
+ * <p>See static factory methods in
+ * {@link org.springframework.test.web.servlet.setup.MockMvcBuilders MockMvcBuilders}.
  *
  * @author Rossen Stoyanchev
  * @since 3.2

spring-test/src/main/java/org/springframework/test/web/servlet/RequestBuilder.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2012 the original author or authors.
+ * Copyright 2002-2015 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.
@@ -13,6 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+
 package org.springframework.test.web.servlet;
 
 import javax.servlet.ServletContext;
@@ -22,8 +23,8 @@
 /**
  * Builds a {@link MockHttpServletRequest}.
  *
- * <p>See static, factory methods in
- * {@code org.springframework.test.web.server.request.MockMvcRequestBuilders}.
+ * <p>See static factory methods in
+ * {@link org.springframework.test.web.servlet.request.MockMvcRequestBuilders MockMvcRequestBuilders}.
  *
  * @author Arjen Poutsma
  * @author Rossen Stoyanchev

spring-test/src/main/java/org/springframework/test/web/servlet/ResultActions.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2012 the original author or authors.
+ * Copyright 2002-2015 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,16 +21,18 @@
  * request.
  *
  * <p>See static factory methods in
- * {@code org.springframework.test.web.servlet.result.MockMvcResultMatchers}
- * {@code org.springframework.test.web.servlet.result.MockMvcResultHandlers}
+ * {@link org.springframework.test.web.servlet.result.MockMvcResultMatchers} and
+ * {@link org.springframework.test.web.servlet.result.MockMvcResultHandlers}.
  *
  * @author Rossen Stoyanchev
  * @since 3.2
  */
 public interface ResultActions {
 
 	/**
-	 * Provide an expectation. For example:
+	 * Perform an expectation.
+	 *
+	 * <h4>Example</h4>
 	 * <pre class="code">
 	 * static imports: MockMvcRequestBuilders.*, MockMvcResultMatchers.*
 	 *
@@ -51,7 +53,9 @@ public interface ResultActions {
 	ResultActions andExpect(ResultMatcher matcher) throws Exception;
 
 	/**
-	 * Provide a general action. For example:
+	 * Perform a general action.
+	 *
+	 * <h4>Example</h4>
 	 * <pre class="code">
 	 * static imports: MockMvcRequestBuilders.*, MockMvcResultMatchers.*
 	 *

spring-test/src/main/java/org/springframework/test/web/servlet/ResultHandler.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2012 the original author or authors.
+ * Copyright 2002-2015 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.
@@ -17,27 +17,37 @@
 package org.springframework.test.web.servlet;
 
 /**
- * Executes a generic action (e.g. printing debug information) on the result of
- * an executed request.
+ * A {@code ResultHandler} performs a generic action on the result of an
+ * executed request — for example, printing debug information.
  *
  * <p>See static factory methods in
- * {@code org.springframework.test.web.server.result.MockMvcResultHandlers}.
+ * {@link org.springframework.test.web.servlet.result.MockMvcResultHandlers
+ * MockMvcResultHandlers}.
  *
- * <p>Example:
+ * <h3>Example</h3>
  *
  * <pre class="code">
- * static imports: MockMvcRequestBuilders.*, MockMvcResultHandlers.*
+ * import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.*;
+ * import static org.springframework.test.web.servlet.result.MockMvcResultHandlers.*;
+ * import static org.springframework.test.web.servlet.setup.MockMvcBuilders.*;
+ *
+ * // ...
+ *
+ * WebApplicationContext wac = ...;
+ *
+ * MockMvc mockMvc = webAppContextSetup(wac).build();
  *
  * mockMvc.perform(get("/form")).andDo(print());
  * </pre>
  *
  * @author Rossen Stoyanchev
+ * @author Sam Brannen
  * @since 3.2
  */
 public interface ResultHandler {
 
 	/**
-	 * Apply the action on the given result.
+	 * Perform an action on the given result.
 	 *
 	 * @param result the result of the executed request
 	 * @throws Exception if a failure occurs

spring-test/src/main/java/org/springframework/test/web/servlet/ResultMatcher.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2012 the original author or authors.
+ * Copyright 2002-2015 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.
@@ -17,22 +17,33 @@
 package org.springframework.test.web.servlet;
 
 /**
- * Matches the result of an executed request against some expectation.
+ * A {@code ResultMatcher} matches the result of an executed request against
+ * some expectation.
  *
  * <p>See static factory methods in
- * {@code org.springframework.test.web.server.result.MockMvcResultMatchers}.
+ * {@link org.springframework.test.web.servlet.result.MockMvcResultMatchers
+ * MockMvcResultMatchers}.
  *
- * <p>Example:
+ * <h3>Example Using Status and Content Result Matchers</h3>
  *
  * <pre class="code">
- * static imports: MockMvcRequestBuilders.*, MockMvcResultMatchers.*
+ * import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.*;
+ * import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*;
+ * import static org.springframework.test.web.servlet.setup.MockMvcBuilders.*;
+ *
+ * // ...
+ *
+ * WebApplicationContext wac = ...;
+ *
+ * MockMvc mockMvc = webAppContextSetup(wac).build();
  *
  * mockMvc.perform(get("/form"))
- *   .andExpect(status.isOk())
+ *   .andExpect(status().isOk())
  *   .andExpect(content().mimeType(MediaType.APPLICATION_JSON));
  * </pre>
  *
  * @author Rossen Stoyanchev
+ * @author Sam Brannen
  * @since 3.2
  */
 public interface ResultMatcher {

spring-test/src/main/java/org/springframework/test/web/servlet/request/MockMvcRequestBuilders.java

@@ -21,7 +21,6 @@
 
 import org.springframework.http.HttpMethod;
 import org.springframework.mock.web.MockHttpServletRequest;
-import org.springframework.mock.web.MockMultipartHttpServletRequest;
 import org.springframework.test.web.servlet.MvcResult;
 import org.springframework.test.web.servlet.RequestBuilder;
 
@@ -33,10 +32,6 @@
  * {@link org.springframework.mock.web.MockServletContext MockServletContext}
  * that was created by the Spring TestContext Framework.
  *
- * <p>Methods in this class that return a {@link MockHttpServletRequestBuilder}
- * will reuse a {@link MockHttpServletRequest} that was created by the Spring
- * TestContext Framework.
- *
  * <h3>Eclipse Users</h3>
  * <p>Consider adding this class as a Java editor favorite. To navigate to
  * this setting, open the Preferences and type "favorites".
@@ -199,11 +194,6 @@ public static MockHttpServletRequestBuilder request(HttpMethod httpMethod, URI u
 
 	/**
 	 * Create a {@link MockMultipartHttpServletRequestBuilder} for a multipart request.
-	 * <p>In contrast to methods in this class that return a
-	 * {@link MockHttpServletRequestBuilder}, the builder returned by this
-	 * method will always create a new {@link MockMultipartHttpServletRequest}
-	 * that is <em>not</em> associated with a mock request created by the
-	 * Spring TestContext Framework.
 	 * @param urlTemplate a URL template; the resulting URL will be encoded
 	 * @param urlVariables zero or more URL variables
 	 */
@@ -213,11 +203,6 @@ public static MockMultipartHttpServletRequestBuilder fileUpload(String urlTempla
 
 	/**
 	 * Create a {@link MockMultipartHttpServletRequestBuilder} for a multipart request.
-	 * <p>In contrast to methods in this class that return a
-	 * {@link MockHttpServletRequestBuilder}, the builder returned by this
-	 * method will always create a new {@link MockMultipartHttpServletRequest}
-	 * that is <em>not</em> associated with a mock request created by the
-	 * Spring TestContext Framework.
 	 * @param uri the URL
 	 * @since 4.0.3
 	 */
@@ -228,7 +213,7 @@ public static MockMultipartHttpServletRequestBuilder fileUpload(URI uri) {
 	/**
 	 * Create a {@link RequestBuilder} for an async dispatch from the
 	 * {@link MvcResult} of the request that started async processing.
-	 * <p>Usage involves performing one request first that starts async processing:
+	 * <p>Usage involves performing a request that starts async processing first:
 	 * <pre class="code">
 	 * MvcResult mvcResult = this.mockMvc.perform(get("/1"))
 	 *	.andExpect(request().asyncStarted())

spring-test/src/main/java/org/springframework/test/web/servlet/setup/MockMvcBuilders.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2012 the original author or authors.
+ * Copyright 2002-2015 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.
@@ -16,56 +16,60 @@
 
 package org.springframework.test.web.servlet.setup;
 
-import javax.servlet.ServletContext;
-
-import org.springframework.stereotype.Controller;
 import org.springframework.test.web.servlet.MockMvc;
 import org.springframework.test.web.servlet.MockMvcBuilder;
 import org.springframework.web.context.WebApplicationContext;
-import org.springframework.web.servlet.DispatcherServlet;
 
 /**
- * The main class to import to access all available {@link MockMvcBuilder}s.
+ * The main class to import in order to access all available {@link MockMvcBuilder}s.
  *
- * <p><strong>Eclipse users:</strong> consider adding this class as a Java editor
- * favorite. To navigate, open the Preferences and type "favorites".
+ * <h3>Eclipse Users</h3>
+ * <p>Consider adding this class as a Java editor favorite. To navigate to
+ * this setting, open the Preferences and type "favorites".
  *
  * @author Rossen Stoyanchev
+ * @author Sam Brannen
  * @since 3.2
+ * @see #webAppContextSetup(WebApplicationContext)
+ * @see #standaloneSetup(Object...)
  */
 public class MockMvcBuilders {
 
 	/**
-	 * Build a {@link MockMvc} using the given, fully initialized, i.e.
-	 * refreshed, {@link WebApplicationContext}. The {@link DispatcherServlet}
-	 * will use the context to discover Spring MVC infrastructure and
-	 * application controllers in it. The context must have been configured with
-	 * a {@link ServletContext}.
+	 * Build a {@link MockMvc} instance using the given, fully initialized
+	 * (i.e., <em>refreshed</em>) {@link WebApplicationContext}.
+	 * <p>The {@link org.springframework.web.servlet.DispatcherServlet DispatcherServlet}
+	 * will use the context to discover Spring MVC infrastructure and application
+	 * controllers in it. The context must have been configured with a
+	 * {@link javax.servlet.ServletContext ServletContext}.
 	 */
 	public static DefaultMockMvcBuilder webAppContextSetup(WebApplicationContext context) {
 		return new DefaultMockMvcBuilder(context);
 	}
 
 	/**
-	 * Build a {@link MockMvc} by registering one or more {@code @Controller}'s
-	 * instances and configuring Spring MVC infrastructure programmatically.
-	 * This allows full control over the instantiation and initialization of
-	 * controllers, and their dependencies, similar to plain unit tests while
+	 * Build a {@link MockMvc} instance by registering one or more
+	 * {@code @Controller} instances and configuring Spring MVC infrastructure
+	 * programmatically.
+	 *
+	 * <p>This allows full control over the instantiation and initialization of
+	 * controllers and their dependencies, similar to plain unit tests while
 	 * also making it possible to test one controller at a time.
 	 *
-	 * <p>When this option is used, the minimum infrastructure required by the
-	 * {@link DispatcherServlet} to serve requests with annotated controllers is
-	 * automatically created, and can be customized, resulting in configuration
-	 * that is equivalent to what the MVC Java configuration provides except
-	 * using builder style methods.
+	 * <p>When this builder is used, the minimum infrastructure required by the
+	 * {@link org.springframework.web.servlet.DispatcherServlet DispatcherServlet}
+	 * to serve requests with annotated controllers is created automatically
+	 * and can be customized, resulting in configuration that is equivalent to
+	 * what MVC Java configuration provides except using builder-style methods.
 	 *
 	 * <p>If the Spring MVC configuration of an application is relatively
-	 * straight-forward, for example when using the MVC namespace or the MVC
-	 * Java config, then using this builder might be a good option for testing
-	 * a majority of controllers. A much smaller number of tests can be used
-	 * to focus on testing and verifying the actual Spring MVC configuration.
+	 * straight-forward &mdash; for example, when using the MVC namespace in
+	 * XML or MVC Java config &mdash; then using this builder might be a good
+	 * option for testing a majority of controllers. In such cases, a much
+	 * smaller number of tests can be used to focus on testing and verifying
+	 * the actual Spring MVC configuration.
 	 *
-	 * @param controllers one or more {@link Controller @Controller}'s to test
+	 * @param controllers one or more {@code @Controller} instances to test
 	 */
 	public static StandaloneMockMvcBuilder standaloneSetup(Object... controllers) {
 		return new StandaloneMockMvcBuilder(controllers);