From 5ee24c84828fe65571d47f5693f3a181c1ddc039 Mon Sep 17 00:00:00 2001 From: Sam Brannen Date: Sat, 15 Aug 2015 13:33:08 +0200 Subject: [PATCH] Polish Javadoc for JsonPathRequestMatchers, etc. --- .../test/util/JsonPathExpectationsHelper.java | 4 +- .../client/match/JsonPathRequestMatchers.java | 63 ++++++++++++------- .../result/JsonPathResultMatchers.java | 20 +++--- 3 files changed, 54 insertions(+), 33 deletions(-) diff --git a/spring-test/src/main/java/org/springframework/test/util/JsonPathExpectationsHelper.java b/spring-test/src/main/java/org/springframework/test/util/JsonPathExpectationsHelper.java index adec64f736a..4b42b322638 100644 --- a/spring-test/src/main/java/org/springframework/test/util/JsonPathExpectationsHelper.java +++ b/spring-test/src/main/java/org/springframework/test/util/JsonPathExpectationsHelper.java @@ -78,8 +78,8 @@ public class JsonPathExpectationsHelper { /** * Construct a new {@code JsonPathExpectationsHelper}. * @param expression the {@link JsonPath} expression; never {@code null} or empty - * @param args arguments to parameterize the {@code JsonPath} expression, with - * formatting specifiers defined in {@link String#format(String, Object...)} + * @param args arguments to parameterize the {@code JsonPath} expression with, + * using formatting specifiers defined in {@link String#format(String, Object...)} */ public JsonPathExpectationsHelper(String expression, Object... args) { Assert.hasText(expression, "expression must not be null or empty"); diff --git a/spring-test/src/main/java/org/springframework/test/web/client/match/JsonPathRequestMatchers.java b/spring-test/src/main/java/org/springframework/test/web/client/match/JsonPathRequestMatchers.java index eb57f0b6e38..a3bd2a487c0 100644 --- a/spring-test/src/main/java/org/springframework/test/web/client/match/JsonPathRequestMatchers.java +++ b/spring-test/src/main/java/org/springframework/test/web/client/match/JsonPathRequestMatchers.java @@ -26,97 +26,112 @@ import org.springframework.mock.http.client.MockClientHttpRequest; import org.springframework.test.util.JsonPathExpectationsHelper; import org.springframework.test.web.client.RequestMatcher; +import com.jayway.jsonpath.JsonPath; + /** - * Factory methods for request content {@code RequestMatcher}s using a - * JsonPath expression. + * Factory for assertions on the request content using + * JsonPath expressions. *

An instance of this class is typically accessed via - * {@link MockRestRequestMatchers#jsonPath}. + * {@link MockRestRequestMatchers#jsonPath(String, Matcher)} or + * {@link MockRestRequestMatchers#jsonPath(String, Object...)}. * * @author Rossen Stoyanchev + * @author Sam Brannen * @since 3.2 */ public class JsonPathRequestMatchers { - private JsonPathExpectationsHelper jsonPathHelper; + private final JsonPathExpectationsHelper jsonPathHelper; /** - * Class constructor, not for direct instantiation. Use - * {@link MockRestRequestMatchers#jsonPath(String, Matcher)} or + * Protected constructor. + *

Use {@link MockRestRequestMatchers#jsonPath(String, Matcher)} or * {@link MockRestRequestMatchers#jsonPath(String, Object...)}. - * - * @param expression the JSONPath expression - * @param args arguments to parameterize the JSONPath expression with using - * the formatting specifiers defined in - * {@link String#format(String, Object...)} + * @param expression the {@link JsonPath} expression; never {@code null} or empty + * @param args arguments to parameterize the {@code JsonPath} expression with, + * using formatting specifiers defined in {@link String#format(String, Object...)} */ protected JsonPathRequestMatchers(String expression, Object ... args) { this.jsonPathHelper = new JsonPathExpectationsHelper(expression, args); } + /** - * Evaluate the JSONPath and assert the resulting value with the given {@code Matcher}. + * Evaluate the JSON path expression against the request content and + * assert the resulting value with the given Hamcrest {@link Matcher}. */ public RequestMatcher value(final Matcher matcher) { return new AbstractJsonPathRequestMatcher() { @Override protected void matchInternal(MockClientHttpRequest request) throws IOException, ParseException { - jsonPathHelper.assertValue(request.getBodyAsString(), matcher); + JsonPathRequestMatchers.this.jsonPathHelper.assertValue(request.getBodyAsString(), matcher); } }; } /** - * Apply the JSONPath and assert the resulting value. + * Evaluate the JSON path expression against the request content and + * assert that the result is equal to the supplied value. */ public RequestMatcher value(final Object expectedValue) { return new AbstractJsonPathRequestMatcher() { @Override protected void matchInternal(MockClientHttpRequest request) throws IOException, ParseException { - jsonPathHelper.assertValue(request.getBodyAsString(), expectedValue); + JsonPathRequestMatchers.this.jsonPathHelper.assertValue(request.getBodyAsString(), expectedValue); } }; } /** - * Apply the JSONPath and assert the resulting value. + * Evaluate the JSON path expression against the request content and + * assert that a non-null value exists at the given path. + *

If the JSON path expression is not {@linkplain JsonPath#isDefinite + * definite}, this method asserts that the value at the given path is not + * empty. */ public RequestMatcher exists() { return new AbstractJsonPathRequestMatcher() { @Override protected void matchInternal(MockClientHttpRequest request) throws IOException, ParseException { - jsonPathHelper.exists(request.getBodyAsString()); + JsonPathRequestMatchers.this.jsonPathHelper.exists(request.getBodyAsString()); } }; } /** - * Evaluate the JSON path and assert the resulting content exists. + * Evaluate the JSON path expression against the request content and + * assert that a value does not exist at the given path. + *

If the JSON path expression is not {@linkplain JsonPath#isDefinite + * definite}, this method asserts that the value at the given path is + * empty. */ public RequestMatcher doesNotExist() { return new AbstractJsonPathRequestMatcher() { @Override protected void matchInternal(MockClientHttpRequest request) throws IOException, ParseException { - jsonPathHelper.doesNotExist(request.getBodyAsString()); + JsonPathRequestMatchers.this.jsonPathHelper.doesNotExist(request.getBodyAsString()); } }; } /** - * Assert the content at the given JSONPath is an array. + * Evaluate the JSON path expression against the request content and + * assert that the result is an array. */ public RequestMatcher isArray() { return new AbstractJsonPathRequestMatcher() { @Override protected void matchInternal(MockClientHttpRequest request) throws IOException, ParseException { - jsonPathHelper.assertValueIsArray(request.getBodyAsString()); + JsonPathRequestMatchers.this.jsonPathHelper.assertValueIsArray(request.getBodyAsString()); } }; } /** - * Abstract base class for JSONPath {@link RequestMatcher}s. + * Abstract base class for {@code JsonPath}-based {@link RequestMatcher}s. + * @see #matchInternal */ private abstract static class AbstractJsonPathRequestMatcher implements RequestMatcher { @@ -131,7 +146,7 @@ public class JsonPathRequestMatchers { } } - protected abstract void matchInternal(MockClientHttpRequest request) throws IOException, ParseException; - + abstract void matchInternal(MockClientHttpRequest request) throws IOException, ParseException; } + } diff --git a/spring-test/src/main/java/org/springframework/test/web/servlet/result/JsonPathResultMatchers.java b/spring-test/src/main/java/org/springframework/test/web/servlet/result/JsonPathResultMatchers.java index 1257625fe50..1a9a9a1a249 100644 --- a/spring-test/src/main/java/org/springframework/test/web/servlet/result/JsonPathResultMatchers.java +++ b/spring-test/src/main/java/org/springframework/test/web/servlet/result/JsonPathResultMatchers.java @@ -22,11 +22,14 @@ import org.springframework.test.util.JsonPathExpectationsHelper; import org.springframework.test.web.servlet.MvcResult; import org.springframework.test.web.servlet.ResultMatcher; +import com.jayway.jsonpath.JsonPath; + /** * Factory for assertions on the response content using * JsonPath expressions. *

An instance of this class is typically accessed via - * {@link MockMvcResultMatchers#jsonPath}. + * {@link MockMvcResultMatchers#jsonPath(String, Matcher)} or + * {@link MockMvcResultMatchers#jsonPath(String, Object...)}. * * @author Rossen Stoyanchev * @author Craig Andrews @@ -42,6 +45,9 @@ public class JsonPathResultMatchers { * Protected constructor. *

Use {@link MockMvcResultMatchers#jsonPath(String, Object...)} or * {@link MockMvcResultMatchers#jsonPath(String, Matcher)}. + * @param expression the {@link JsonPath} expression; never {@code null} or empty + * @param args arguments to parameterize the {@code JsonPath} expression with, + * using formatting specifiers defined in {@link String#format(String, Object...)} */ protected JsonPathResultMatchers(String expression, Object ... args) { this.jsonPathHelper = new JsonPathExpectationsHelper(expression, args); @@ -79,9 +85,9 @@ public class JsonPathResultMatchers { /** * Evaluate the JSON path expression against the response content and * assert that a non-null value exists at the given path. - *

If the JSON path expression is not - * {@linkplain com.jayway.jsonpath.JsonPath#isDefinite definite}, - * this method asserts that the value at the given path is not empty. + *

If the JSON path expression is not {@linkplain JsonPath#isDefinite + * definite}, this method asserts that the value at the given path is not + * empty. */ public ResultMatcher exists() { return new ResultMatcher() { @@ -96,9 +102,9 @@ public class JsonPathResultMatchers { /** * Evaluate the JSON path expression against the response content and * assert that a value does not exist at the given path. - *

If the JSON path expression is not - * {@linkplain com.jayway.jsonpath.JsonPath#isDefinite definite}, this - * method asserts that the value at the given path is empty. + *

If the JSON path expression is not {@linkplain JsonPath#isDefinite + * definite}, this method asserts that the value at the given path is + * empty. */ public ResultMatcher doesNotExist() { return new ResultMatcher() {