5.11. ページネーション

Caution

本バージョンの内容は既に古くなっています。最新のガイドラインはこちらからご参照ください。

5.11.1. Overview

本章では、検索条件に一致するデータをページ分割して表示する方法(ページネーション)について説明する。

検索条件に一致するデータが大量になる場合は、ページネーション機能を使用することを推奨する。
一度に大量のデータを取得し画面に表示すると、以下3点の問題が発生する可能性がある。
  • サーバ側のメモリ枯渇の発生。
    単発のリクエストで問題が発生しなくても、同時に複数実行された場合に java.lang.OutOfMemoryError が発生する可能性がある。
  • ネットワーク負荷の発生。
    不要なデータがネットワークに流れることで、ネットワーク全体にかかる負荷が高くなり、システム全体のレスポンスタイムに影響を与える可能性がある。
  • 画面のレスポンス遅延の発生。
    大量のデータを扱う場合、サーバの処理、ネットワークのトラフィック処理、クライアントの描画処理の全てで時間がかかるため、画面のレスポンスが遅くなる可能性がある。

5.11.1.1. ページ分割時の一覧画面の表示について

ページネーション機能を利用してページ分割した場合、以下のような画面になる。

Screen image of Pagination.
項番 説明
(1)
ページを移動するためのリンクを表示する。
リンク押下時には、該当ページを表示するためのリクエストを送信する。この領域を表示するためのJSPタグライブラリを共通ライブラリとして提供している。
(2)
ページネーションに関連する情報(合計件数、合計ページ数、表示ページ数など)を表示する。
この領域を表示するためのタグライブラリは存在しないため、JSPの処理として個別に実装する必要がある。

5.11.1.2. ページ検索について

ページネーションを実現する際には、まずサーバ側で行う検索処理をページ検索できるように実装する必要がある。
本ガイドラインでは、サーバ側のページ検索は、 Spring Data から提供されている仕組みを利用することを前提としている。

5.11.1.2.1. Spring Data提供のページ検索機能について

Spring Dataより提供されているページ検索用の機能は、以下の通り。

項番 説明
1
リクエストパラメータよりページ検索に必要な情報(検索対象のページ位置、取得件数、ソート条件)を抽出し、抽出した情報を org.springframework.data.domain.Pageable のオブジェクトとしてControllerの引数に引き渡す。
この機能は、 org.springframework.data.web.PageableHandlerMethodArgumentResolver クラスとして提供されており、 spring-mvc.xml の <mvc:argument-resolvers> 要素に追加することで有効となる。
リクエストパラメータについては、「 Note欄 」を参照されたい。
2
ページ情報(合計件数、該当ページのデータ、検索対象のページ位置、取得件数、ソート条件)を保持する。
この機能は、 org.springframework.data.domain.Page インタフェースとして提供されており、デフォルトの実装クラスとして org.springframework.data.domain.PageImpl が提供されている。
共通ライブラリより提供しているページネーションリンクを出力するためのJSPタグライブラリでは、 Pageオブジェクトから必要なデータを取得する仕様となっている。
3
データベースアクセスとしてSpring Data JPAを使用する場合は、RepositoryのQueryメソッドの引数に Pageable オブジェクトを指定することで、該当ページの情報が Page オブジェクトとして返却される。
合計件数を取得するSQLの発行、ソート条件の追加、該当ページに一致するデータの抽出などの処理が全て自動で行われる。
データベースアクセスとして、MyBatisを使用する場合は、Spring Data JPAが自動で行ってくれる処理を、Java(Service)及びSQLマッピングファイル内で実装する必要がある。

Note

ページ検索用のリクエストパラメータについて

Spring Dataより提供されているページ検索用のリクエストパラメータは以下の3つとなる。

項番 パラメータ名 説明
page
検索対象のページ位置を指定するためのリクエストパラメータ。
値には、0以上の数値を指定する。
デフォルトの設定では、ページ位置の値は 0 から開始する。そのため、1ページ目のデータを取得する場合は 0 を、2ページ目のデータを取得する場合は 1 を指定する必要がある。
size
取得する件数を指定するためのリクエストパラメータ。
値には、1以上の数値を指定する。
PageableHandlerMethodArgumentResolver の maxPageSize に指定された値より大きい値が指定された場合は、 maxPageSize の値が size の値となる。
sort
ソート条件を指定するためのパラメータ(複数指定可能)。
値には、"{ソート項目名(,ソート順)}" の形式で指定する。
ソート順には、"ASC" 又は "DESC" のどちらかの値を指定し、省略した場合は "ASC" が適用される。
項目名は "," 区切りで複数指定することが可能である。
例えば、クエリ文字列として "sort=lastModifiedDate,id,DESC&sort=subId" を指定した場合、 "ORDER BY lastModifiedDate DESC, id DESC, subId ASC" というOrder By句がQueryに追加される。

Warning

spring-data-commons 1.6.1.RELEASEにおける「size=0」指定時の動作について

terasoluna-gfw-common 1.0.0.RELEASEが依存するspring-data-commons 1.6.1.RELEASEでは、"size=0" を指定すると条件に一致するレコードを全件取得するという不具合がある。 そのため、大量のレコードが取得対象となる可能性がある場合は、java.lang.OutOfMemoryError が発生する可能性が高くなる。

この問題はSpring Data CommonsのJIRA「DATACMNS-377」で対応され、spring-data-commons 1.6.3.RELEASEで解消されている。 改修後の動作としては、"size<=0" を指定した場合は、 sizeパラメータ省略時のデフォルト値が適用される。

terasoluna-gfw-common 1.0.0.RELEASEを使用している場合は、terasoluna-gfw-common 1.0.1.RELEASE以上へバージョンアップする必要がある。

Warning

spring-data-commons 1.6.1.RELEASEにおけるリクエストパラメータに不正な値を指定した際の動作について

terasoluna-gfw-common 1.0.0.RELEASEが依存するspring-data-commons 1.6.1.RELEASEでは、ページ検索用のリクエストパラメータ(page, size, sort)に不正な値を指定した場合、 java.lang.IllegalArgumentException 又は java.lang.ArrayIndexOutOfBoundsException が発生し、SpringMVCのデフォルトの設定だとシステムエラー(HTTPステータスコード=500)となってしまうという不具合がある。

この問題はSpring Data CommonsのJIRA「DATACMNS-379」と「DATACMNS-408」で対応され、spring-data-commons 1.6.3.RELEASEで解消されている。 改修後の動作としては、不正な値を指定した場合は、 パラメータ省略時のデフォルト値が適用される。

terasoluna-gfw-common 1.0.0.RELEASEを使用している場合は、terasoluna-gfw-common 1.0.1.RELEASE以上へバージョンアップする必要がある。

Note

Spring Data CommonsのAPI仕様の変更に伴う注意点

terasoluna-gfw-common 5.0.0.RELEASE以上が依存するspring-data-commons(1.9.1.RELEASE以上)では、 ページ検索機能用のインタフェース(org.springframework.data.domain.Page)とクラス(org.springframework.data.domain.PageImplとorg.springframework.data.domain.Sort.Order)のAPI仕様が変更になっている。

具体的には、

  • PageインタフェースとPageImplクラスでは、isFirst()とisLast()メソッドがspring-data-commons 1.8.0.RELEASEで追加、isFirstPage()とisLastPage()メソッドがspring-data-commons 1.9.0.RELEASEで削除
  • Sort.Orderクラスでは、 nullHandlingプロパティがspring-data-commons 1.8.0.RELEASEで追加

されている。

削除されたAPIを使用している場合はコンパイルエラーとなるので、アプリケーションの修正が必要になる。 加えて、REST APIのリソースオブジェクトとしてPageインタフェース(PageImplクラス)を使用している場合は、 JSONやXMLのフォーマットが変わってしまうため、こちらもアプリケーションの修正が必要になるケースがある。


5.11.1.4. ページネーション機能使用時の処理フロー

Spring Dataより提供されているページネーション機能と、共通ライブラリから提供してるJSPタグライブラリを利用した際の処理フローは、以下の通り。

processing flow of pagination
項番 説明
(1)
検索条件と共に、リクエストパラメータとして検索対象のページ位置(page)と取得件数(size)を指定してリクエストを送信する。
(2)
PageableHandlerMethodArgumentResolver は、リクエストパラメータに指定されている検索対象のページ位置(page)と取得件数(size)を取得し、 Pageable オブジェクトを生成する。
生成された Pageable オブジェクトは、Controllerの処理メソッドの引数に設定される。
(3)
Controllerは、引数で受け取った Pageable オブジェクトを、Serviceのメソッドに引き渡す。
(4)
Serviceは、引数で受け取った Pageable オブジェクトを、 RepositoryのQueryメソッドに引き渡す。
(5)
Repositoryは、検索条件に一致するデータの合計件数(totalElements)と、引数で受け取った Pageable オブジェクトに指定されているページ位置(page)と取得件数(size)の範囲に存在するデータを、データベースより取得する。
(6)
Repositoryは、取得した合計件数(totalElements)、取得データ(content)、引数で受け取った Pageable オブジェクトより Page オブジェクトを作成し、Service及びControllerへ返却する。
(7)
Controllerは、返却された Page オブジェクトを、 Model オブジェクトに格納後、JSPに遷移する。
(8)
JSPは、 Model オブジェクトに格納されている Page オブジェクトを取得し、共通ライブラリから提供されているページネーション用のJSPタグライブラリ( <t:pagination> )を呼び出す。
ページネーション用のJSPタグライブラリは Page オブジェクトを参照し、ページネーションリンクを生成する。
(9)
JSPで生成したHTMLを、クライアント(ブラウザ)に返却する。
(10)
ページネーションリンクを押下すると、該当ページを表示するためリクエストが送信される。

Note

Repositoryの実装について

上記フローの(5)と(6)の処理は、使用するO/R Mapperによって実装方法が異なる。

  • MyBatis3を使用する場合は、Java(Service)及びSQLマッピングファイルの実装が必要がある。
  • Spring Data JPAを使用する場合は、Spring Data JPAの機能で自動的で行われるため実装は不要である。

具体的な実装例については、

を参照されたい。


5.11.2. How to use

ページネーション機能の具体的な使用方法を以下に示す。

5.11.2.1. アプリケーションの設定

5.11.2.1.1. Spring Dataのページネーション機能を有効化するための設定

リクエストパラメータに指定された検索対象のページ位置(page)、取得件数(size)、ソート条件(sort)を、 Pageable オブジェクトとしてControllerの引数に設定するための機能を有効化する。
下記の設定は、ブランクプロジェクトでは設定済みの状態になっている。

spring-mvc.xml

<mvc:annotation-driven>
    <mvc:argument-resolvers>
        <!-- (1) -->
        <bean
            class="org.springframework.data.web.PageableHandlerMethodArgumentResolver" />
    </mvc:argument-resolvers>
</mvc:annotation-driven>
項番 説明
(1)
<mvc:argument-resolvers> に org.springframework.data.web.PageableHandlerMethodArgumentResolver を指定する。
PageableHandlerMethodArgumentResolver で指定できるプロパティについては、「 PageableHandlerMethodArgumentResolver のプロパティ値について 」を参照されたい。

5.11.2.2. ページ検索の実装

ページ検索を実現するための実装方法を以下に示す。

5.11.2.2.1. アプリケーション層の実装

ページ検索に必要な情報(検索対象のページ位置、取得件数、ソート条件)を、Controllerの引数として受け取り、Serviceのメソッドに引き渡す。

  • Controller
@RequestMapping("list")
public String list(@Validated ArticleSearchCriteriaForm form,
        BindingResult result,
        Pageable pageable, // (1)
        Model model) {

    ArticleSearchCriteria criteria = beanMapper.map(form,
            ArticleSearchCriteria.class);

    Page<Article> page = articleService.searchArticle(criteria, pageable); // (2)

    model.addAttribute("page", page); // (3)

    return "article/list";
}
項番 説明
(1)
処理メソッドの引数として Pageable を指定する。
Pageable オブジェクトには、ページ検索に必要な情報(検索対象のページ位置、取得件数、ソート条件)が格納されている。
(2)
Serviceのメソッドの引数に Pageable オブジェクトを指定して呼び出す。
(3)
Serviceから返却された検索結果( Page オブジェクト )を Model に追加する。 Model に追加することで、View(JSP)から参照できるようになる。

Note

リクエストパラメータにページ検索に必要な情報の指定がない場合の動作について

ページ検索に必要な情報(検索対象のページ位置、取得件数、ソート条件)がリクエストパラメータに指定されていない場合は、デフォルト値が適用される。 デフォルト値は、以下の通り。

  • 検索対象のページ位置 : 0 (1ページ目)
  • 取得件数 : 20
  • ソート条件 : null (ソート条件なし)

デフォルト値は、以下の２つの方法で変更することができる。

  • 処理メソッドの Pageable の引数に、 @org.springframework.data.web.PageableDefault アノテーションを指定してデフォルト値を定義する。
  • PageableHandlerMethodArgumentResolver の fallbackPageable プロパティにデフォルト値を定義した Pageable オブジェクトを指定する。

@PageableDefault アノテーションを使用してデフォルト値を指定する方法について説明する。
ページ検索処理毎にデフォルト値を変更する必要がある場合は、@PageableDefault アノテーションを使ってデフォルト値を指定する。
@RequestMapping("list")
public String list(@Validated ArticleSearchCriteriaForm form,
        BindingResult result,
        @PageableDefault( // (1)
                page = 0,    // (2)
                size = 50,   // (3)
                direction = Direction.DESC,  // (4)
                sort = {     // (5)
                    "publishedDate",
                    "articleId"
                    }
                ) Pageable pageable,
        Model model) {
    // ...
    return "article/list";
}
項番 説明 デフォルト値
(1)
Pageable の引数に @PageableDefault アノテーションを指定する。
-
(2)
ページ位置のデフォルト値を変更する場合は、 @PageableDefault のpage属性に値を指定する。
通常変更する必要はない。
0
(1ページ目)
(3)
取得件数のデフォルト値を変更する場合は、 @PageableDefault のsize又はvalue属性に値を指定する。
10
(4)
ソート条件のデフォルト値を変更する場合は、 @PageableDefault のdirection属性に値を指定する。
Direction.ASC
(昇順)
(5)
ソート条件のソート項目を指定する場合は、 @PageableDefault のsort属性にソート項目を指定する。
複数の項目でソートする場合は、ソートするプロパティ名を配列で指定する。
上記例では、 "ORDER BY publishedDate DESC, articleId DESC" というソート条件がQueryに追加される。
空の配列
(ソート項目なし)

Note

@PageableDefaultアノテーションで指定できるソート順について

@PageableDefault アノテーションで指定できるソート順は昇順か降順のどちらか一つなので、項目ごとに異なるソート順を指定したい場合は @org.springframework.data.web.SortDefaults アノテーションを使用する必要がある。 具体的には、 "ORDER BY publishedDate DESC, articleId ASC" というソート順にしたい場合である。

Tip

取得件数のデフォルト値のみ変更する場合の指定方法

取得件数のデフォルト値のみ変更する場合は、 @PageableDefault(50) と指定することもできる。これは @PageableDefault(size = 50) と同じ動作となる。


@SortDefaults アノテーションを使用してデフォルト値を指定する方法について説明する。
@SortDefaults アノテーションは、ソート項目が複数あり、項目ごとに異なるソート順を指定したい場合に使用する。
@RequestMapping("list")
public String list(
        @Validated ArticleSearchCriteriaForm form,
        BindingResult result,
        @PageableDefault(size = 50)
        @SortDefaults(  // (1)
                {
                    @SortDefault(  // (2)
                                 sort = "publishedDate",    // (3)
                                 direction = Direction.DESC // (4)
                                ),
                    @SortDefault(
                                 sort = "articleId"
                                )
                }) Pageable pageable,
        Model model) {
    // ...
    return "article/list";
}
項番 説明 デフォルト値
(1)
Pageable の引数に @SortDefaults アノテーションを指定する。
@SortDefaults アノテーションには、複数の @org.springframework.data.web.SortDefault アノテーションを配列として指定することができる。
-
(2)
@SortDefaults アノテーションの value属性に、 @SortDefault アノテーションを指定する。
複数指定する場合は配列として指定する。
-
(3)
@PageableDefault のsort又はvalue属性にソート項目を指定する。
複数の項目を指定する場合は配列として指定する。
空の配列
(ソート項目なし)
(4)
ソート条件のデフォルト値を変更する場合は、@PageableDefault のdirection属性に値を指定する。
Direction.ASC
(昇順)

上記例では、 "ORDER BY publishedDate DESC, articleId ASC" というソート条件がQueryに追加される。

Tip

ソート項目のデフォルト値のみ指定する場合の指定方法

取得項目のみ指定する場合は、 @PageableDefault("articleId") と指定することもできる。 これは @PageableDefault(sort = "articleId") や @PageableDefault(sort = "articleId", direction = Direction.ASC) と同じ動作となる。


アプリケーション全体のデフォルト値を変更する必要がある場合は、 spring-mvc.xml に定義した PageableHandlerMethodArgumentResolver の fallbackPageable プロパティにデフォルト値を定義した Pageable オブジェクトを指定する。

fallbackPageable の説明や具体的な設定例については、「 PageableHandlerMethodArgumentResolver のプロパティ値について 」を参照されたい。


5.11.2.2.2. ドメイン層の実装(MyBatis3編)

MyBatisを使用してデータベースにアクセスする場合は、Controllerから受け取った Pageable オブジェクトより、必要な情報を抜き出してRepositoryに引き渡す。
該当データを抽出するためのSQLやソート条件については、SQLマッピングで実装する必要がある。

ドメイン層で実装するページ検索処理の詳細については、

を参照されたい。


5.11.2.2.3. ドメイン層の実装(JPA編)

JPA(Spring Data JPA)を使用してデータベースにアクセスする場合は、Controllerから受け取った Pageable オブジェクトをRepositoryに引き渡す。

ドメイン層で実装するページ検索処理の詳細については、

を参照されたい。


5.11.2.3. JSPの実装(基本編)

ページ検索処理で取得した Page オブジェクトを一覧画面に表示し、ページネーションリンク及びページネーション情報(合計件数、合計ページ数、表示ページ数など)を表示する方法を以下に示す。

5.11.2.3.1. 取得データの表示

ページ検索処理で取得したデータを表示するための実装例を以下に示す。

  • Controller
@RequestMapping("list")
public String list(@Validated ArticleSearchCriteriaForm form, BindingResult result,
        Pageable pageable, Model model) {

    if (!StringUtils.hasLength(form.getWord())) {
        return "article/list";
    }

    ArticleSearchCriteria criteria = beanMapper.map(form,
            ArticleSearchCriteria.class);

    Page<Article> page = articleService.searchArticle(criteria, pageable);

    model.addAttribute("page", page); // (1)

    return "article/list";
}
項番 説明
(1)
"page" という属性名で Page オブジェクトを Model に格納する。
JSPでは "page" という属性名を指定して Page オブジェクトにアクセスすることになる。
  • JSP
<%-- ... --%>

<%-- (2) --%>
<c:when test="${page != null && page.totalPages != 0}">

  <table class="maintable">
    <thead>
      <tr>
        <th class="no">No</th>
        <th class="articleClass">Class</th>
        <th class="title">Title</th>
        <th class="overview">Overview</th>
        <th class="date">Published Date</th>
      </tr>
    </thead>

    <%-- (3) --%>
    <c:forEach var="article" items="${page.content}" varStatus="rowStatus">
      <tr>
        <td class="no">
          ${(page.number * page.size) + rowStatus.count}
        </td>
        <td class="articleClass">
          ${f:h(article.articleClass.name)}
        </td>
        <td class="title">
          ${f:h(article.title)}
        </td>
        <td class="overview">
          ${f:h(article.overview)}
        </td>
        <td class="date">
          ${f:h(article.publishedDate)}
        </td>
      </tr>
    </c:forEach>

  </table>

  <div class="paginationPart">

    <%-- ... --%>

  </div>
</c:when>

<%-- ... --%>
項番 説明
(2)
上記例では、条件に一致するデータが存在するかチェックを行い、一致するデータがない場合はヘッダ行も含めて表示していない。
一致するデータがない場合でもヘッダ行は表示させる必要がある場合は、この分岐は不要となる。
(3)
JSTLの <c:forEach> タグを使用して、取得したデータの一覧を表示する。
取得したデータは、 Page オブジェクトの content プロパティにリスト形式で格納されている。
  • 上記JSPで出力される画面例
Screen image of content table

5.11.2.3.3. ページネーション情報の表示

ページネーションに関連する情報(合計件数、合計ページ数、表示ページ数など)を表示するための実装例を以下に示す。

  • 画面例
Screen image of pagination information(total results, current pages, total pages)
  • JSP
<div>
    <fmt:formatNumber value="${page.totalElements}" /> results <%-- (1) --%>
</div>
<div>
    ${f:h(page.number + 1) } /       <%-- (2) --%>
    ${f:h(page.totalPages)} Pages    <%-- (3) --%>
</div>
項番 説明
(1)
検索条件に一致するデータの合計件数を表示する場合は、 Page オブジェクトの totalElements プロパティから値を取得する。
(2)
表示しているページのページ数を表示する場合は、 Page オブジェクトの number プロパティから値を取得し、+1 する。
Page オブジェクトの number プロパティは 0 開始のため、 ページ番号を表示する際は +1 が必要となる。
(3)
検索条件に一致するデータの合計ページ数を表示する場合は、 Page オブジェクトの totalPages プロパティから値をする。

該当ページの表示データ範囲を表示するための実装例を以下に示す。

  • 画面例
Screen image of pagination information(begin position, end position)
  • JSP
<div>
    <%-- (4) --%>
    <fmt:formatNumber value="${(page.number * page.size) + 1}" /> -
    <%-- (5) --%>
    <fmt:formatNumber value="${(page.number * page.size) + page.numberOfElements}" />
</div>
項番 説明
(4)
開始位置を表示する場合は、 Page オブジェクトの number プロパティと size プロパティを使って計算する。
Page オブジェクトの number プロパティは 0 開始のため、データ開始位置を表示する際は +1 が必要となる。
(5)
終了位置を表示する場合は、 Page オブジェクトの number プロパティ、 size プロパティ、 numberOfElements プロパティ を使って計算する。
最終ページは端数となる可能性があるので、 numberOfElements を加算する必要がある。

Tip

数値のフォーマットについて

表示する数値をフォーマットする必要がある場合は、 JSTLから提供されているタグライブラリ( <fmt:formatNumber> )を使用する。


5.11.2.3.4. ページリンクで検索条件を引き継ぐ

検索条件をページ移動時のリクエストに引き継ぐ方法を、以下に示す。

Processing image of take over search criteria
  • JSP
<%-- (1) --%>
<div id="criteriaPart">
  <form:form action="${pageContext.request.contextPath}/article/list" method="get"
             modelAttribute="articleSearchCriteriaForm">
    <form:input path="word" />
    <form:button>Search</form:button>
    <br>
  </form:form>
</div>

<%-- ... --%>

<t:pagination page="${page}"
    outerElementClass="pagination"
    criteriaQuery="${f:query(articleSearchCriteriaForm)}" /> <%-- (2) --%>
項番 説明
(1)
検索条件を指定するフォーム。
検索条件として word が存在する。
(2)
ページ移動時のリクエストに検索条件を引き継ぐ場合は、 criteriaQuery属性にURLエンコーディング済みのクエリ文字列を指定する。
検索条件をフォームオブジェクトに格納する場合は、共通ライブラリから提供しているELファクション( f:query(Object) ) を使用すると、簡単に条件を引き継ぐことができる。
上記例の場合、 "?page=ページ位置&size=取得件数&word=入力値"という形式のクエリ文字列が生成される。

criteriaQuery属性は、terasoluna-gfw-web 1.0.1.RELEASE以上で利用可能な属性である。

Note

f:query(Object) の仕様について

f:query の引数には、 フォームオブジェクトなどのJavaBeanと Map オブジェクトを指定することができる。 JavaBeanの場合はプロパティ名がリクエストパラメータ名となり、 Map オブジェクトの場合はマップのキー名がリクエストパラメータとなる。 生成されるクエリ文字列は、UTF-8のURLエンコーディングが行われる。

f:queryの詳細な仕様(URLエンコーディングの仕様など)については、「f:query()」を参照されたい。

Warning

f:queryを使用して生成したクエリ文字列をqueryTmpl属性に指定した際の動作について

f:queryを使用して生成したクエリ文字列をqueryTmpl属性に指定すると、URLエンコーディングが重複してしまい、特殊文字の引き継ぎが正しく行われないことが判明している。

URLエンコーディングが重複してしまう事象については、terasoluna-gfw-web 1.0.1.RELEASE以上で利用可能なcriteriaQuery属性を使用することで回避する事が出来る。


5.11.2.3.5. ページリンクでソート条件を引き継ぐ

ソート条件をページ移動時のリクエストに引き継ぐ方法を、以下に示す。

  • JSP
<t:pagination page="${page}"
    outerElementClass="pagination"
    queryTmpl="page={page}&size={size}&sort={sortOrderProperty},{sortOrderDirection}" />  <%-- (1) --%>
項番 説明
(1)
ページ移動時のリクエストにソート条件を引き継ぐ場合は、 queryTmpl を指定し、クエリ文字列にソート条件を追加する。
ソート条件を指定するためのパラメータの仕様については、「 ページ検索用のリクエストパラメータについて 」を参照されたい。
上記例の場合、 "?page=0&size=20&sort=ソート項目,ソート順(ASC or DESC)" がクエリ文字列となる。

5.11.2.4. JSPの実装(レイアウト変更編)

5.11.2.4.1. 先頭ページと最終ページに移動するリンクの削除

「最初のページに移動するためのリンク」と「最後のページに移動するためのリンク」を削除するための実装例を、以下に示す。

  • 画面例
Remove page link that move to first & last page
  • JSP
<t:pagination page="${page}"
    outerElementClass="pagination"
    firstLinkText=""
    lastLinkText="" /> <%-- (1) (2) --%>
項番 説明
(1)
「最初のページに移動するためのリンク」を非表示にする場合は、 <t:pagination> タグの firstLinkText属性に "" を指定する。
(2)
「最後のページに移動するためのリンク」を非表示にする場合は、 <t:pagination> タグの lastLinkText属性に "" を指定する。

5.11.2.4.2. 前ページと次ページに移動するリンクの削除

「最初のページに移動するためのリンク」と「最後のページに移動するためのリンク」を削除するための実装例を、以下に示す。

  • 画面例
Remove page link that move to previous & next page
  • JSP
<t:pagination page="${page}"
    outerElementClass="pagination"
    previousLinkText=""
    nextLinkText="" /> <%-- (1) (2) --%>
項番 説明
(1)
「前のページに移動するためのリンク」を非表示にする場合は、 <t:pagination> タグの previousLinkText属性に "" を指定する。
(2)
「次のページに移動するためのリンク」を非表示にする場合は、 <t:pagination> タグの nextLinkText属性に "" を指定する。

5.11.2.4.3. disabled状態のリンクの削除

"disabled" 状態のリンクを削除するための実装例を、以下に示す。
"disabled" 時のスタイルシートに、以下の定義を追加する。
  • 画面例
Remove page link that move to previous & next page
  • スタイルシート
.pagination .disabled {
    display: none;  /* (1) */
}
項番 説明
(1)
"disabled" クラスの属性値として、 "display: none;" を指定する。

5.11.2.4.4. 指定ページへ移動するリンクの最大表示数の変更

指定したページに移動するためのリンクの最大表示数を変更するための実装例を、以下に示す。

  • 画面例
change max display count of page link that move to specified page
  • JSP
<t:pagination page="${page}"
    outerElementClass="pagination"
    maxDisplayCount="5" /> <%-- (1) --%>
項番 説明
(1)
指定したページに移動するためのリンクの最大表示数を変更する場合は、 <t:pagination> タグの maxDisplayCount属性に値を指定する。

5.11.2.4.5. 指定ページへ移動するリンクの削除

指定したページに移動するためのリンクを削除するための実装例を、以下に示す。
  • 画面例
Remove page link that move to specified page
  • JSP
<t:pagination page="${page}"
    outerElementClass="pagination"
    maxDisplayCount="0" /> <%-- (1) --%>
項番 説明
(1)
指定したページに移動するためのリンクを非表示にする場合は、 <t:pagination> タグの maxDisplayCount属性に "0" を指定する。

5.11.2.5. JSPの実装(動作編)

5.11.2.5.1. ソート条件の指定

クライアントからソート条件を指定するための実装例を、以下に示す。

  • 画面例
specify the sort condition
  • JSP
<div id="criteriaPart">
  <form:form
    action="${pageContext.request.contextPath}/article/search"
    method="get" modelAttribute="articleSearchCriteriaForm">
    <form:input path="word" />
    <%-- (1) --%>
    <form:select path="sort">
        <form:option value="publishedDate,DESC">Newest</form:option>
        <form:option value="publishedDate,ASC">Oldest</form:option>
    </form:select>
    <form:button>Search</form:button>
    <br>
  </form:form>
</div>
項番 説明
(1)
クライアントからソート条件を指定する場合は、 ソート条件を指定するためのパラメータを追加する。
ソート条件を指定するためのパラメータの仕様については、「 ページ検索用のリクエストパラメータについて 」を参照されたい。
上記例では、publishedDateの昇順と降順をプルダウンで選択できるようにしている。

5.11.2.5.2. JavaScriptを使用したページリンクの無効化

デフォルトでは、"disabled"状態と"active"状態のページリンク押下時の動作を無効化するために、<t:pagination>タグのdisabledHref属性に"javascript:void(0)"を設定している。 この状態でページリンクにフォーカスを移動又はマウスオーバーすると、 ブラウザのステータスバーに"javascript:void(0)"が表示されることがある。 この挙動を変えたい場合は、JavaScriptを使用してページリンク押下時の動作を無効化する必要がある。

以下に実装例を示す。

JSP

<%-- (1) --%>
<script type="text/javascript"
        src="${pageContext.request.contextPath}/resources/vendor/js/jquery.js"></script>

<%-- (2) --%>
<script type="text/javascript">
    $(function(){
        $(document).on("click", ".disabled a, .active a", function(){
            return false;
        });
    });
</script>

<%-- ... --%>

<%-- (3) --%>
<t:pagination page="${page}" disabledHref="#" />
項番 説明
(1)

jQueryのjsファイルを読み込む。

上記例では、JavaScriptを使用してページリンク押下時の動作を無効化するためにjQueryのAPIを利用する。
(2)

jQueryのAPIを使用して、"disabled"状態と"active"状態のページリンクのクリックイベントを無効化する。

ただし、<t:pagination>タグのenableLinkOfCurrentPage属性に"true"を指定している場合は、"active"状態のページリンクのクリックイベントを無効化してはいけない。
(3)
 disabledHref属性に"#"を指定する。

5.11.3. Appendix

5.11.3.1. PageableHandlerMethodArgumentResolver のプロパティ値について

PageableHandlerMethodArgumentResolver で指定できるプロパティは以下の通り。
アプリケーションの要件に応じて、値を変更すること。
項番 プロパティ名 説明 デフォルト値
maxPageSize
取得件数として許可する最大値を指定する。
指定された取得件数が maxPageSize を超えていた場合は、 maxPageSize が取得件数となる。
2000
fallbackPageable
アプリケーション全体のページ位置、取得件数、ソート条件のデフォルト値を指定する。
ページ位置、取得件数、ソート条件が指定されていない場合は、fallbackPageableに設定されている値が適用される。
ページ位置 : 0
取得件数 : 20
ソート条件 : null
oneIndexedParameters
ページ位置の開始値を指定する。
false を指定した場合はページ位置の開始値は 0 となり、 true を指定した場合はページ位置の開始値は 1 となる。
false
pageParameterName
ページ位置を指定するためのリクエストパラメータ名を指定する。
"page"
sizeParameterName
取得件数を指定するためのリクエストパラメータ名を指定する。
"size"
prefix
ページ位置と取得件数を指定するためのリクエストパラメータの接頭辞(ネームスペース)を指定する。
デフォルトのパラメータ名がアプリケーションで使用するパラメータと衝突する場合は、ネームスペースを指定することでリクエストパラメータ名の衝突を防ぐことが出来る。
prefixを指定すると、ページ位置を指定するためのリクエストパラメータ名は prefix + pageParameterName 、取得件数を指定するためのリクエストパラメータ名は prefix + sizeParameterName となる。
""
(ネームスペースなし)
qualifierDelimiter
同一リクエストで複数のページ検索が必要になる場合、ページ検索に必要な情報(検索対象のページ位置、取得件数など)を区別するために、リクエストパラメータ名は qualifier + delimiter + 標準パラメータ名 の形式で指定する。
本プロパティは、上記形式の中の delimiter の値を設定する。
この設定を変更する場合は、 SortHandlerMethodArgumentResolver の qualifierDelimiter 設定も合わせて変更する必要がある。
"_"

Note

maxPageSizeの設定値について

デフォルト値は 2000 であるが、アプリケーションが許容する最大値に設定を変更することを推奨する。 アプリケーションが許可する最大値が 100 ならば、maxPageSizeも 100 に設定する。

Note

fallbackPageableの設定方法について

アプリケーション全体に適用するデフォルト値を変更する場合は、 fallbackPageable プロパティにデフォルト値が定義されている Pageable ( org.springframework.data.domain.PageRequest ) オブジェクトを設定する。 ソート条件のデフォルト値を変更する場合は、 SortHandlerMethodArgumentResolver の fallbackSort プロパティにデフォルト値が定義されている org.springframework.data.domain.Sort オブジェクトを設定する。


開発するアプリケーション毎に変更が想定される以下の項目について、デフォルト値を変更する際の設定例を以下に示す。

  • 取得件数として許可する最大値( maxPageSize )
  • アプリケーション全体のページ位置、取得件数のデフォルト値( fallbackPageable )
  • ソート条件のデフォルト値( fallbackSort )
<mvc:annotation-driven>
    <mvc:argument-resolvers>
        <bean
            class="org.springframework.data.web.PageableHandlerMethodArgumentResolver">
            <!-- (1) -->
            <property name="maxPageSize" value="100" />
            <!-- (2) -->
            <property name="fallbackPageable">
                <bean class="org.springframework.data.domain.PageRequest">
                    <!-- (3) -->
                    <constructor-arg index="0" value="0" />
                    <!-- (4) -->
                    <constructor-arg index="1" value="50" />
                </bean>
            </property>
            <!-- (5) -->
            <constructor-arg index="0">
                <bean class="org.springframework.data.web.SortHandlerMethodArgumentResolver">
                    <!-- (6) -->
                    <property name="fallbackSort">
                        <bean class="org.springframework.data.domain.Sort">
                            <!-- (7) -->
                            <constructor-arg index="0">
                                <list>
                                    <!-- (8) -->
                                    <bean class="org.springframework.data.domain.Sort.Order">
                                        <!-- (9) -->
                                        <constructor-arg index="0" value="DESC" />
                                        <!-- (10) -->
                                        <constructor-arg index="1" value="lastModifiedDate" />
                                    </bean>
                                    <!-- (8) -->
                                    <bean class="org.springframework.data.domain.Sort.Order">
                                        <constructor-arg index="0" value="ASC" />
                                        <constructor-arg index="1" value="id" />
                                    </bean>
                                </list>
                            </constructor-arg>
                        </bean>
                    </property>
                </bean>
            </constructor-arg>
        </bean>
    </mvc:argument-resolvers>
</mvc:annotation-driven>
項番 説明
(1)
上記例では取得件数の最大値を 100 に設定している。 取得件数(size)に 101 以上が指定された場合は、 100 に切り捨てて検索が行われる。
(2)
org.springframework.data.domain.PageRequest のインスタンスを生成し、 fallbackPageable に設定する。
(3)
PageRequest のコンストラクタの第1引数に、ページ位置のデフォルト値を指定する。
上記例では 0 を指定しているため、デフォルト値は変更していない。
(4)
PageRequest のコンストラクタの第2引数に、取得件数のデフォルト値を指定する。
上記例ではリクエストパラメータに取得件数の指定がない場合の取得件数は 50 となる。
(5)
PageableHandlerMethodArgumentResolver のコンストラクタとして、 SortHandlerMethodArgumentResolver のインスタンスを設定する。
(6)
Sort のインスタンスを生成し、 fallbackSort に設定する。
(7)
Sort のコンストラクタの第1引数に、 デフォルト値として使用する Order オブジェクトのリストを設定する。
(8)
Order のインスタンスを生成し、 デフォルト値として使用する Order オブジェクトのリストに追加する。
上記例ではリクエストパラメータにソート条件の指定がない場合は "ORDER BY x.lastModifiedDate DESC, x.id ASC" というソート条件がQueryに追加される。
(9)
Order のコンストラクタの第1引数に、ソート順(ASC/DESC)を指定する。
(10)
Order のコンストラクタの第2引数に、ソート項目を指定する。

5.11.3.2. SortHandlerMethodArgumentResolver のプロパティ値について

SortHandlerMethodArgumentResolver で指定できるプロパティは以下の通り。
アプリケーションの要件に応じて、値を変更すること。
項番 プロパティ名 説明 デフォルト値
fallbackSort
アプリケーション全体のソート条件のデフォルト値を指定する。
ソート条件が指定されていない場合は、fallbackSortに設定されている値が適用される。
null
(ソート条件なし)
sortParameter
ソート条件を指定するためのリクエストパラメータ名を指定する。
デフォルトのパラメータ名がアプリケーションで使用するパラメータと衝突する場合は、リクエストパラメータ名を変更することで衝突を防ぐことができる。
"sort"
propertyDelimiter
ソート項目及びソート順(ASC,DESC)の区切り文字を指定する。
","
qualifierDelimiter
同一リクエストで複数のページ検索が必要になる場合、ページ検索に必要な情報(ソート条件)を区別するために、リクエストパラメータ名は qualifier + delimiter + sortParameter の形式で指定する。
本プロパティは、上記形式の中の delimiter の値を設定する。
"_"