Author: athimel Date: 2014-05-22 11:37:07 +0200 (Thu, 22 May 2014) New Revision: 2628 Url: http://forge.nuiton.org/projects/nuiton-utils/repository/revisions/2628 Log: refs #3211 Improve implementation, tests and documentation Added: trunk/src/main/java/org/nuiton/util/pagination/package-info.java Modified: trunk/src/main/java/org/nuiton/util/PagerBean.java trunk/src/main/java/org/nuiton/util/pagination/PaginationParameter.java trunk/src/main/java/org/nuiton/util/pagination/PaginationResult.java trunk/src/test/java/org/nuiton/util/pagination/PaginationParameterTest.java Modified: trunk/src/main/java/org/nuiton/util/PagerBean.java =================================================================== --- trunk/src/main/java/org/nuiton/util/PagerBean.java 2014-05-22 08:57:52 UTC (rev 2627) +++ trunk/src/main/java/org/nuiton/util/PagerBean.java 2014-05-22 09:37:07 UTC (rev 2628) @@ -35,7 +35,9 @@ * * @author tchemit <chemit@codelutin.com> * @since 2.6.2 + * @deprecated since 3.0, prefer using {@link org.nuiton.util.pagination.PaginationParameter}. */ +@Deprecated public class PagerBean implements Serializable { private static final long serialVersionUID = 1L; Modified: trunk/src/main/java/org/nuiton/util/pagination/PaginationParameter.java =================================================================== --- trunk/src/main/java/org/nuiton/util/pagination/PaginationParameter.java 2014-05-22 08:57:52 UTC (rev 2627) +++ trunk/src/main/java/org/nuiton/util/pagination/PaginationParameter.java 2014-05-22 09:37:07 UTC (rev 2628) @@ -43,8 +43,19 @@ private static final long serialVersionUID = -2564463476779099397L; + /** + * 0-based page number + */ protected int pageNumber; + + /** + * The size of each page. Value can be -1 (for infinite pageSize) or greater than 0 + */ protected int pageSize; + + /** + * The list of order clauses. This instance is unmodifiable and never null. + */ protected List<PaginationOrder> orderClauses; private PaginationParameter(int pageNumber, int pageSize) { @@ -52,16 +63,41 @@ } private PaginationParameter(int pageNumber, int pageSize, List<PaginationOrder> orderClauses) { + Preconditions.checkArgument(pageNumber >= 0, "pageNumber cannot be lower than 0"); + Preconditions.checkArgument(pageSize == -1 || pageSize > 0, "pageSize can only be -1 or greater than 0"); + Preconditions.checkArgument(pageSize != -1 || pageNumber == 0, "This is non-sense to have pageNumber>1 if pageSize==-1"); this.pageNumber = pageNumber; this.pageSize = pageSize; this.orderClauses = Collections.unmodifiableList(orderClauses); } + /** + * Method to create a PaginationParameter only based on pageNumber and pageSize (no order clauses). + * + * @param pageNumber the index (0-based) of the page + * @param pageSize the size of each page. Value can be -1 (for infinite pageSize) or greater than 0 + * @return an immutable PaginationParameter instance + */ public static PaginationParameter of(int pageNumber, int pageSize) { PaginationParameter result = new PaginationParameter(pageNumber, pageSize); return result; } + /** + * Method to create a PaginationParameter based on pageNumber, pageSize and a single order clause. + * <p/> + * If you have an unknown number of order clauses, you should use the {@link #builder(int, int)} + * method together with {@link org.nuiton.util.pagination.PaginationParameter.Builder#addOrder(String, boolean)} and + * {@link org.nuiton.util.pagination.PaginationParameter.Builder#build()} methods. + * + * @param pageNumber the index (0-based) of the page + * @param pageSize the size of each page. Value can be -1 (for infinite pageSize) or greater than 0 + * @param orderClause1 an order clause attribute name. It comes together with {code}orderDesc1{/code} + * @param orderDesc1 the asc/desc property associated with {code}orderClause1{/code} + * @return an immutable PaginationParameter instance + * @see org.nuiton.util.pagination.PaginationOrder + * @see org.nuiton.util.pagination.PaginationParameter.Builder + */ public static PaginationParameter of(int pageNumber, int pageSize, String orderClause1, boolean orderDesc1) { return builder(pageNumber, pageSize) @@ -69,6 +105,23 @@ .build(); } + /** + * Method to create a PaginationParameter based on pageNumber, pageSize and two order clauses. + * <p/> + * If you have an unknown number of order clauses, you should use the {@link #builder(int, int)} + * method together with {@link org.nuiton.util.pagination.PaginationParameter.Builder#addOrder(String, boolean)} and + * {@link org.nuiton.util.pagination.PaginationParameter.Builder#build()} methods. + * + * @param pageNumber the index (0-based) of the page + * @param pageSize the size of each page. Value can be -1 (for infinite pageSize) or greater than 0 + * @param orderClause1 an order clause attribute name. It comes together with {code}orderDesc1{/code} + * @param orderDesc1 the asc/desc property associated with {code}orderClause1{/code} + * @param orderClause2 an order clause attribute name. It comes together with {code}orderDesc2{/code} + * @param orderDesc2 the asc/desc property associated with {code}orderClause2{/code} + * @return an immutable PaginationParameter instance + * @see org.nuiton.util.pagination.PaginationOrder + * @see org.nuiton.util.pagination.PaginationParameter.Builder + */ public static PaginationParameter of(int pageNumber, int pageSize, String orderClause1, boolean orderDesc1, String orderClause2, boolean orderDesc2) { @@ -78,6 +131,25 @@ .build(); } + /** + * Method to create a PaginationParameter based on pageNumber, pageSize and three order clauses. + * <p/> + * If you have more order clauses, or an unknown number of clauses, you should use the {@link #builder(int, int)} + * method together with {@link org.nuiton.util.pagination.PaginationParameter.Builder#addOrder(String, boolean)} and + * {@link org.nuiton.util.pagination.PaginationParameter.Builder#build()} methods. + * + * @param pageNumber the index (0-based) of the page + * @param pageSize the size of each page. Value can be -1 (for infinite pageSize) or greater than 0 + * @param orderClause1 an order clause attribute name. It comes together with {code}orderDesc1{/code} + * @param orderDesc1 the asc/desc property associated with {code}orderClause1{/code} + * @param orderClause2 an order clause attribute name. It comes together with {code}orderDesc2{/code} + * @param orderDesc2 the asc/desc property associated with {code}orderClause2{/code} + * @param orderClause3 an order clause attribute name. It comes together with {code}orderDesc3{/code} + * @param orderDesc3 the asc/desc property associated with {code}orderClause3{/code} + * @return an immutable PaginationParameter instance + * @see org.nuiton.util.pagination.PaginationOrder + * @see org.nuiton.util.pagination.PaginationParameter.Builder + */ public static PaginationParameter of(int pageNumber, int pageSize, String orderClause1, boolean orderDesc1, String orderClause2, boolean orderDesc2, @@ -89,6 +161,13 @@ .build(); } + /** + * Method to create a PaginationParameter using the {@link org.nuiton.util.pagination.PaginationParameter.Builder}. + * + * @param pageNumber the index (0-based) of the page + * @param pageSize the size of each page. Value can be -1 (for infinite pageSize) or greater than 0 + * @return an immutable PaginationParameter.Builder instance + */ public static PaginationParameter.Builder builder(int pageNumber, int pageSize) { Builder result = new Builder(pageNumber, pageSize); return result; @@ -106,6 +185,11 @@ return orderClauses; } + /** + * Method that computes the start index of a page according to {@link #pageNumber} and {@link #pageSize}. + * + * @return the computed start index + */ public int getStartIndex() { if (pageNumber != 0) { Preconditions.checkState(pageSize != -1, "This is non-sense to have pageNumber>1 if pageSize==-1"); @@ -114,6 +198,12 @@ return startIndex; } + /** + * Method that computes the end index of a page according to {@link #pageNumber} and {@link #pageSize}. If the + * pageSize is -1, the end index will be {@link Integer#MAX_VALUE}. + * + * @return the computed end index + */ public int getEndIndex() { int endIndex = Integer.MAX_VALUE; if (pageSize != -1) { @@ -123,7 +213,11 @@ } /** - * Class used to build an instance of PaginationParameter + * Class used to build an instance of PaginationParameter. Use the {@link #build()} method to create the + * {@link org.nuiton.util.pagination.PaginationParameter}. + * + * @author Arnaud Thimel (Code Lutin) + * @since 3.0 */ public static class Builder { @@ -131,11 +225,24 @@ protected int pageSize; protected List<PaginationOrder> orderClauses; + /** + * Creates a Builder instance + * + * @param pageNumber the index (0-based) of the page + * @param pageSize the size of each page. Value can be -1 (for infinite pageSize) or greater than 0 + */ public Builder(int pageNumber, int pageSize) { this.pageNumber = pageNumber; this.pageSize = pageSize; } + /** + * Adds an order clause + * + * @param clause an order clause attribute name. It comes together with {code}desc{/code} + * @param desc the asc/desc property associated with {code}clause{/code} + * @return the current Builder for a Fluent usage + */ public Builder addOrder(String clause, boolean desc) { if (orderClauses == null) { orderClauses = Lists.newLinkedList(); @@ -145,14 +252,33 @@ return this; } + /** + * Adds an ASC order clause + * + * @param clause an order clause attribute name + * @return the current Builder for a Fluent usage + */ public Builder addAscOrder(String clause) { return addOrder(clause, false); } + /** + * Adds an DESC order clause + * + * @param clause an order clause attribute name + * @return the current Builder for a Fluent usage + */ public Builder addDescOrder(String clause) { return addOrder(clause, true); } + /** + * Adds an order clause. The asc/desc value is guessed from the given {code}clause{/code}. The expected format + * is "column asc" or "column desc" + * + * @param clause an order clause attribute name. It comes together with {code}desc{/code} + * @return the current Builder for a Fluent usage + */ public Builder addOrder(String clause) { boolean desc = false; String cleanedClause = clause; @@ -164,6 +290,12 @@ return addOrder(cleanedClause, desc); } + /** + * Adds an the given order clauses + * + * @param clauses an list of order clauses + * @return the current Builder for a Fluent usage + */ public Builder addOrderClauses(Iterable<PaginationOrder> clauses) { if (orderClauses == null) { orderClauses = Lists.newLinkedList(); @@ -174,6 +306,11 @@ return this; } + /** + * Final method that instantiates the immutable PaginationParameter + * + * @return the immutable PaginationParameter built + */ public PaginationParameter build() { PaginationParameter result = new PaginationParameter(pageNumber, pageSize, orderClauses); return result; Modified: trunk/src/main/java/org/nuiton/util/pagination/PaginationResult.java =================================================================== --- trunk/src/main/java/org/nuiton/util/pagination/PaginationResult.java 2014-05-22 08:57:52 UTC (rev 2627) +++ trunk/src/main/java/org/nuiton/util/pagination/PaginationResult.java 2014-05-22 09:37:07 UTC (rev 2628) @@ -31,7 +31,8 @@ /** * Represents the result of a pagination request. It contains the result elements together with the - * {code}PaginationParameter{/code} used to compute it. + * {@link org.nuiton.util.pagination.PaginationParameter} used to compute it. The class also contains methods to + * navigate through the other pages. * * @author Arnaud Thimel (Code Lutin) * @since 3.0 @@ -50,6 +51,16 @@ this.currentPage = currentPage; } + /** + * Creates an instance using the already computed list of {code}elements{/code} and {code}count{/count}, together + * with the {code}currentPage{/code} {@link org.nuiton.util.pagination.PaginationParameter} used to build it. + * + * @param elements the list of elements + * @param count the total number of elements (through all pages) + * @param currentPage the PaginationParameter used to build this paged result + * @param <E> any object type + * @return the built instance of PaginationResult + */ public static <E> PaginationResult<E> of(List<E> elements, long count, PaginationParameter currentPage) { PaginationResult<E> result = new PaginationResult<E>(elements, count, currentPage); return result; Copied: trunk/src/main/java/org/nuiton/util/pagination/package-info.java (from rev 2626, trunk/src/main/java/org/nuiton/util/package-info.java) =================================================================== --- trunk/src/main/java/org/nuiton/util/pagination/package-info.java (rev 0) +++ trunk/src/main/java/org/nuiton/util/pagination/package-info.java 2014-05-22 09:37:07 UTC (rev 2628) @@ -0,0 +1,34 @@ +/** + * This package contains all about pagination : <ul> + * <li>{@link org.nuiton.util.pagination.PaginationParameter} to express the input pagination parameters when + * preparing a query</li> + * <li>{@link org.nuiton.util.pagination.PaginationOrder} represents an order clause together with asc/desc</li> + * <li>{@link org.nuiton.util.pagination.PaginationResult} represents a list together with the pagination parameters + * used to get the list of elements. It also contains methods to navigate throw the other pages</li> + * </ul> + */ +package org.nuiton.util.pagination; + +/* + * #%L + * Nuiton Utils + * $Id$ + * $HeadURL$ + * %% + * Copyright (C) 2004 - 2014 CodeLutin + * %% + * This program is free software: you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License as + * published by the Free Software Foundation, either version 3 of the + * License, or (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Lesser Public License for more details. + * + * You should have received a copy of the GNU General Lesser Public + * License along with this program. If not, see + * <http://www.gnu.org/licenses/lgpl-3.0.html>. + * #L% + */ Modified: trunk/src/test/java/org/nuiton/util/pagination/PaginationParameterTest.java =================================================================== --- trunk/src/test/java/org/nuiton/util/pagination/PaginationParameterTest.java 2014-05-22 08:57:52 UTC (rev 2627) +++ trunk/src/test/java/org/nuiton/util/pagination/PaginationParameterTest.java 2014-05-22 09:37:07 UTC (rev 2628) @@ -66,10 +66,28 @@ } } - @Test(expected = IllegalStateException.class) - public void testInvalidIndex() { + @Test(expected = IllegalArgumentException.class) + public void testIncoherentNumbers() { PaginationParameter paginationParameter = PaginationParameter.of(2, -1); paginationParameter.getStartIndex(); } + @Test(expected = IllegalArgumentException.class) + public void testInvalidPageSizeTo0() { + PaginationParameter paginationParameter = PaginationParameter.of(5, 0); + paginationParameter.getStartIndex(); + } + + @Test(expected = IllegalArgumentException.class) + public void testInvalidPageSizeToMinus5() { + PaginationParameter paginationParameter = PaginationParameter.of(5, -5); + paginationParameter.getStartIndex(); + } + + @Test(expected = IllegalArgumentException.class) + public void testInvalidPageNumber() { + PaginationParameter paginationParameter = PaginationParameter.of(-3, 25); + paginationParameter.getStartIndex(); + } + }