From 77be0ba85958a232dd5a5e4816491d267e802109 Mon Sep 17 00:00:00 2001 From: Christoph Strobl Date: Fri, 5 May 2017 14:16:40 +0200 Subject: [PATCH] DATACMNS-995 - Polishing. Update JavaDoc to reflect reactive types, not null arguments and potential exceptions. Align not null JavaDoc of imperative QueryByExample interface. Original Pull Request: #197 --- .../query/QueryByExampleExecutor.java | 12 +++++----- .../query/ReactiveQueryByExampleExecutor.java | 23 +++++++++++-------- 2 files changed, 19 insertions(+), 16 deletions(-) diff --git a/src/main/java/org/springframework/data/repository/query/QueryByExampleExecutor.java b/src/main/java/org/springframework/data/repository/query/QueryByExampleExecutor.java index 2288e86d7..cbd41c2d0 100644 --- a/src/main/java/org/springframework/data/repository/query/QueryByExampleExecutor.java +++ b/src/main/java/org/springframework/data/repository/query/QueryByExampleExecutor.java @@ -35,7 +35,7 @@ public interface QueryByExampleExecutor { /** * Returns a single entity matching the given {@link Example} or {@literal null} if none was found. * - * @param example can be {@literal null}. + * @param example must not be {@literal null}. * @return a single entity matching the given {@link Example} or {@link Optional#empty()} if none was found. * @throws org.springframework.dao.IncorrectResultSizeDataAccessException if the Example yields more than one result. */ @@ -45,7 +45,7 @@ public interface QueryByExampleExecutor { * Returns all entities matching the given {@link Example}. In case no match could be found an empty {@link Iterable} * is returned. * - * @param example can be {@literal null}. + * @param example must not be {@literal null}. * @return all entities matching the given {@link Example}. */ Iterable findAll(Example example); @@ -54,7 +54,7 @@ public interface QueryByExampleExecutor { * Returns all entities matching the given {@link Example} applying the given {@link Sort}. In case no match could be * found an empty {@link Iterable} is returned. * - * @param example can be {@literal null}. + * @param example must not be {@literal null}. * @param sort the {@link Sort} specification to sort the results by, must not be {@literal null}. * @return all entities matching the given {@link Example}. * @since 1.10 @@ -65,7 +65,7 @@ public interface QueryByExampleExecutor { * Returns a {@link Page} of entities matching the given {@link Example}. In case no match could be found, an empty * {@link Page} is returned. * - * @param example can be {@literal null}. + * @param example must not be {@literal null}. * @param pageable can be {@literal null}. * @return a {@link Page} of entities matching the given {@link Example}. */ @@ -74,7 +74,7 @@ public interface QueryByExampleExecutor { /** * Returns the number of instances matching the given {@link Example}. * - * @param example the {@link Example} to count instances for, can be {@literal null}. + * @param example the {@link Example} to count instances for. Must not be {@literal null}. * @return the number of instances matching the {@link Example}. */ long count(Example example); @@ -82,7 +82,7 @@ public interface QueryByExampleExecutor { /** * Checks whether the data store contains elements that match the given {@link Example}. * - * @param example the {@link Example} to use for the existence check, can be {@literal null}. + * @param example the {@link Example} to use for the existence check. Must not be {@literal null}. * @return {@literal true} if the data store contains elements that match the given {@link Example}. */ boolean exists(Example example); diff --git a/src/main/java/org/springframework/data/repository/query/ReactiveQueryByExampleExecutor.java b/src/main/java/org/springframework/data/repository/query/ReactiveQueryByExampleExecutor.java index cff9890b5..3b849a8ea 100644 --- a/src/main/java/org/springframework/data/repository/query/ReactiveQueryByExampleExecutor.java +++ b/src/main/java/org/springframework/data/repository/query/ReactiveQueryByExampleExecutor.java @@ -26,32 +26,35 @@ import org.springframework.data.domain.Sort; * * @param * @author Mark Paluch + * @author Christoph Strobl * @since 2.0 */ public interface ReactiveQueryByExampleExecutor { /** - * Returns a single entity matching the given {@link Example} or {@literal null} if none was found. + * Returns a single entity matching the given {@link Example} or {@link Mono#empty()} if none was found. * - * @param example can be {@literal null}. - * @return a single entity matching the given {@link Example} or {@literal null} if none was found. + * @param example must not be {@literal null}. + * @return a single entity matching the given {@link Example} or {@link Mono#empty()} if none was found. + * @throws org.springframework.dao.IncorrectResultSizeDataAccessException via {@link Mono#error(Throwable)} if the + * example yields more than one result. */ Mono findOne(Example example); /** - * Returns all entities matching the given {@link Example}. In case no match could be found an empty {@link Iterable} - * is returned. + * Returns all entities matching the given {@link Example}. In case no match could be found {@link Flux#empty()} is + * returned. * - * @param example can be {@literal null}. + * @param example must not be {@literal null}. * @return all entities matching the given {@link Example}. */ Flux findAll(Example example); /** * Returns all entities matching the given {@link Example} applying the given {@link Sort}. In case no match could be - * found an empty {@link Iterable} is returned. + * found {@link Flux#empty()} is returned. * - * @param example can be {@literal null}. + * @param example must not be {@literal null}. * @param sort the {@link Sort} specification to sort the results by, must not be {@literal null}. * @return all entities matching the given {@link Example}. */ @@ -60,7 +63,7 @@ public interface ReactiveQueryByExampleExecutor { /** * Returns the number of instances matching the given {@link Example}. * - * @param example the {@link Example} to count instances for, can be {@literal null}. + * @param example the {@link Example} to count instances for. Must not be {@literal null}. * @return the number of instances matching the {@link Example}. */ Mono count(Example example); @@ -68,7 +71,7 @@ public interface ReactiveQueryByExampleExecutor { /** * Checks whether the data store contains elements that match the given {@link Example}. * - * @param example the {@link Example} to use for the existence check, can be {@literal null}. + * @param example the {@link Example} to use for the existence check. Must not be {@literal null}. * @return {@literal true} if the data store contains elements that match the given {@link Example}. */ Mono exists(Example example);