4.5. ページネーション

4.5.1. Overview

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

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

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

ページネーション機能を利用してページ分割した場合、以下のような画面になる。
各要素の表示にはサーバ側で行う検索処理をページ検索に対応させる必要がある。ページ検索機能については、「ページ検索について 」を参照されたい。
また、各要素の概要及びHTML構造等については、「ページネーションの表示について」を参照されたい。
Screen image of Pagination.
項番 説明
(1)
ページ検索処理で取得したデータを表示する。
(2)
ページを移動するためのリンクを表示する。
リンク押下時には、該当ページを表示するためのリクエストを送信する。
(3)
ページネーションに関連する情報(合計件数、合計ページ数、表示ページ数など)を表示する。

4.5.1.2. ページ検索について

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

4.5.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 が提供されている。
ページネーションリンクを出力する際には、 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に追加することになる。

4.5.1.3. ページネーションの表示について

「ページ分割時の一覧画面の表示について」にて説明した画面の各要素について説明する。

4.5.1.3.1. 取得データの表示について

ページ検索処理で検索条件(検索対象のページ位置、取得件数、ソート条件等)を指定して取得したデータを表示する。
ページ検索については、「ページ検索について 」を参照されたい。

4.5.1.3.2. ページネーションリンクの表示について

この章で実装例として取り上げるページネーションリンクについて以下の流れで説明する。
  1. ページネーションリンクの構成
  2. ページネーションリンクのHTML構造
なおこの章では、TERASOLUNA共通ライブラリで提供されるJSPタグである <t:pagination> のデフォルト設定で出力されるHTMLを例に、ページネーションリンクの実装例を説明する。
実装例のページネーションリンクの構成・レイアウト等は、あくまでも一例である。実装例を参考にアプリケーションの要件によって適宜変更すること。

以降の説明で使用する画面は、Bootstrap v3.0.0のスタイルシートを適用している。

4.5.1.3.2.1. ページネーションリンクの構成

ページネーションリンクは、以下の要素から構成される。

Structure of the pagination link.
項番 説明
(1)
最初のページに移動するためのリンク。
(2)
前のページに移動するためのリンク。
(3)
指定したページに移動するためのリンク。
(4)
次のページに移動するためのリンク。
(5)
最後のページに移動するためのリンク。

ページネーションリンクは、以下の状態をもつ。

Status of the pagination link.
項番 説明
(6)
現在表示しているページで操作することができないリンクであることを示す状態。
具体的には、1ページ目を表示している時の「最初のページに移動するためのリンク」「前のページに移動するためのリンク」と、最終ページを表示している時の「次のページに移動するためのリンク」「最後のページに移動するためのリンク」がこの状態となる。
この状態を disabled と定義する。
(7)
現在表示しているページであることを示す状態。
この状態を active と定義する。

上記を実現するHTMLは、以下の構造となる。
図中の番号は、上記で説明した「ページネーションリンクの構成」と「ページネーションリンクの状態」の項番に対応させている。
html of the pagination link.

4.5.1.3.2.2. ページネーションリンクのHTML構造
ページネーションリンクのHTML構造について説明する。
スタイルクラスの指定は省略している。スタイルクラスは、作成するアプリケーションの要件に応じて適宜指定すること。
  • HTML
html structure of the pagination link.
  • 画面イメージ
screen structure of the pagination link.
項番 説明
(1)
ページネーションリンクの構成要素をまとめるための要素。
(2)
ページネーションリンクを構成するための要素。
(3)
ページ移動するためのリクエストを送信するための要素。
(4)
ページ移動するためのURLを指定するための属性。
(5)
ページ移動するためのリンクの表示テキストを指定する。

4.5.1.3.3. ページネーション情報の表示について

ページネーションに関する情報の表示を行う。
Spring Data提供のページ検索機能を使用することで、以下の情報を画面に表示することができる。
  • 合計件数
  • 検索対象のページ位置
  • 取得件数
  • ソート条件
ページ検索については、「ページ検索について 」を参照されたい。

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

Spring Dataより提供されているページネーション機能を利用した際の処理フローは、以下の通り。

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 オブジェクトに格納後、ThymeleafのテンプレートHTMLに遷移する。
テンプレートHTMLは、 Model オブジェクトに格納されている Page オブジェクトを取得し、ページネーションリンクを生成する。
(8)
生成したHTMLを、クライアント(ブラウザ)に返却する。
(9)
ページネーションリンクを押下すると、該当ページを表示するためリクエストが送信される。

Note

Repositoryの実装について

上記フローの(5)と(6)の具体的な実装例については、

を参照されたい。


4.5.2. How to use

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

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

4.5.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 のプロパティ値について 」を参照されたい。

4.5.2.2. ページ検索の実装

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

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

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

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

    ArticleSearchCriteria criteria = beanMapper.map(form); // (2)

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

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

    return "article/list";
}
項番 説明
(1)
ハンドラメソッドの引数として Pageable を指定する。
Pageable オブジェクトには、ページ検索に必要な情報(検索対象のページ位置、取得件数、ソート条件)が格納されている。
(2)
BeanのマッピングにはMapStructを用いて作成したマッパーインタフェースを使用する。
Mapperインタフェースの定義方法についてはBeanマッピング(MapStruct)を参照されたい。
(3)
Serviceのメソッドの引数に Pageable オブジェクトを指定して呼び出す。
(4)
Serviceから返却された検索結果( Page オブジェクト )を Model に追加する。 Model に追加することで、View(テンプレートHTML)から参照できるようになる。

Note

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

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

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

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

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

@PageableDefault アノテーションを使用してデフォルト値を指定する方法について説明する。
ページ検索処理毎にデフォルト値を変更する必要がある場合は、@PageableDefault アノテーションを使ってデフォルト値を指定する。
@GetMapping("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 のようなOrder By句を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 のようなOrder By句をQueryに追加することになる。

Tip

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

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


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

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


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

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

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

を参照されたい。


4.5.2.3. テンプレートHTMLの実装

ページ検索処理で取得した Page オブジェクトからデータを取得し、ページネーションを行う画面に取得したデータ、ページネーションリンク、ページネーションに関する情報(合計件数、合計ページ数、表示ページ数など)を表示する方法について説明する。

ページネーションリンクやページネーション情報の表示は、アプリケーション内で共通的に使用されるため部品化することを推奨する。
また、ページネーションリンクの出力範囲や該当ページの表示データ範囲の計算等の複雑な計算ロジックはテンプレートHTMLではなくJavaで実装することを推奨する。

そのため、ここでは以下の構成でテンプレートHTMLの実装を行う例を示す。

成果物の構成要素 説明
テンプレートHTML（ページネーションを行う画面）
取得したデータの一覧の表示を実装する
テンプレートHTML（フラグメント）
すべてのテンプレートHTML（ページネーションを行う画面）で同様の、ページネーションリンクやページネーション情報の表示の実装を共通化する
式オブジェクト
ページネーションリンクの出力範囲や該当ページの表示データ範囲の計算ロジックを実装する
なお、「アプリケーション層の実装」の例では、 Page オブジェクトを page という名前で Model に格納している。
そのため、テンプレートHTMLの実装では page という名前を指定して Page オブジェクトにアクセスすることができる。

4.5.2.3.1. 取得データの表示

ページ検索処理で取得したデータを表示するための実装例を以下に示す。 データの表示内容は画面ごとに異なるため、共通化せずテンプレートHTML（ページネーションを行う画面）に実装すると良い。

  • テンプレートHTML（ページネーションを行う画面）
<!--/* ... */-->

<!--/* (1) */-->
<div th:if="${page} != null" th:remove="tag">

  <table class="maintable">

    <thead>
      <tr>
        <th>No</th>
        <th>Class</th>
        <th>Title</th>
        <th>Overview</th>
        <th>Published Date</th>
      </tr>
    </thead>

    <!--/* (2) */-->
    <tbody>
      <tr th:each="article, status : ${page.content}" th:object="${article}">
        <td class="no" th:text="*{articleId}"></td>
        <td class="articleClass" th:text="*{articleClass.name}"></td>
        <td class="title" th:text="*{title}"></td>
        <td class="overview" th:text="*{overview}"></td>
        <td class="date"
          th:text="*{#dates.format(publishDate, 'yyyy/MM/dd HH:mm:ss')}"></td>
      </tr>
    </tbody>

  </table>

</div>

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

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

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

ここでは、どの画面でも共通のページネーション情報を表示するため、テンプレートHTML（フラグメント）に実装する。また、ページネーション情報に出力する「該当ページの表示データ範囲」については、計算ロジックを伴うため式オブジェクトに実装する。

  • 画面例
Screen image of pagination information(total results, current pages, total pages)
  • テンプレートHTML（フラグメント）
<!--/* ... */-->

<div th:fragment="paginationInfo (page)" th:object="${page}" th:remove="tag">

  <!--/* (1) */-->
  <div class="text-center"
    th:text="|*{totalElements} results|"></div>

  <!--/* (2), (3) */-->
  <div th:if="*{totalElements} != 0" class="text-center"
    th:text="|*{number + 1} / *{totalPages} Pages|"></div>

</div>

<!--/* ... */-->
項番 説明
(1)
検索条件に一致するデータの合計件数を表示する場合は、 Page オブジェクトの totalElements プロパティから値を取得する。
(2)
表示しているページのページ数を表示する場合は、 Page オブジェクトの number プロパティから値を取得し、+1 する。
Page オブジェクトの number プロパティは 0 開始のため、 ページ番号を表示する際は +1 が必要となる。
(3)
検索条件に一致するデータの合計ページ数を表示する場合は、 Page オブジェクトの totalPages プロパティから値を取得する。

該当ページの表示データ範囲を表示するための実装例を以下に示す。
該当ページの表示データ範囲の表示では最大で3つの変数を用いた複雑な計算ロジックを実装することになるため式オブジェクトを用いた実装例を示す。

ここでは、式オブジェクトへ追加するメソッドの実装例のみを示す。式オブジェクトの登録や作成したカスタムダイアレクトの設定等については、「リンクの出力範囲を計算する式オブジェクトを実装する」を参照されたい。
  • 画面例
Screen image of pagination information(begin position, end position)

「リンクの出力範囲を計算する式オブジェクトを実装する」で作成した式オブジェクトに新たにメソッドを実装する。実装例を以下に示す。

  • 式オブジェクト
public class PageInfo {

    // omitted

    // (1)
    public int firstItemNumInPage(Page<T> page) {
        return page.getNumber() * page.getSize() + 1;
    }

    // (2)
    public int lastItemNumInPage(Page<T> page) {
        return page.getNumber() * page.getSize() + page.getNumberOfElements();
    }

}
項番 説明
(1)
Page オブジェクトを引数に取り、 該当ページの表示データの開始位置を返すメソッドを定義する。
Page オブジェクトの number プロパティは 0 開始のため、データ開始位置を表示する際は +1 が必要となる。
(2)
Page オブジェクトを引数に取り、 該当ページの表示データの終了位置を返すメソッドを定義する。
最終ページは端数となる可能性があるので、 numberOfElements を加算する必要がある。
  • テンプレートHTML（フラグメント）
<!--/* ... */-->

<div th:fragment="paginationInfo (page)" th:object="${page}" th:remove="tag">

  <!--/* (4), (5) */-->
  <div class="text-center"
    th:text="|${#pageInfo.firstItemNumInPage(page)} - ${#pageInfo.lastItemNumInPage(page)}|">
  </div>

</div>

<!--/* ... */-->
項番 説明
(4)
開始位置を式オブジェクトを使用して取得する。
(5)
終了位置を式オブジェクトを使用して取得する。

Tip

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

表示する数値をフォーマットする必要がある場合は、Thymeleafから提供されているユーティリティメソッド #numbers.formatInteger() を使用する。

上記で定義したフラグメントを使用してページネーション情報を表示するテンプレートHTML（ページネーションを行う画面）の実装例は以下の通りとなる。

  • テンプレートHTML（ページネーションを行う画面）
<!--/* ... */-->

<div th:replace="~{pgnt/fragment :: paginationInfo (${page})}"></div>

<!--/* ... */-->

4.5.3. Appendix

4.5.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" factory-method="of">
                    <!-- (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" factory-method="by">
                            <!-- (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 に設定する。
spring-data-commons 2.2.0より PageRequest クラスからpublicなコンストラクタが削除されたため、factory-methodを利用してstaticな PageRequest#of メソッドによりBeanを生成する必要がある。
(3)
PageRequest#of メソッドの第1引数に、ページ位置のデフォルト値を指定する。
上記例では 0 を指定しているため、デフォルト値は変更していない。
(4)
PageRequest#of メソッドの第2引数に、取得件数のデフォルト値を指定する。
上記例ではリクエストパラメータに取得件数の指定がない場合の取得件数は 50 となる。
(5)
PageableHandlerMethodArgumentResolver のコンストラクタとして、 SortHandlerMethodArgumentResolver のインスタンスを設定する。
(6)
Sort のインスタンスを生成し、 fallbackSort に設定する。
spring-data-commons 2.2.0より Sort クラスからpublicなコンストラクタが削除されたため、factory-methodを利用してstaticな Sort#by メソッドによりBeanを生成する必要がある。
(7)
Sort#by メソッドの第1引数に、 デフォルト値として使用する Order オブジェクトのリストを設定する。
(8)
Order のインスタンスを生成し、 デフォルト値として使用する Order オブジェクトのリストに追加する。
上記例ではリクエストパラメータにソート条件の指定がない場合は ORDER BY lastModifiedDate DESC, id ASC のようなOrder By句をQueryに追加することになる。
(9)
Order のコンストラクタの第1引数に、ソート順(ASC/DESC)を指定する。
(10)
Order のコンストラクタの第2引数に、ソート項目を指定する。

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

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