Skip to content

Commit

Permalink
docs: enhance QueryMapper javadoc
Browse files Browse the repository at this point in the history 
Signed-off-by: Maximillian Arruda <dearrudam@gmail.com>
  • Loading branch information
@dearrudam
dearrudam committed Jun 12, 2023
1 parent cdfd3a0 commit 7250642
Showing 1 changed file with 59 additions and 54 deletions.
113 changes: 59 additions & 54 deletions api/nosql-core/src/main/java/jakarta/nosql/QueryMapper.java
View file
Expand Up @@ -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}
Expand All @@ -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 <T> the type
Expand All @@ -58,7 +58,7 @@ interface MapperDeleteNameCondition {
<T> 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}
Expand All @@ -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 <T> the type
Expand All @@ -77,7 +77,7 @@ interface MapperDeleteNameCondition {
<T> 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 <T> the type
* @param value the value to the condition
Expand All @@ -87,7 +87,7 @@ interface MapperDeleteNameCondition {
<T> 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 <T> the type
* @param value the value to the condition
Expand All @@ -97,7 +97,7 @@ interface MapperDeleteNameCondition {
<T> 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 <T> the type
* @param value the value to the condition
Expand All @@ -107,7 +107,7 @@ interface MapperDeleteNameCondition {
<T> MapperDeleteWhere lte(T value);

/**
* Creates the between condition
* Creates a delete condition where the column name provided is between the provided values
*
* @param <T> the type
* @param valueA the values within a given range
Expand All @@ -118,7 +118,7 @@ interface MapperDeleteNameCondition {
<T> 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 <T> the type
Expand All @@ -128,21 +128,21 @@ interface MapperDeleteNameCondition {
<T> MapperDeleteWhere in(Iterable<T> values);

/**
* Creates the equals condition.
* Creates a NOT delete condition for the column name provided
*
* @return {@link MapperDeleteNotCondition}
*/
MapperDeleteNotCondition not();
}

/**
* 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 {

Expand All @@ -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}
Expand Down Expand Up @@ -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 {

Expand All @@ -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 <T> the type
Expand All @@ -251,7 +250,7 @@ interface MapperNameCondition {
<T> 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}
Expand All @@ -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 <T> the type
* @param value the value to the condition
Expand All @@ -270,7 +269,7 @@ interface MapperNameCondition {
<T> 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 <T> the type
* @param value the value to the condition
Expand All @@ -280,7 +279,7 @@ interface MapperNameCondition {
<T> MapperWhere gte(T value);

/**
* Creates the lesser than condition
* Creates a condition where the column name provided is less than the provided value
*
* @param <T> the type
* @param value the value to the condition
Expand All @@ -290,7 +289,7 @@ interface MapperNameCondition {
<T> 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 <T> the type
* @param value the value to the condition
Expand All @@ -300,7 +299,7 @@ interface MapperNameCondition {
<T> MapperWhere lte(T value);

/**
* Creates the between condition
* Creates a condition where the column name provided is between the provided values
*
* @param <T> the type
* @param valueA the values within a given range
Expand All @@ -311,7 +310,7 @@ interface MapperNameCondition {
<T> 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 <T> the type
Expand All @@ -321,22 +320,28 @@ interface MapperNameCondition {
<T> MapperWhere in(Iterable<T> values);

/**
* Creates the equals condition.
* Creates a NOT condition for the column name provided.
*
* @return {@link MapperNotCondition}
*/
MapperNotCondition not();
}

/**
* The Column name order a query
* Represents the step in the query fluent API where it's possible to:
* <lu>
* <li>define the order of the results</li>
* <li>or define the position of the first result</li>
* <li>or define the maximum number of results to retrieve</li>
* <li>or to perform the query execution</li>
* </lu>
*/
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
*/
Expand All @@ -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 {

Expand All @@ -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 {

Expand All @@ -403,15 +408,15 @@ interface MapperQueryBuild {
<T> List<T> result();

/**
* Executes the query and it returns as a Stream
* Executes the query and it returns as a {@link Stream}
*
* @param <T> the entity type
* @return the result of the query
*/
<T> Stream<T> 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 <T> the entity type
* @return the result of the query that may have one or empty result
Expand All @@ -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 {

Expand All @@ -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);

Expand Down

0 comments on commit 7250642

Please sign in to comment.