This is an automated email from the git hooks/post-receive script. New commit to branch develop in repository topia. See http://git.nuiton.org/topia.git commit 6d7829748f51f9d57ab9a1f89e5ba6e3a27480fd Author: Arnaud Thimel <thimel@codelutin.com> Date: Wed Aug 27 00:01:28 2014 +0200 Complete TopiaQueryBuilder*Step javadoc --- ...TopiaQueryBuilderAddCriteriaOrRunQueryStep.java | 2 +- .../TopiaQueryBuilderAddCriteriaStep.java | 118 ++++++++++----- .../persistence/TopiaQueryBuilderRunQueryStep.java | 162 +++++++++++++++++---- ...iaQueryBuilderRunQueryWithUniqueResultStep.java | 27 +++- 4 files changed, 244 insertions(+), 65 deletions(-) diff --git a/topia-persistence/src/main/java/org/nuiton/topia/persistence/TopiaQueryBuilderAddCriteriaOrRunQueryStep.java b/topia-persistence/src/main/java/org/nuiton/topia/persistence/TopiaQueryBuilderAddCriteriaOrRunQueryStep.java index 6199d33..573269f 100644 --- a/topia-persistence/src/main/java/org/nuiton/topia/persistence/TopiaQueryBuilderAddCriteriaOrRunQueryStep.java +++ b/topia-persistence/src/main/java/org/nuiton/topia/persistence/TopiaQueryBuilderAddCriteriaOrRunQueryStep.java @@ -26,7 +26,7 @@ package org.nuiton.topia.persistence; /** * Additional contract that aggregate both {@link org.nuiton.topia.persistence.TopiaQueryBuilderAddCriteriaStep} and - * {@link org.nuiton.topia.persistence.TopiaQueryBuilderRunQueryStep} contracts + * {@link org.nuiton.topia.persistence.TopiaQueryBuilderRunQueryStep} contracts. * * @author bleny * @since 3.0 diff --git a/topia-persistence/src/main/java/org/nuiton/topia/persistence/TopiaQueryBuilderAddCriteriaStep.java b/topia-persistence/src/main/java/org/nuiton/topia/persistence/TopiaQueryBuilderAddCriteriaStep.java index 044093c..e483a26 100644 --- a/topia-persistence/src/main/java/org/nuiton/topia/persistence/TopiaQueryBuilderAddCriteriaStep.java +++ b/topia-persistence/src/main/java/org/nuiton/topia/persistence/TopiaQueryBuilderAddCriteriaStep.java @@ -31,101 +31,145 @@ import java.util.Set; /** * Represents a step when building a query to add a constraint. - * + * <p/> * The builder implements the fluent interface DP, so you can add multiple constraints by chaining calls. * * @author bleny + * @author Arnaud Thimel (Code Lutin) * @since 3.0 */ public interface TopiaQueryBuilderAddCriteriaStep<E extends TopiaEntity> { /** - * @param property the name of a field of the queried entity, must be - * a one-to-one or a many-to-one property. - * @param value the value the field of the entity must be equals to argument + * @param property the name of a field of the queried entity, must be a one-to-one or a many-to-one property. + * @param value the value the field of the entity must be equals to + * @return the current or next step for a fluent interface usage */ TopiaQueryBuilderAddCriteriaOrRunQueryStep<E> addEquals(String property, Object value); /** - * @param property the name of a field of the queried entity, must be - * a one-to-one or a many-to-one property. - * @param value the value the field of the entity must not be equals to argument + * @param property the name of a field of the queried entity, must be a one-to-one or a many-to-one property. + * @param value the value the field of the entity must not be equals to + * @return the current or next step for a fluent interface usage */ TopiaQueryBuilderAddCriteriaOrRunQueryStep<E> addNotEquals(String property, Object value); /** - * @param property the name of a field of the queried entity, must be - * a one-to-one or a many-to-one property - * @param values the value the field of the entity must be equals to one of the given values + * @param property the name of a field of the queried entity, must be a one-to-one or a many-to-one property + * @param values a collection of values the field of the entity must be equals to + * @return the current or next step for a fluent interface usage */ TopiaQueryBuilderAddCriteriaOrRunQueryStep<E> addIn(String property, Collection<?> values); /** - * @param property the name of a field of the queried entity, must be - * a one-to-one or a many-to-one property - * @param values the value the field of the entity must not be equals to any of the given values + * @param property the name of a field of the queried entity, must be a one-to-one or a many-to-one property + * @param values the value the field of the entity must not be equals to + * @return the current or next step for a fluent interface usage */ TopiaQueryBuilderAddCriteriaOrRunQueryStep<E> addNotIn(String property, Collection<?> values); /** - * @param property the name of a field of the queried entity, must be - * a one-to-many or a many-to-many property - * @param value the property of the entity must be a collection that contains value + * @param property the name of a field of the queried entity, must be a one-to-many or a many-to-many property + * @param value the property of the entity must be a collection that contains value + * @return the current or next step for a fluent interface usage */ TopiaQueryBuilderAddCriteriaOrRunQueryStep<E> addContains(String property, Object value); /** - * @param property the name of a field of the queried entity, must be - * a one-to-many or a many-to-many property - * @param value the property of the entity must be a collection that doesn't contain value + * @param property the name of a field of the queried entity, must be a one-to-many or a many-to-many property + * @param value the property of the entity must be a collection that doesn't contain value + * @return the current or next step for a fluent interface usage */ TopiaQueryBuilderAddCriteriaOrRunQueryStep<E> addNotContains(String property, Object value); /** - * @param property the name of a field of the queried entity, must be - * a one-to-one or a many-to-one property + * @param property the name of a field of the queried entity, must be a one-to-one or a many-to-one property + * @return the current or next step for a fluent interface usage */ TopiaQueryBuilderAddCriteriaOrRunQueryStep<E> addNull(String property); /** - * @param property the name of a field of the queried entity, must be - * a one-to-one or a many-to-one property + * @param property the name of a field of the queried entity, must be a one-to-one or a many-to-one property + * @return the current or next step for a fluent interface usage */ TopiaQueryBuilderAddCriteriaOrRunQueryStep<E> addNotNull(String property); /** - * This method has the same behavior as {@link #addEquals(String, Object)} but - * you don't need to have the entity but only the topiaId. + * This method has the same behavior as {@link #addEquals(String, Object)} but you don't need to have the entity but + * only the topiaId. * - * @param property the name of a field of the queried entity, must be - * a one-to-one or a many-to-one property - * @param topiaId the + * @param property the name of a field of the queried entity, must be a one-to-one or a many-to-one property + * @param topiaId the value the topiaId of the entity must be equals to + * @return the current or next step for a fluent interface usage */ TopiaQueryBuilderAddCriteriaOrRunQueryStep<E> addTopiaIdEquals(String property, String topiaId); - TopiaQueryBuilderAddCriteriaOrRunQueryStep<E> addTopiaIdIn(String property, Collection<String> topiaIds); - + /** + * This method has the same behavior as {@link #addNotEquals(String, Object)} but you don't need to have the entity + * but only the topiaId. + * + * @param property the name of a field of the queried entity, must be a one-to-one or a many-to-one property + * @param topiaId the value the topiaId of the entity must not be equals to + * @return the current or next step for a fluent interface usage + */ TopiaQueryBuilderAddCriteriaOrRunQueryStep<E> addTopiaIdNotEquals(String property, String topiaId); - TopiaQueryBuilderAddCriteriaOrRunQueryStep<E> addTopiaIdNotIn(String property, Collection<String> topiaIds); - - TopiaQueryBuilderRunQueryStep<E> setOrderByArguments(Set<String> orderByArguments); - - TopiaQueryBuilderRunQueryStep<E> setOrderByArguments(String... orderByArguments); + /** + * This method has the same behavior as {@link #addIn(String, Collection)} but you don't need to have the entity but + * only the topiaId. + * + * @param property the name of a field of the queried entity, must be a one-to-one or a many-to-one property + * @param topiaIds a collection of values the topiaId of the entity must be equals to + * @return the current or next step for a fluent interface usage + */ + TopiaQueryBuilderAddCriteriaOrRunQueryStep<E> addTopiaIdIn(String property, Collection<String> topiaIds); - TopiaQueryBuilderRunQueryStep<E> setOrderByArguments(Collection<PaginationOrder> paginationOrders); + /** + * This method has the same behavior as {@link #addNotIn(String, Collection)} but you don't need to have the entity + * but only the topiaId. + * + * @param property the name of a field of the queried entity, must be a one-to-one or a many-to-one property + * @param topiaIds a collection of values the topiaId of the entity must not be equals to + * @return the current or next step for a fluent interface usage + */ + TopiaQueryBuilderAddCriteriaOrRunQueryStep<E> addTopiaIdNotIn(String property, Collection<String> topiaIds); + /** + * @param property a property to load (fetch) with the entity(ies) (in a single query) + * @return the current or next step for a fluent interface usage + */ TopiaQueryBuilderAddCriteriaOrRunQueryStep<E> addFetch(String property); /** - * @param property a property to load (fetch) with the entity(ies) (in a single query) + * @param property a property to load (fetch) with the entity(ies) (in a single query) * @param otherProperties an optional array of additional properties to load (fetch) with the entity(ies) + * @return the current or next step for a fluent interface usage */ TopiaQueryBuilderAddCriteriaOrRunQueryStep<E> addAllFetches(String property, String... otherProperties); /** * @param properties a collection of properties to load (fetch) with the entity(ies) (in a single query) + * @return the current or next step for a fluent interface usage */ TopiaQueryBuilderAddCriteriaOrRunQueryStep<E> addAllFetches(Collection<String> properties); + /** + * @param orderByArguments list of arguments that will be added as order by + * @return the next step as this method must be used at the end + */ + TopiaQueryBuilderRunQueryStep<E> setOrderByArguments(Set<String> orderByArguments); + + /** + * @param orderByArguments list of arguments that will be added as order by + * @return the next step as this method must be used at the end + */ + TopiaQueryBuilderRunQueryStep<E> setOrderByArguments(String... orderByArguments); + + /** + * @param paginationOrders list of {@link PaginationOrder} that will be added as order by + * @return the next step as this method must be used at the end + * @see PaginationOrder + */ + TopiaQueryBuilderRunQueryStep<E> setOrderByArguments(Collection<PaginationOrder> paginationOrders); + } diff --git a/topia-persistence/src/main/java/org/nuiton/topia/persistence/TopiaQueryBuilderRunQueryStep.java b/topia-persistence/src/main/java/org/nuiton/topia/persistence/TopiaQueryBuilderRunQueryStep.java index 7a38e26..2e48c2f 100644 --- a/topia-persistence/src/main/java/org/nuiton/topia/persistence/TopiaQueryBuilderRunQueryStep.java +++ b/topia-persistence/src/main/java/org/nuiton/topia/persistence/TopiaQueryBuilderRunQueryStep.java @@ -40,13 +40,16 @@ import java.util.List; * Some methods return an {@link Optional}, but since it's not yet available in JDK, we use Guava's. If you don't want * your project to require Guava dependency, we provide equivalent method named XXXOrNull() for the same purpose. * + * @author bleny + * @author Arnaud Thimel (Code Lutin) * @since 3.0 */ -public interface TopiaQueryBuilderRunQueryStep<E extends TopiaEntity> extends TopiaQueryBuilderRunQueryWithUniqueResultStep<E> { +public interface TopiaQueryBuilderRunQueryStep<E extends TopiaEntity> + extends TopiaQueryBuilderRunQueryWithUniqueResultStep<E> { /** - * This method is equivalent as calling {@link java.util.Collection#size()} - * after doing a {@link #findAll()} but it may be faster. + * This method is equivalent as calling {@link java.util.Collection#size()} after doing a {@link #findAll()} but it + * may be faster. * * @return the number of that the query would have returned, if executed */ @@ -55,69 +58,178 @@ public interface TopiaQueryBuilderRunQueryStep<E extends TopiaEntity> extends To /** * Get the first element of the non-empty result set. * - * @return the first value from the set of result, - * according to given order. Returned value - * can't be null - * @throws QueryMissingOrderException if you the query - * misses an order clause + * @return the first value from the set of result, according to given order. Returned value can't be null + * @throws QueryMissingOrderException if you the query misses an order clause + * @throws TopiaNoResultException if the query does not return any result */ E findFirst() throws QueryMissingOrderException, TopiaNoResultException; /** - * Get the first element of the result set or null if - * query result was empty. + * Get the first element of the result set or null if query result is empty. * <p/> - * This method duplicates {@link #tryFindFirst()} - * but allows you to prevent using Guava in you project. + * This method duplicates {@link #tryFindFirst()} but allows you to prevent using Guava in you project. * - * @return the first value from the set of result, - * according to given order, or null of result - * set for given query was empty - * @throws QueryMissingOrderException if you the query - * misses an order clause + * @return the first value from the set of result, according to given order, or null of result set for given query + * is empty + * @throws QueryMissingOrderException if you the query misses an order clause */ E findFirstOrNull() throws QueryMissingOrderException; /** * Get the first element of the result set. * <p/> - * This method duplicates {@link #tryFindFirst()} - * but allows you to prevent using Guava in you project. - * <p/> * If the call must return a result, prefer {@link #findFirst()} * - * @return the first value from the set of result, - * according to given order. It's an optional - * because the query may return no result. - * @throws QueryMissingOrderException if you the query - * misses an order clause + * @return the first value from the set of result, according to given order. It's an optional because the query may + * return no result. + * @throws QueryMissingOrderException if you the query misses an order clause */ Optional<E> tryFindFirst() throws QueryMissingOrderException; + /** + * Get the an element of the non-empty result set. + * <p/> + * This method does not guarantee any order as no ordering clause is mandatory + * + * @return the first value from the set of result, without any order guarantee. Returned value can't be null + * @throws TopiaNoResultException if the query does not return any result + */ E findAny() throws TopiaNoResultException; + /** + * Get the an element of the result set or null if query result is empty. + * <p/> + * This method does not guarantee any order as no ordering clause is mandatory. + * <p/> + * This method duplicates {@link #tryFindAny()} but allows you to prevent using Guava in you project. + * + * @return the first value from the set of result, without any order guarantee. Returned value can be null + */ E findAnyOrNull(); + /** + * Get the an element of the result set. + * <p/> + * This method does not guarantee any order as no ordering clause is mandatory. + * <p/> + * If the call must return a result, prefer {@link #findAny()} + * + * @return the first value from the set of result, without any order guarantee. It's an optional because the query + * may return no result. + */ Optional<E> tryFindAny(); + /** + * Get all the elements of the result set. + * + * @return the full list of results. + */ List<E> findAll(); + /** + * Get all the elements in a lazy loading list. The entities will be loaded gradually when the returned Iterable is + * iterated. + * <p/> + * If you wish to specify a batch size, use {@link #findAllLazy(int)} + * + * @return the full list of results which will be loaded gradually. + */ Iterable<E> findAllLazy(); + /** + * Get all the elements in a lazy loading list. The entities will be loaded gradually when the returned Iterable is + * iterated. + * <p/> + * If you do not need to specify a batch size, use {@link #findAllLazy()} + * + * @param batchSize the number of elements to load per request + * @return the full list of results which will be loaded gradually. + */ Iterable<E> findAllLazy(int batchSize); + /** + * Get the elements with the given bounds. + * + * @param startIndex inclusive index of the first element to return. This value is 0-based + * @param endIndex inclusive index of the last element to return. A value lower than 0 means infinite upper bound. + * @return the list of loaded results. + */ List<E> find(int startIndex, int endIndex); + /** + * Get the elements according to the given {@link PaginationParameter}. + * <p/> + * Use {@link #findPage(PaginationParameter)} to get a {@link PaginationResult} instead of a list. + * + * @param page information about the page to load. + * @return the list of loaded results. + * @see org.nuiton.util.pagination.PaginationParameter + */ List<E> find(PaginationParameter page); + /** + * Get the elements according to the given {@link PaginationParameter}. + * <p/> + * Use {@link #find(PaginationParameter)} to get a list instead of {@link PaginationResult}. + * <p/> + * Note: compared to {@link #find(PaginationParameter)}, this method performs an additional statement to get the + * total elements count. + * + * @param page information about the page to load. + * @return the list of loaded results. + * @see org.nuiton.util.pagination.PaginationParameter + * @see org.nuiton.util.pagination.PaginationResult + */ PaginationResult<E> findPage(PaginationParameter page); + /** + * Get all the elements identifiers of the result set. + * <p/> + * Note: compared to {@link #findAll()}, this method will not load entities, only its identifier. + * + * @return the full list of results ids. + */ List<String> findAllIds(); + /** + * Get the elements identifiers with the given bounds. + * <p/> + * Note: compared to {@link #find(int, int)}, this method will not load entities, only its identifier. + * + * @param startIndex inclusive index of the first element to return. This value is 0-based + * @param endIndex inclusive index of the last element to return. A value lower than 0 means infinite upper bound. + * @return the list of loaded results ids. + */ List<String> findIds(int startIndex, int endIndex); + /** + * Get the elements identifiers according to the given {@link PaginationParameter}. + * <p/> + * Use {@link #findIdsPage(PaginationParameter)} to get a {@link PaginationResult} instead of a list. + * <p/> + * Note: compared to {@link #find(PaginationParameter)}, this method will not load entities, only its identifier. + * + * @param page information about the page to load. + * @return the list of loaded results ids. + * @see org.nuiton.util.pagination.PaginationParameter + */ List<String> findIds(PaginationParameter page); + /** + * Get the elements identifiers according to the given {@link PaginationParameter}. + * <p/> + * Use {@link #findIds(PaginationParameter)} to get a list instead of {@link PaginationResult}. + * <p/> + * Note: compared to {@link #findIds(PaginationParameter)}, this method performs an additional statement to get the + * total elements identifiers count. + * <p/> + * Note: compared to {@link #findPage(PaginationParameter)}, this method will not load entities, only its identifier + * + * @param page information about the page to load. + * @return the list of loaded results. + * @see org.nuiton.util.pagination.PaginationParameter + * @see org.nuiton.util.pagination.PaginationResult + */ PaginationResult<String> findIdsPage(PaginationParameter page); } diff --git a/topia-persistence/src/main/java/org/nuiton/topia/persistence/TopiaQueryBuilderRunQueryWithUniqueResultStep.java b/topia-persistence/src/main/java/org/nuiton/topia/persistence/TopiaQueryBuilderRunQueryWithUniqueResultStep.java index af13f8e..8a31d85 100644 --- a/topia-persistence/src/main/java/org/nuiton/topia/persistence/TopiaQueryBuilderRunQueryWithUniqueResultStep.java +++ b/topia-persistence/src/main/java/org/nuiton/topia/persistence/TopiaQueryBuilderRunQueryWithUniqueResultStep.java @@ -27,9 +27,9 @@ package org.nuiton.topia.persistence; import com.google.common.base.Optional; /** - * A subset of {@link TopiaQueryBuilderRunQueryStep} for certain API methods that should - * not allow findAll. + * A subset of {@link TopiaQueryBuilderRunQueryStep} for certain API methods that should not allow findAll. * + * @author bleny * @since 3.0 */ public interface TopiaQueryBuilderRunQueryWithUniqueResultStep<E extends TopiaEntity> { @@ -39,10 +39,33 @@ public interface TopiaQueryBuilderRunQueryWithUniqueResultStep<E extends TopiaEn */ boolean exists(); + /** + * Get the first element of a single-element result set. + * + * @return the first value from the set of result. Returned value can't be null + * @throws TopiaNonUniqueResultException if the query returns more than one element. + * @throws TopiaNoResultException if the query does not return any result. + */ E findUnique() throws TopiaNoResultException, TopiaNonUniqueResultException; + /** + * Get the first element of a single-element result set or null if query result is empty. + * <p/> + * This method duplicates {@link #tryFindUnique()} but allows you to prevent using Guava in you project. + * + * @return the first value from the set of result, or null of result set for given query is empty. + * @throws TopiaNonUniqueResultException if the query returns more than one element. + */ E findUniqueOrNull() throws TopiaNonUniqueResultException; + /** + * Get the first element of a single-element result set. + * <p/> + * If the call must return a result, prefer {@link #findUnique()} + * + * @return the first value from the set of result. It's an optional because the query may return no result. + * @throws TopiaNonUniqueResultException if the query returns more than one element. + */ Optional<E> tryFindUnique() throws TopiaNonUniqueResultException; } -- To stop receiving notification emails like this one, please contact nuiton.org SCM administrator <admin+scm@nuiton.org>.