Polish MockRestServiceServer code

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

@@ -167,6 +167,9 @@ public abstract class AbstractRequestExpectationManager implements RequestExpect
 		}
 
 
+		/**
+		 * Return a matching expectation, or {@code null} if none match.
+		 */
 		@Nullable
 		public RequestExpectation findExpectation(ClientHttpRequest request) throws IOException {
 			for (RequestExpectation expectation : this.expectations) {
@@ -175,7 +178,7 @@ public abstract class AbstractRequestExpectationManager implements RequestExpect
 					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

@@ -92,7 +92,7 @@ public class MockRestServiceServer {
 	}
 
 	/**
-	 * 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.ClientHttpRequest;
 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,14 +39,36 @@ 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);
 
+	/**
+	 * 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
@@ -49,15 +76,4 @@ public interface RequestExpectationManager {
 	 */
 	ClientHttpResponse validateRequest(ClientHttpRequest request) throws IOException;
 
-	/**
-	 * Verify that all expectations have been met.
-	 * @throws AssertionError when some expectations were not met
-	 */
-	void verify();
-
-	/**
-	 * Reset the internal state removing all expectations and recorded requests.
-	 */
-	void reset();
-
 }

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

@@ -38,9 +38,11 @@ import org.springframework.util.Assert;
  */
 public class SimpleRequestExpectationManager extends AbstractRequestExpectationManager {
 
+	/** Expectations in the order of declaration (count may be > 1) */
 	@Nullable
 	private Iterator<RequestExpectation> expectationIterator;
 
+	/** Track expectations that have a remaining count */
 	private final RequestExpectationGroup repeatExpectations = new RequestExpectationGroup();