Pagination ================================================================================ .. only:: html .. contents:: Table of Contents :depth: 3 :local: Overview -------------------------------------------------------------------------------- This chapter describes the Pagination functionality wherein the data matching the search criteria is divided into pages and displayed. | **It is recommended to use pagination functionality when a large amount of data matches the search criteria.** | Retrieving and displaying a large amount of data at a time on screen may lead to following problems. * | Memory exhaustion at server side | ``java.lang.OutOfMemoryError`` occurs when multiple requests are executed simultaneously. * | Network load | Transferring unnecessary data over the network results in increased network load and thereby may affect the response time of the entire system. * | Delay in response on screen | Server process, network traffic process and client rendering process take time to handle a large amount of data; hence the response on screen may get delayed. | Display of list screen at the time of dividing into pages ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ When a page is divided using pagination, the screen looks as follows: .. figure:: ./images/pagination-overview_screen.png :alt: Screen image of Pagination. :width: 100% .. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}| .. list-table:: :header-rows: 1 :widths: 10 90 * - Sr. No. - Description * - | (1) - | Display the link to navigate to various pages. | On clicking link, send a request to display the corresponding page. JSP tag library to display this area is provided as common library. * - | (2) - | Display the information related to pagination (total records, total pages and number of displayed pages etc.). | Tag library to display this area does not exist; hence it should be implemented separately as JSP processing. | Page search ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | For implementing pagination, it is essential to first implement the server-side search processing to make page searching possible. | It is assumed in this guideline that the mechanism provided by Spring Data is used for page search at server side. | .. _pagination_overview_page_springdata: Page search functionality of Spring Data """""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" Page search functionality provided by Spring Data is as follows: .. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}| .. list-table:: :header-rows: 1 :widths: 10 90 * - Sr. No. - Description * - 1 - | Extract the information required for page search (location of page to be searched, number of records to be fetched and sort condition) from request parameter and pass the extracted information as objects of ``org.springframework.data.domain.Pageable`` to the argument of Controller. | This functionality is provided as ``org.springframework.data.web.PageableHandlerMethodArgumentResolver`` class and is enabled by adding to ```` element of :file:`spring-mvc.xml` . | For request parameters, refer to ":ref:`Note column `". * - 2 - | Save the page information (total records, data of corresponding page, location of page to be searched, number of records to be fetched and sort condition). | This functionality is provided as ``org.springframework.data.domain.Page`` interface and ``org.springframework.data.domain.PageImpl`` is provided as default implementation class. | **As per specifications, it fetches the required data from Page object in JSP tag library to output pagination link provided by common library.** * - 3 - | When Spring Data JPA is used for database access, the information of corresponding page is returned as ``Page`` object by specifying ``Pageable`` object as an argument of Repository Query method. | All the processes such as executing SQL to fetch total records, adding sort condition and extracting data matching the corresponding page are carried out automatically. | When MyBatis is used for database access, the process that is automatically carried out in Spring Data JPA needs to be implemented in Java (Service) and SQL mapping file. .. _pagination_overview_pagesearch_requestparameter: .. note:: **Request parameters for page search** Request parameters for page search provided by Spring Data are as follows: .. tabularcolumns:: |p{0.10\linewidth}|p{0.15\linewidth}|p{0.75\linewidth}| .. list-table:: :header-rows: 1 :widths: 10 15 75 * - Sr. No. - Parameter name - Description * - 1. - page - | Request parameter to specify the location of page to be searched | Specify value greater than or equal to 0. | As per default setting, page location starts from ``0`` (zero). Hence, specify ``0`` (zero) to fetch the data of the first page and ``1`` (one) to fetch the data of the second page. * - 2. - size - | Request parameter to specify the count of fetched records. | Specify value greater than or equal to 1. | When value specified is greater than the value in ``maxPageSize`` of ``PageableHandlerMethodArgumentResolver``, ``maxPageSize`` value becomes ``size`` value. * - 3. - sort - | Parameter to specify sort condition (multiple parameters can be specified). | Specify the value in ``"{sort item name(,sort order)}"`` format. | Specify either ``"ASC"`` or ``"DESC"`` as sort order. When nothing is specified, ``"ASC"`` is used. | Multiple item names can be specified using ``","`` separator. | For example, when ``"sort=lastModifiedDate,id,DESC&sort=subId"`` is specified as query string, Order By clause ``"ORDER BY lastModifiedDate DESC, id DESC, subId ASC"`` is added to the query. .. warning:: **Operations at the time of specifying "size=0" in spring-data-commons 1.6.1.RELEASE** spring-data-commons 1.6.1.RELEASE having terasoluna-gfw-common 1.0.0.RELEASE has a bug wherein if ``"size=0"`` is specified, all the records matching the specified condition are fetched. As a result, ``java.lang.OutOfMemoryError`` may occur when a large amount of records are fetched. This problem is handled using JIRA `DATACMNS-377 `_ of Spring Data Commons and is being resolved in spring-data-commons 1.6.3.RELEASE. Post modification, if ``"size<=0"`` is specified, the default value when size parameter is omitted will be applied. In cases where terasoluna-gfw-common 1.0.0.RELEASE is used, the version should be upgraded to terasoluna-gfw-common 1.0.1.RELEASE or higher version. .. warning:: **About operations when invalid values are specified in request parameters of spring-data-commons 1.6.1.RELEASE** spring-data-commons 1.6.1.RELEASE having terasoluna-gfw-common 1.0.0.RELEASE has a bug wherein if an invalid value is specified in request parameters for page search (page, size, sort etc.), ``java.lang.IllegalArgumentException`` or ``java.lang.ArrayIndexOutOfBoundsException`` occurs and SpringMVC settings when set to default values leads to system error (HTTP status code=500). This problem is handled using JIRA `DATACMNS-379 `_ and `DATACMNS-408 `_ and is being resolved in spring-data-commons 1.6.3.RELEASE. Post modification, if invalid values are specified, the default value when parameters are omitted will be applied. In cases where terasoluna-gfw-common 1.0.0.RELEASE is used, the version should be upgraded to terasoluna-gfw-common 1.0.1.RELEASE or higher version. .. note:: **Points to be noted due to the changes in API specifications of Spring Data Commons** In case of "terasoluna-gfw-common 5.0.0.RELEASE or later version" dependent spring-data-commons (1.9.1 RELEASE or later), there is a change in API specifications of interface for page search functionality (\ ``org.springframework.data.domain.Page``\ ) and class (\ ``org.springframework.data.domain.PageImpl``\ and \ ``org.springframework.data.domain.Sort.Order``\ ). Specifically, * In \ ``Page``\ interface and \ ``PageImpl``\ class, \ ``isFirst()``\ and \ ``isLast()``\ methods are added in spring-data-commons 1.8.0.RELEASE, and \ ``isFirstPage()``\ and \ ``isLastPage()``\ methods are deleted from spring-data-commons 1.9.0.RELEASE. * In \ ``Sort.Order``\ class, \ ``nullHandling``\ property is added in spring-data-commons 1.8.0.RELEASE. If deleted API is used, there will be a compilation error and application will have to be modified. In addition, when using \ ``Page``\ interface (\ ``PageImpl``\ class) as resource object of REST API, that application may also need to be modified, as JSON and XML format get changed. | .. _pagination_overview_paginationlink: Display of pagination link ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | This section describes the pagination link which is output using JSP tag library of common library. | Style sheet to display pagination link is not provided from common library, hence it should be created in each project. | Bootstrap v3.0.0 style sheet is applied for the screens used in the explanation below. | Structure of pagination link """""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" Pagination link consists of the following elements. .. figure:: ./images/pagination-how_to_use_jsp_pagelink_description.png :alt: Structure of the pagination link. :width: 90% :align: center .. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}| .. list-table:: :header-rows: 1 :widths: 10 90 * - Sr. No. - Description * - | (1) - | Link to navigate to the first page. * - | (2) - | Link to navigate to the previous page. * - | (3) - | Link to navigate to the specified page. * - | (4) - | Link to navigate to the next page. * - | (5) - | Link to navigate to the last page. | Pagination link has the following status. .. figure:: ./images/pagination-how_to_use_jsp_pagelink_description_status.png :alt: Status of the pagination link. :width: 90% :align: center .. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}| .. list-table:: :header-rows: 1 :widths: 10 90 * - Sr. No. - Description * - | (6) - | Status indicating link where operations cannot be performed on the currently displayed page. | The status is specifically "Link to navigate to the first page" and "Link to navigate to the previous page" when the first page is displayed and "Link to navigate to the next page" "Link to navigate to the last page" when the last page is displayed. | This status is defined as ``"disabled"`` in the JSP tag library of common library. * - | (7) - | Status indicating currently displayed page. | This status is defined as ``"active"`` in the JSP tag library of common library. | | HTML to be output using common library is as follows: | The numbers in figure correspond to serial numbers of "Structure of pagination link" and "Status of pagination link" mentioned above. - JSP .. code-block:: jsp - HTML to be output .. figure:: ./images/pagination-overview_html.png :alt: html of the pagination link. :width: 90% :align: center | HTML of pagination link """""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" HTML of pagination link to be output using common library is as follows: - HTML .. figure:: ./images/pagination-overview_html_basic.png :alt: html structure of the pagination link. :width: 100% :align: center - Screen image .. figure:: ./images/pagination-overview_html_basic_screen.png :alt: screen structure of the pagination link. :width: 80% :align: center .. tabularcolumns:: |p{0.10\linewidth}|p{0.70\linewidth}|p{0.20\linewidth}| .. list-table:: :header-rows: 1 :widths: 10 70 20 * - Sr. No. - Description - Default values * - | (1) - | Elements to combine the components of pagination link. | In common library, this part is called "Outer Element" which stores multiple "Inner Elements". | The elements to be used can be changed using the parameters of JSP tag library. - | ``