Polish MockRestServiceServer code

Cherry picked from #7ab4d0ca08

Author: rstoyanchev

spring-test/src/main/java/org/springframework/test/web/client/AbstractRequestExpectationManager.java

@@ -159,14 +159,17 @@ public Set<RequestExpectation> getExpectations() {
 			return this.expectations;
 		}
 
+		/**
+		 * Return a matching expectation, or {@code null} if none match.
+		 */
 		public RequestExpectation findExpectation(ClientHttpRequest request) throws IOException {
 			for (RequestExpectation expectation : getExpectations()) {
 				try {
 					expectation.match(request);
 					return expectation;
 				}
 				catch (AssertionError error) {
-					// Ignore
+					// We're looking to find a match or return null..
 				}
 			}
 			return null;

spring-test/src/main/java/org/springframework/test/web/client/MockRestServiceServer.java

@@ -94,7 +94,7 @@ public ResponseActions expect(RequestMatcher matcher) {
 	}
 
 	/**
-	 * An alternative to {@link #expect(RequestMatcher)} with an indication how
+	 * An alternative to {@link #expect(RequestMatcher)} that also indicates how
 	 * many times the request is expected to be executed.
 	 * <p>When request expectations have an expected count greater than one, only
 	 * the first execution is expected to match the order of declaration. Subsequent

spring-test/src/main/java/org/springframework/test/web/client/RequestExpectationManager.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2017 the original author or authors.
+ * Copyright 2002-2018 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,9 +22,14 @@
 import org.springframework.http.client.ClientHttpResponse;
 
 /**
- * Abstraction for creating HTTP request expectations, applying them to actual
- * requests (in strict or random order), and verifying whether expectations
- * have been met.
+ * Encapsulates the behavior required to implement {@link MockRestServiceServer}
+ * including its public API (create expectations + verify/reset) along with an
+ * extra method for verifying actual requests.
+ *
+ * <p>This contract is not used directly in applications but a custom
+ * implementation can be
+ * {@link org.springframework.test.web.client.MockRestServiceServer.MockRestServiceServerBuilder#build(RequestExpectationManager)
+ * plugged} in through the {@code MockRestServiceServer} builder.
  *
  * @author Rossen Stoyanchev
  * @since 4.3
@@ -34,30 +39,41 @@ public interface RequestExpectationManager {
 	/**
 	 * Set up a new request expectation. The returned {@link ResponseActions} is
 	 * used to add more expectations and define a response.
+	 * <p>This is a delegate for
+	 * {@link MockRestServiceServer#expect(ExpectedCount, RequestMatcher)}.
+	 *
 	 * @param requestMatcher a request expectation
 	 * @return for setting up further expectations and define a response
+	 * @see MockRestServiceServer#expect(RequestMatcher)
+	 * @see MockRestServiceServer#expect(ExpectedCount, RequestMatcher)
 	 */
 	ResponseActions expectRequest(ExpectedCount count, RequestMatcher requestMatcher);
 
-	/**
-	 * Validate the given actual request against the declared expectations.
-	 * Is successful return the mock response to use or raise an error.
-	 * @param request the request
-	 * @return the response to return if the request was validated.
-	 * @throws AssertionError when some expectations were not met
-	 * @throws IOException in case of any validation errors
-	 */
-	ClientHttpResponse validateRequest(ClientHttpRequest request) throws IOException;
-
 	/**
 	 * Verify that all expectations have been met.
+	 * <p>This is a delegate for {@link MockRestServiceServer#verify()}.
 	 * @throws AssertionError when some expectations were not met
+	 * @see MockRestServiceServer#verify()
 	 */
 	void verify();
 
 	/**
 	 * Reset the internal state removing all expectations and recorded requests.
+	 * <p>This is a delegate for {@link MockRestServiceServer#reset()}.
+	 * @see MockRestServiceServer#reset()
 	 */
 	void reset();
 
+
+	/**
+	 * Validate the given actual request against the declared expectations.
+	 * Is successful return the mock response to use or raise an error.
+	 * <p>This is used in {@link MockRestServiceServer} against actual requests.
+	 * @param request the request
+	 * @return the response to return if the request was validated.
+	 * @throws AssertionError when some expectations were not met
+	 * @throws IOException in case of any validation errors
+	 */
+	ClientHttpResponse validateRequest(ClientHttpRequest request) throws IOException;
+
 }

spring-test/src/main/java/org/springframework/test/web/client/SimpleRequestExpectationManager.java

@@ -37,8 +37,10 @@
  */
 public class SimpleRequestExpectationManager extends AbstractRequestExpectationManager {
 
+	/** Expectations in the order of declaration (count may be > 1) */
 	private Iterator<RequestExpectation> expectationIterator;
 
+	/** Track expectations that have a remaining count */
 	private final RequestExpectationGroup repeatExpectations = new RequestExpectationGroup();