From 72506422a8033135e4f42ac602c20d25882fb7fc Mon Sep 17 00:00:00 2001 From: Maximillian Arruda Date: Mon, 12 Jun 2023 08:18:24 -0300 Subject: [PATCH] docs: enhance `QueryMapper` javadoc Signed-off-by: Maximillian Arruda --- .../main/java/jakarta/nosql/QueryMapper.java | 113 +++++++++--------- 1 file changed, 59 insertions(+), 54 deletions(-) diff --git a/api/nosql-core/src/main/java/jakarta/nosql/QueryMapper.java b/api/nosql-core/src/main/java/jakarta/nosql/QueryMapper.java index 2120e9b12..e37c1ed13 100644 --- a/api/nosql-core/src/main/java/jakarta/nosql/QueryMapper.java +++ b/api/nosql-core/src/main/java/jakarta/nosql/QueryMapper.java @@ -21,18 +21,18 @@ import java.util.stream.Stream; /** - * The builder to either select and delete query using an object mapper API. + * This interface holds the interfaces that compose the Fluent API for selecting and deleting NoSQL entities. */ public interface QueryMapper { /** - * The Column Delete Query + * Represents the first step in the delete query fluent API */ interface MapperDeleteFrom extends MapperDeleteQueryBuild { /** - * Starts a new condition defining the column name + * Starts a new delete condition by a column name * * @param name the column name * @return a new {@link MapperDeleteNameCondition} @@ -42,13 +42,13 @@ interface MapperDeleteFrom extends MapperDeleteQueryBuild { } /** - * The base to delete name condition + * Represents a delete condition based on a column name */ interface MapperDeleteNameCondition { /** - * Creates the equals condition + * Creates a delete condition where the column name provided is equal to the provided value * * @param value the value to the condition * @param the type @@ -58,7 +58,7 @@ interface MapperDeleteNameCondition { MapperDeleteWhere eq(T value); /** - * Creates the like condition + * Creates a delete condition where the column name provided is like to the provided value * * @param value the value to the condition * @return the {@link MapperDeleteWhere} @@ -67,7 +67,7 @@ interface MapperDeleteNameCondition { MapperDeleteWhere like(String value); /** - * Creates the greater than condition + * Creates a delete condition where the column name provided is greater than to the provided value * * @param value the value to the condition * @param the type @@ -77,7 +77,7 @@ interface MapperDeleteNameCondition { MapperDeleteWhere gt(T value); /** - * Creates the greater equals than condition + * Creates a delete condition where the column name provided is greater than or equal to the provided value * * @param the type * @param value the value to the condition @@ -87,7 +87,7 @@ interface MapperDeleteNameCondition { MapperDeleteWhere gte(T value); /** - * Creates the lesser than condition + * Creates a delete condition where the column name provided is less than the provided value * * @param the type * @param value the value to the condition @@ -97,7 +97,7 @@ interface MapperDeleteNameCondition { MapperDeleteWhere lt(T value); /** - * Creates the lesser equals than condition + * Creates a delete condition where the column name provided is less than or equal to the provided value * * @param the type * @param value the value to the condition @@ -107,7 +107,7 @@ interface MapperDeleteNameCondition { MapperDeleteWhere lte(T value); /** - * Creates the between condition + * Creates a delete condition where the column name provided is between the provided values * * @param the type * @param valueA the values within a given range @@ -118,7 +118,7 @@ interface MapperDeleteNameCondition { MapperDeleteWhere between(T valueA, T valueB); /** - * Creates in condition + * Creates a delete condition where the column name provided is in the provided iterable values * * @param values the values * @param the type @@ -128,7 +128,7 @@ interface MapperDeleteNameCondition { MapperDeleteWhere in(Iterable values); /** - * Creates the equals condition. + * Creates a NOT delete condition for the column name provided * * @return {@link MapperDeleteNotCondition} */ @@ -136,13 +136,13 @@ interface MapperDeleteNameCondition { } /** - * The column not condition + * Represents a NOT delete condition in the delete query fluent API */ interface MapperDeleteNotCondition extends MapperDeleteNameCondition { } /** - * The last step to the build of execution + * Represents the last step of the delete query fluent API execution */ interface MapperDeleteQueryBuild { @@ -155,37 +155,36 @@ interface MapperDeleteQueryBuild { } /** - * The Column Where whose define the condition in the delete query. + * Represents a step where it's possible to perform a logical conjunction or disjunction adding one more delete condition or end up performing the built query */ interface MapperDeleteWhere extends MapperDeleteQueryBuild { - /** - * It starts a new condition performing a logical conjunction using two predicates. + * Create a new delete condition performing logical conjunction (AND) by giving a column name * - * @param name a condition to be added - * @return the same {@link MapperDeleteNameCondition} with the condition appended - * @throws NullPointerException when condition is null + * @param name the column name + * @return the same {@link MapperDeleteNameCondition} with the delete condition appended + * @throws NullPointerException when name is null */ MapperDeleteNameCondition and(String name); /** - * It starts a new condition performing a logical disjunction using two predicates. + * Create a new delete condition performing logical disjunction (OR) by giving a column name * - * @param name a condition to be added - * @return the same {@link MapperDeleteNameCondition} with the condition appended - * @throws NullPointerException when condition is null + * @param name the column name + * @return the same {@link MapperDeleteNameCondition} with the delete condition appended + * @throws NullPointerException when name is null */ MapperDeleteNameCondition or(String name); } /** - * The ColumnFrom Query + * Represents the first step in the query fluent API */ interface MapperFrom extends MapperQueryBuild { /** - * Starts a new condition defining the column name + * Starts a new condition by given a column name * * @param name the column name * @return a new {@link MapperNameCondition} @@ -221,7 +220,7 @@ interface MapperFrom extends MapperQueryBuild { } /** - * The Column Order whose define the maximum number of results to retrieve. + * Represents the step in the query fluent API where it's possible to define the maximum number of results to retrieve or to perform the query execution */ interface MapperLimit extends MapperQueryBuild { @@ -235,13 +234,13 @@ interface MapperLimit extends MapperQueryBuild { } /** - * The base to name condition + * Represents a condition based on a column name */ interface MapperNameCondition { /** - * Creates the equals condition + * Creates a condition where the column name provided is equal to the provided value * * @param value the value to the condition * @param the type @@ -251,7 +250,7 @@ interface MapperNameCondition { MapperWhere eq(T value); /** - * Creates the like condition + * Creates a condition where the column name provided is like to the provided value * * @param value the value to the condition * @return the {@link MapperWhere} @@ -260,7 +259,7 @@ interface MapperNameCondition { MapperWhere like(String value); /** - * Creates the greater than condition + * Creates a condition where the column name provided is greater than to the provided value * * @param the type * @param value the value to the condition @@ -270,7 +269,7 @@ interface MapperNameCondition { MapperWhere gt(T value); /** - * Creates the greater equals than condition + * Creates a condition where the column name provided is greater than or equal to the provided value * * @param the type * @param value the value to the condition @@ -280,7 +279,7 @@ interface MapperNameCondition { MapperWhere gte(T value); /** - * Creates the lesser than condition + * Creates a condition where the column name provided is less than the provided value * * @param the type * @param value the value to the condition @@ -290,7 +289,7 @@ interface MapperNameCondition { MapperWhere lt(T value); /** - * Creates the lesser equals than condition + * Creates a condition where the column name provided is less than or equal to the provided value * * @param the type * @param value the value to the condition @@ -300,7 +299,7 @@ interface MapperNameCondition { MapperWhere lte(T value); /** - * Creates the between condition + * Creates a condition where the column name provided is between the provided values * * @param the type * @param valueA the values within a given range @@ -311,7 +310,7 @@ interface MapperNameCondition { MapperWhere between(T valueA, T valueB); /** - * Creates in condition + * Creates a condition where the column name provided is in the provided iterable values * * @param values the values * @param the type @@ -321,7 +320,7 @@ interface MapperNameCondition { MapperWhere in(Iterable values); /** - * Creates the equals condition. + * Creates a NOT condition for the column name provided. * * @return {@link MapperNotCondition} */ @@ -329,14 +328,20 @@ interface MapperNameCondition { } /** - * The Column name order a query + * Represents the step in the query fluent API where it's possible to: + * + *
  • define the order of the results
    • + *
  • or define the position of the first result
    • + *
  • or define the maximum number of results to retrieve
    • + *
  • or to perform the query execution
    • + *     */ interface MapperNameOrder extends MapperQueryBuild { /** - * Add the order how the result will return + * Add the order of how the result will return based on a given column name * - * @param name the name to be ordered + * @param name the column name to be ordered * @return a query with the sort defined * @throws NullPointerException when name is null */ @@ -362,13 +367,13 @@ interface MapperNameOrder extends MapperQueryBuild { } /** - * The column not condition + * Represents a NOT condition in the delete query fluent API */ interface MapperNotCondition extends MapperNameCondition { } /** - * The definition to either + * Represents the step in the query fluent API where it's possible to define the order of the results or to perform the query execution */ interface MapperOrder { @@ -389,7 +394,7 @@ interface MapperOrder { } /** - * The last step to the build select query + * Represents the last step of the query fluent API execution */ interface MapperQueryBuild { @@ -403,7 +408,7 @@ interface MapperQueryBuild { List result(); /** - * Executes the query and it returns as a Stream + * Executes the query and it returns as a {@link Stream} * * @param the entity type * @return the result of the query @@ -411,7 +416,7 @@ interface MapperQueryBuild { Stream stream(); /** - * Executes and returns a single result + * Executes the query and returns the result as a single element otherwise it will return an {@link Optional#empty()} * * @param the entity type * @return the result of the query that may have one or empty result @@ -422,7 +427,7 @@ interface MapperQueryBuild { } /** - * The Column Order whose define the position of the first result to retrieve. + * Represents the step in the query fluent API where it's possible to define the position of the first result to retrieve or to perform the query execution */ interface MapperSkip extends MapperQueryBuild { @@ -437,26 +442,26 @@ interface MapperSkip extends MapperQueryBuild { } /** - * The Column Where whose define the condition in the query. + * Represents a step where it's possible to perform a logical conjunction or disjunction adding one more condition or end up performing the built query */ interface MapperWhere extends MapperQueryBuild { /** - * It starts a new condition performing a logical conjunction using two predicates. + * Create a new condition performing logical conjunction (AND) by giving a column name * - * @param name a condition to be added + * @param name the column name * @return the same {@link MapperNameCondition} with the condition appended - * @throws NullPointerException when condition is null + * @throws NullPointerException when name is null */ MapperNameCondition and(String name); /** - * It starts a new condition performing a logical disjunction using two predicates. + * Create a new condition performing logical disjunction (OR) by giving a column name * - * @param name a condition to be added + * @param name the column name * @return the same {@link MapperNameCondition} with the condition appended - * @throws NullPointerException when condition is null + * @throws NullPointerException when name is null */ MapperNameCondition or(String name);