[topia] branch develop updated (8d9ae23 -> 6d78297)
This is an automated email from the git hooks/post-receive script. New change to branch develop in repository topia. See http://git.nuiton.org/topia.git from 8d9ae23 Update versions H2 1.4.181 Guava 18.0 nuiton-utils 3.0-rc-7 nuiton-csv 3.0-rc-4 new 6d78297 Complete TopiaQueryBuilder*Step javadoc The 1 revisions listed above as "new" are entirely new to this repository and will be described in separate emails. The revisions listed as "adds" were already present in the repository and have only been added to this reference. Detailed log of new commits: commit 6d7829748f51f9d57ab9a1f89e5ba6e3a27480fd Author: Arnaud Thimel <thimel@codelutin.com> Date: Wed Aug 27 00:01:28 2014 +0200 Complete TopiaQueryBuilder*Step javadoc Summary of changes: ...TopiaQueryBuilderAddCriteriaOrRunQueryStep.java | 2 +- .../TopiaQueryBuilderAddCriteriaStep.java | 118 ++++++++++----- .../persistence/TopiaQueryBuilderRunQueryStep.java | 162 +++++++++++++++++---- ...iaQueryBuilderRunQueryWithUniqueResultStep.java | 27 +++- 4 files changed, 244 insertions(+), 65 deletions(-) -- To stop receiving notification emails like this one, please contact nuiton.org SCM administrator <admin+scm@nuiton.org>.
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>.
participants (1)
-
nuiton.org scm