入力チェック
********************************************************************************

.. only:: html

.. contents:: 目次
  :depth: 4
  :local:

|

Overview
================================================================================

| ユーザーが入力した値が不正かどうかを検証することは必須である。
| 入力値の検証は大きく分けて、

#. 長さや形式など、文脈によらず入力値だけを見て、それが妥当かどうかを判定できる検証
#. システムの状態によって入力値が妥当かどうかが変わる検証

がある。

1.の例としては必須チェックや、桁数チェックがあり、2.の例としては登録済みのE-mailかどうかのチェックや、注文数が在庫数以内であるかどうかのチェックが挙げられる。

本節では、基本的には前者のことを説明し、このチェックのことを「入力チェック」を呼ぶ。後者のチェックは「業務ロジックチェック」と呼ぶ。業務ロジックチェックについては\ :doc:`../../ImplementationAtEachLayer/DomainLayer`\ を参照されたい。

本ガイドラインでは、基本的に入力チェックをアプリケーション層で行い、業務ロジックチェックは、ドメイン層で行うことをポリシーとする。

Webアプリケーションの入力チェックには、サーバサイドで行うチェックと、クライアントサイド(JavaScript)で行うチェックがある。サーバーサイドのチェックは必須であるが、クライアントサイドでも同じチェックを実施すると、サーバー通信なしでチェック結果が分かるため、ユーザビリティが向上する。

.. warning::

  JavaScriptによるクライアントサイドの処理は改ざん可能であるため、サーバーサイドのチェックは必ず行うこと。

  クライアントサイドのみでチェックを行い、サーバーサイドでチェックを省略した場合は、システムが危険な状態に晒されていることになる。

|

入力チェックの分類
--------------------------------------------------------------------------------

入力チェックは、単項目チェック、相関項目チェックに分類される。

.. tabularcolumns:: |p{0.15\linewidth}|p{0.30\linewidth}|p{0.25\linewidth}|p{0.30\linewidth}|
.. list-table::
  :header-rows: 1
  :widths: 15 30 25 30

  * - 種類
    - 説明
    - 例
    - 実現方法
  * - 単項目チェック
    - | 単一のフィールドで完結するチェック
    - | 入力必須チェック
      | 桁チェック
      | 型チェック
    - | Bean Validation (実装ライブラリとしてHibernate Validatorを使用)
  * - 相関項目チェック
    - | 複数のフィールドを比較するチェック
    - | パスワードと確認用パスワードの一致チェック
    - | \ :url_spring_reference:`org.springframework.validation.Validator </core/validation/validator.html>`\ インタフェースを実装したValidationクラス
      | または Bean Validation

| Spring は、Java標準であるBean Validationをサポートしている。単項目チェックには、このBean Validationを利用する。
| 相関項目チェックの場合は、Bean ValidationまたはSpringが提供している\ ``org.springframework.validation.Validator``\ インタフェースを利用する。

|

.. _ValidationHowToUse:

How to use
================================================================================

.. _ValidationAddDependencyLibrary:

依存ライブラリの追加
--------------------------------------------------------------------------------

Bean Validation 3.0(Hibernate Validator 8.x)以上を使用する場合、Bean ValidationのAPI仕様クラス(\ ``jakarta.validation``\ パッケージのクラス)が格納されているjarファイルとHibernate Validatorのjarファイルに加えて、

* Expression Language 5.0以上のAPI仕様クラス (\ ``jakarta.el``\ パッケージのクラス)
* Expression Language 5.0以上のリファレンス実装クラス

が格納されているライブラリが必要となる。

アプリケーションサーバにデプロイして動かす場合は、これらのライブラリはアプリケーションサーバから提供されているため、依存ライブラリの追加は不要である。ただし、スタンドアロン環境(JUnitなど)で動かす場合は、これらのライブラリを依存ライブラリとして追加する必要がある。

スタンドアロン環境でBean Validation 3.0以上を動かす際に必要となるライブラリの追加例を以下に示す。

.. code-block:: xml

  <!-- (1) -->
  <dependency>
      <groupId>org.apache.tomcat.embed</groupId>
      <artifactId>tomcat-embed-el</artifactId>
      <scope>test</scope> <!-- (2) -->
  </dependency>

.. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
.. list-table::
  :header-rows: 1
  :widths: 10 90

  * - 項番
    - 説明
  * - | (1)
    - | スタンドアロン環境で動かすプロジェクトの\ :file:`pom.xml`\ ファイルに、Expression Language用のクラスが格納されているライブラリを追加する。
      |
      | 上記例では、組込み用のApache Tomcat向けに提供されているライブラリを指定している。
      | \ ``tomcat-embed-el``\ のjarファイルには、Expression LanguageのAPI仕様クラスとリファレンス実装クラスの両方が格納されている。
  * - | (2)
    - | JUnitを実行するために依存ライブラリが必要になる場合は、スコープは \ ``test``\ が適切である。

|

.. _ValidationSingleCheck:

単項目チェック
--------------------------------------------------------------------------------

単項目チェックを実装するには、

* フォームクラスのフィールドに、Bean Validation用のアノテーションを付与する
* Controllerに、検証するための\ ``@Validated``\ アノテーションを付与する
* JSPまたはThymeleafのテンプレートHTMLに、検証エラーメッセージを表示するためのタグを追加する

が必要である。

.. note::

  spring-mvc.xmlに\ ``<mvc:annotation-driven>``\ の設定が行われていれば、Bean Validationは有効になる。

|

.. _ValidationInputRequiredCheck:

入力必須チェックについて
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

| 入力必須チェックは基本的に、対象のフィールドに\ ``@NotNull``\ を付け、値が\ ``null``\ ではないことを確認することでチェックを行う。しかし、文字列の入力フィールドに未入力の状態でフォームを送信した場合、Spring MVCのデフォルト挙動ではフォームオブジェクトに\ **nullではなく、空文字がバインドされる**\ 。そのため、文字列の入力フィールドに対して入力必須チェックを行う場合は、\ ``@NotNull``\ ではなく、\ ``@NotEmpty``\ を使用して\ ``null``\ および空文字を許可しないことを推奨する。
| 入力フィールドが未入力の場合に、空文字ではなく\ ``null``\ にバインドする方法に関しては、\ :ref:`ValidationStringTrimmerEditor`\ を参照されたい。

文字列のフィールドに対して入力必須チェックだけではなく、\ ``@Size(min = 1, max = 20)``\ のように最小の文字数をチェックする場合は\ ``@NotNull``\ を使用した場合と\ ``@NotEmpty``\ を使用した場合では挙動が異なる点に注意されたい。

* \ ``@NotNull``\ を使用した場合は、未入力の場合\ ``@Size``\ のエラーメッセージのみが表示される。
* \ ``@NotEmpty``\ を使用した場合は、未入力の場合\ ``@NotEmpty``\ のエラーメッセージと\ ``@Size``\ のエラーメッセージが表示される。

\ ``@Size``\ のminを1以上に設定する場合は空文字を許容しないため、\ ``@NotEmpty``\ によるチェックは冗長となる。そのため、本ガイドラインで文字列フィールドに対して入力必須チェックと文字列長の最小値チェックを行う場合は、\ ``@NotNull``\ を使用する。

以上の説明より、本ガイドラインでは次の表の内容に従い入力必須チェックを行う。

.. tabularcolumns:: |p{0.20\linewidth}|p{0.40\linewidth}|p{0.30\linewidth}|p{0.50\linewidth}|
.. list-table::
  :header-rows: 1
  :widths: 20 30 30 50

  * - 対象フィールド
    - チェック内容
    - 使用するアノテーション
    - 説明
  * - | 文字列以外
    - | 入力必須チェック
    - | \ ``@NotNull``\ 
    - | \ ``null``\ を許可しない
  * - | 文字列
    - | 入力必須チェック
    - | \ ``@NotEmpty``\ 
    - | \ ``null``\ と空文字を許可しない
  * - | 
    - | 入力必須チェック + 文字列長チェック
    - | \ ``@NotNull``\ + \ ``@Size(min = 1, max = 20)``\
    - | 未入力の場合は\ ``@Size``\ のエラーメッセージのみが表示される。

.. _ValidationBasicValidation:

基本的な単項目チェック
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

「新規ユーザー登録」処理を例に用いて、実装方法を説明する。ここでは「新規ユーザー登録」のフォームに、以下のチェックルールを設ける。


.. tabularcolumns:: |p{0.20\linewidth}|p{0.30\linewidth}|p{0.50\linewidth}|
.. list-table::
  :header-rows: 1
  :widths: 20 30 50

  * - フィールド名
    - 型
    - ルール
  * - | name
    - | \ ``java.lang.String``\
    - | 入力必須
      | 1文字以上
      | 20文字以下
  * - | email
    - | \ ``java.lang.String``\
    - | 入力必須
      | 1文字以上
      | 50文字以下
      | E-mail形式
  * - | age
    - | \ ``java.lang.Integer``\
    - | 入力必須
      | 1以上
      | 200以下

* フォームクラス

  フォームクラスの各フィールドに、Bean Validationのアノテーションを付ける。使用するアノテーションの詳細は\ :ref:`ValidationJsr380Doc`\ を参照されたい。

  .. code-block:: java

    package com.example.sample.app.validation;

    import java.io.Serializable;

    import jakarta.validation.constraints.Email;
    import jakarta.validation.constraints.Max;
    import jakarta.validation.constraints.Min;
    import jakarta.validation.constraints.NotNull;
    import jakarta.validation.constraints.Size;

    public class UserForm implements Serializable {

        private static final long serialVersionUID = 1L;

        @NotNull // (1)
        @Size(min = 1, max = 20) // (2)
        private String name;

        @NotNull
        @Size(min = 1, max = 50)
        @Email // (3)
        private String email;

        @NotNull // (4)
        @Min(0) // (5)
        @Max(200) // (6)
        private Integer age;

        // omitted setter/getter
    }

  .. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
  .. list-table::
    :header-rows: 1
    :widths: 10 90

    * - 項番
      - 説明
    * - | (1)
      - | 対象のフィールドが\ ``null``\ でないことを示す\ ``jakarta.validation.constraints.NotNull``\ を付ける。
        |
        | Spring MVCでは、文字列の入力フィールドに未入力の状態でフォームを送信した場合、
        | デフォルトではフォームオブジェクトに\ **nullではなく、空文字がバインドされる**\ 。
        | この\ ``@NotNull``\ は、そもそもリクエストパラメータとして\ ``name``\ が存在することをチェックする。
    * - | (2)
      - | 対象のフィールドの文字列長(またはコレクションのサイズ)が指定したサイズの範囲内にあることを示す\ ``jakarta.validation.constraints.Size``\ を付ける。
        |
        | 上記の通り、Spring MVCではデフォルトで、未入力の文字列フィールドには、空文字がバインドされるため、
        | 1文字以上というルールが入力必須を表す。
    * - | (3)
      - | 対象のフィールドがE-mail形式であることを示す\ ``jakarta.validation.constraints.Email``\ を付ける。
        | 
        | E-mail形式の要件が\ ``@Email`` \ のチェックと合致しない場合は、\ ``jakarta.validation.constraints.Pattern``\ を用いて、正規表現を指定する必要がある。
        | \ ``@Email`` \ については、\ :ref:`ValidationJsr380Doc`\ を参照されたい。
    * - | (4)
      - | 数値の入力フィールドに未入力の状態でフォームを送信した場合、フォームオブジェクトに\ ``null`` \ がバインドされるため、\ ``@NotNull``\ が\ ``age``\ の入力必須条件を表す。
    * - | (5)
      - | 対象のフィールドが指定した数値の以上であることを示す\ ``jakarta.validation.constraints.Min``\ を付ける。
    * - | (6)
      - | 対象のフィールドが指定した数値の以下であることを示す\ ``jakarta.validation.constraints.Max``\ を付ける。

  .. tip::

    Bean Validation標準のアノテーション、Hibernate Validationが用意しているアノテーションについては、\ :ref:`ValidationJsr380Doc`\ 、\ :ref:`ValidationValidatorList`\ を参照されたい。

* Controllerクラス

  入力チェック対象のフォームクラスに、\ ``@Validated``\ を付ける。

  .. code-block:: java

    package com.example.sample.app.validation;

    import org.springframework.stereotype.Controller;
    import org.springframework.validation.BindingResult;
    import org.springframework.validation.annotation.Validated;
    import org.springframework.web.bind.annotation.GetMapping;
    import org.springframework.web.bind.annotation.ModelAttribute;
    import org.springframework.web.bind.annotation.PostMapping;
    import org.springframework.web.bind.annotation.RequestMapping;

    @Controller
    @RequestMapping("user")
    public class UserController {

        @ModelAttribute
        public UserForm setupForm() {
          return new UserForm();
        }

        @GetMapping(value = "create", params = "form")
        public String createForm() {
            return "user/createForm"; // (1)
        }

        @PostMapping(value = "create", params = "confirm")
        public String createConfirm(@Validated /* (2) */ UserForm form, BindingResult /* (3) */ result) {
          if (result.hasErrors()) { // (4)
              return "user/createForm";
          }
          return "user/createConfirm";
        }

        @PostMapping(value = "create")
        public String create(@Validated UserForm form, BindingResult result) { // (5)
          if (result.hasErrors()) {
              return "user/createForm";
          }
          // omitted business logic
          return "redirect:/user/create?complete";
        }

        @GetMapping(value = "create", params = "complete")
        public String createComplete() {
            return "user/createComplete";
        }
    }

  .. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
  .. list-table::
    :header-rows: 1
    :widths: 10 90

    * - 項番
      - 説明
    * - | (1)
      - | 「新規ユーザー登録」フォーム画面を表示する。
    * - | (2)
      - | フォームにつけたアノテーションで入力チェックをするために、フォームの引数に \ ``org.springframework.validation.annotation.Validated``\ を付ける。
    * - | (3)
      - | (2)のチェック結果を格納する\ ``org.springframework.validation.BindingResult``\ を、引数に加える。
        | この\ ``BindingResult``\ は、フォームの直後に記述する必要がある。
        |
        | 直後に指定されていない場合は、検証後に結果をバインドできず、\ ``org.springframework.validation.BindException``\ がスローされる。
    * - | (4)
      - | (2)のチェック結果は、\ ``BindingResult.hasErrors()``\ メソッドで判定できる。
        | \ ``hasErrors()``\ の結果が\ ``true``\ の場合は、入力値に問題があるため、フォーム表示画面に戻す。
    * - | (5)
      - | 入力内容確認画面から新規作成処理にリクエストを送る際にも、\ **入力チェックを必ず再実行すること**\ 。
        | 途中でデータを改ざんすることは可能であるため、必ず業務処理の直前で入力チェックは必要である。

  \ ``@Validated``\ は、Bean Validation標準ではなくSpringの独自アノテーションである。
  
  Bean Validation標準の\ ``jakarta.validation.Valid``\ アノテーションも使用できるが、\ ``@Validated``\ は\ ``@Valid``\ に比べてバリデーションのグループを指定できる点で優れているため、本ガイドラインではControllerの引数には\ ``@Validated``\ を使用することを推奨する。

.. _ValidationJspImplSample:

* View

.. tabs::
  .. group-tab:: JSP

    * JSP
    
      \ ``<form:errors>``\ タグで、入力エラーがある場合にエラーメッセージを表示できる。
    
      .. code-block:: jsp
    
        <!DOCTYPE html>
        <html>
        <%-- WEB-INF/views/user/createForm.jsp --%>
        <body>
            <form:form modelAttribute="userForm" method="post"
                action="${pageContext.request.contextPath}/user/create">
                <form:label path="name">Name:</form:label>
                <form:input path="name" />
                <form:errors path="name" /><%--(1) --%>
                <br>
                <form:label path="email">Email:</form:label>
                <form:input path="email" />
                <form:errors path="email" />
                <br>
                <form:label path="age">Age:</form:label>
                <form:input path="age" />
                <form:errors path="age" />
                <br>
                <form:button name="confirm">Confirm</form:button>
            </form:form>
        </body>
        </html>
    
      .. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
      .. list-table::
        :header-rows: 1
        :widths: 10 90
    
        * - 項番
          - 説明
        * - | (1)
          - | \ ``<form:errors>``\ タグの\ ``path``\ 属性に、対象のフィールド名を指定する。
            | この例では、フィールド毎に入力フィールドの横にエラーメッセージを表示する。

  .. group-tab:: Thymeleaf

    * HTML
    
      \ ``th:errors``\ 属性で、入力エラーがある場合にエラーメッセージを表示できる。
    
      .. code-block:: html
    
        <!DOCTYPE html>
        <html xmlns:th="http://www.thymeleaf.org">
        <!--/* WEB-INF/views/user/createForm.html */-->
        <body>
            <form th:object="${userForm}" method="post" th:action="@{/user/create}">
                <label for="name">Name:</label>
                <input type="text" th:field="*{name}">
                <span id="name-errors" th:errors="*{name}"></span><!--/* (1) */-->
                <br>
                <label for="email">Email:</label>
                <input type="text" th:field="*{email}">
                <span id="email-errors" th:errors="*{email}"></span>
                <br>
                <label for="age">Age:</label>
                <input type="text" th:field="*{age}">
                <span id="age-errors" th:errors="*{age}"></span>
                <br>
                <button id="confirm" name="confirm" type="submit" value="Submit">Confirm</button>
            </form>
        </body>
        </html>
    
      .. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
      .. list-table::
        :header-rows: 1
        :widths: 10 90
    
        * - 項番
          - 説明
        * - | (1)
          - | \ ``<span>``\ タグの\ ``th:errors``\ 属性に、対象のフィールド名を指定する。
            | この例では、フィールド毎に入力フィールドの横にエラーメッセージを表示する。

フォームは、以下のように表示される。

.. figure:: ./images_Validation/validations-first-sample1.png
  :width: 60%

このフォームに対して、すべての入力フィールドを未入力のまま送信すると、以下のようにエラーメッセージが表示される。

.. figure:: ./images_Validation/validations-first-sample2.png
  :width: 60%

NameとEmailが空文字であることに対するエラーメッセージと、Ageが\ ``null``\ であることに対するエラーメッセージが表示されている。

.. note::

  Bean Validationでは、通常、入力値が\ ``null``\ の場合は正常な値とみなす。ただし、以下のアノテーションを除く。

  * \ ``jakarta.validation.constraints.NotNull``\
  * \ ``jakarta.validation.constraints.NotEmpty``\
  * \ ``jakarta.validation.constraints.NotBlank``\

  上記の例では、Ageの値は\ ``null``\ であるため、\ ``@Min``\ と\ ``@Max``\ によるチェックは正常とみなされ、エラーメッセージは出力されていない。

次に、フィールドに何らかの値を入力してフォームを送信する。

.. figure:: ./images_Validation/validations-first-sample3.png
  :width: 60%

| Nameの入力値は、チェック条件を満たすため、エラーメッセージが表示されない。
| E-mailの入力値は文字列長に関する条件は満たすが、E-mail形式ではないため、エラーメッセージが表示される。
| Ageの入力値は最大値を超えているため、エラーメッセージが表示される。

エラー時にスタイルを変更したい場合は、前述のフォームを、以下のように変更する。

.. tabs::
  .. group-tab:: JSP

    .. code-block:: jsp
    
      <form:form modelAttribute="userForm" method="post"
          class="form-horizontal"
          action="${pageContext.request.contextPath}/user/create">
          <form:label path="name" cssErrorClass="error-label">Name:</form:label><%-- (1) --%>
          <form:input path="name" cssErrorClass="error-input" /><%-- (2) --%>
          <form:errors path="name" cssClass="error-messages" /><%-- (3) --%>
          <br>
          <form:label path="email" cssErrorClass="error-label">Email:</form:label>
          <form:input path="email" cssErrorClass="error-input" />
          <form:errors path="email" cssClass="error-messages" />
          <br>
          <form:label path="age" cssErrorClass="error-label">Age:</form:label>
          <form:input path="age" cssErrorClass="error-input" />
          <form:errors path="age" cssClass="error-messages" />
          <br>
          <form:button name="confirm">Confirm</form:button>
      </form:form>
    
    .. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
    .. list-table::
      :header-rows: 1
      :widths: 10 90
    
      * - 項番
        - 説明
      * - | (1)
        - | エラー時に\ ``<label>``\ タグへ加えるクラス名を、\ ``cssErrorClass``\ 属性で指定する。
      * - | (2)
        - | エラー時に\ ``<input>``\ タグへ加えるクラス名を、\ ``cssErrorClass``\ 属性で指定する。
      * - | (3)
        - | エラーメッセージに加えるクラス名を、\ ``cssClass``\ 属性で指定する。

  .. group-tab:: Thymeleaf

    .. code-block:: html
    
      <form th:object="${userForm}" method="post"
          class="form-horizontal" th:action="@{/user/create}">
          <label for="name" name="name" th:errorclass="error-label">Name:</label><!--/* (1) */-->
          <input type="text" th:field="*{name}" th:errorclass="error-input"><!--/* (2) */-->
          <span id="name-errors" th:errors="*{name}" class="error-messages"></span><!--/* (3) */-->
          <br>
          <label for="email" name="email" th:errorclass="error-label">Email:</label>
          <input type="text" th:field="*{email}" th:errorclass="error-input">
          <span id="email-errors" th:errors="*{email}" class="error-messages"></span>
          <br>
          <label for="age" name="age" th:errorclass="error-label">Age:</label>
          <input type="text" th:field="*{age}" th:errorclass="error-input">
          <span id="age-errors" th:errors="*{age}" class="error-messages"></span>
          <br>
          <button id="confirm" name="confirm" type="submit" value="Submit">Confirm</button>
      </form>
    
    .. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
    .. list-table::
      :header-rows: 1
      :widths: 10 90
    
      * - 項番
        - 説明
      * - | (1)
        - | エラー時に\ ``<label>``\ タグへ加えるクラス名を、\ ``th:errorclass``\ 属性で指定する。
          | また、\ ``th:field``\ 属性が指定されていないタグへ\ ``th:errorclass``\ 属性を指定する場合は、対象のフィールド名を\ ``name``\ 属性で指定する。
      * - | (2)
        - | エラー時に\ ``<input>``\ タグへ加えるクラス名を、\ ``th:errorclass``\ 属性で指定する。
      * - | (3)
        - | エラーメッセージに加えるクラス名を、\ ``class``\ 属性で指定する。
    
    .. note:: \ **エラー時にスタイルを変更する方法について**\
    
      実装例のように、\ ``th:errorclass``\ 属性を使用することで、入力チェックエラーがある要素のスタイルを変更することができる。
      
      しかし、\ ``th:errorclass``\ 属性を使用できるのは、同じタグに付与された\ ``th:field``\ 属性または\ ``name``\ 属性により、入力チェックエラーとなったフィールド名（フォームオブジェクトのプロパティ名）が特定できる場合のみとなる。
      
      入力項目以外のスタイルを変更したい場合は、\ ``#fields.hasErrors('fieldName')``\ を使用してフィールドに入力チェックエラーが存在するかを判定することでスタイルを変更することができる。
      
      例えば、\ ``#fields.hasErrors('fieldName')``\ を使用して上記実装例の(1)と同じ仕様を実現する場合には、以下のような構文となる。
      
      * \ ``th:classappend="${#fields.hasErrors('name')} ? 'error-label'"``\
    
    .. note::
    
      \ ``class``\ 属性が指定されているタグに\ ``th:errorclass``\ 属性をあわせて指定した場合、エラー時には、\ ``class``\ 属性で指定した値に\ ``th:errorclass``\ 属性で指定した値が追加される。

このJSPまたはHTMLに対して、例えば以下のCSSを適用すると、

.. code-block:: css

  .form-horizontal input {
      display: block;
      float: left;
  }

  .form-horizontal label {
      display: block;
      float: left;
      text-align: right;
      float: left;
  }

  .form-horizontal br {
      clear: left;
  }

  .error-label {
      color: #b94a48;
  }

  .error-input {
      border-color: #b94a48;
      margin-left: 5px;
  }

  .error-messages {
      color: #b94a48;
      display: block;
      padding-left: 5px;
      overflow-x: auto;
  }

エラー画面は、以下のように表示される。

.. figure:: ./images_Validation/validations-has-errors1.png
  :width: 60%

画面の要件に応じてCSSをカスタマイズすればよい。

エラーメッセージを、入力フィールドの横に一件一件出力する代わりに、まとめて出力することもできる。

.. tabs::
  .. group-tab:: JSP

    .. code-block:: jsp
    
      <form:form modelAttribute="userForm" method="post"
          action="${pageContext.request.contextPath}/user/create">
          <form:errors path="*" element="div" cssClass="error-message-list" /><%-- (1) --%>
    
          <form:label path="name" cssErrorClass="error-label">Name:</form:label>
          <form:input path="name" cssErrorClass="error-input" />
          <br>
          <form:label path="email" cssErrorClass="error-label">Email:</form:label>
          <form:input path="email" cssErrorClass="error-input" />
          <br>
          <form:label path="age" cssErrorClass="error-label">Age:</form:label>
          <form:input path="age" cssErrorClass="error-input" />
          <br>
          <form:button name="confirm">Confirm</form:button>
      </form:form>
    
    .. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
    .. list-table::
      :header-rows: 1
      :widths: 10 90
    
      * - 項番
        - 説明
      * - | (1)
        - | \ ``<form:form>``\ タグ内で、\ ``<form:errors>``\ の\ ``path``\ 属性に"\ ``*``\ "を指定することで、
          | \ ``<form:form>``\ の\ ``modelAttribute``\ 属性に指定したModelに関する全エラーメッセージを出力できる。
          | \ ``element``\ 属性に、これらのエラーメッセージを包含するタグ名を指定できる。デフォルトでは、\ ``span``\ であるが、
          | ここではエラーメッセージ一覧をブロック要素として出力するために、\ ``div``\ を指定する。
          | また、CSSのクラスを\ ``cssClass``\ 属性に指定する。

  .. group-tab:: Thymeleaf

    .. code-block:: html
    
      <form th:object="${userForm}" method="post" th:action="@{/user/create}">
          <div id="userForm-errors" th:errors="*{*}" class="error-message-list"></div><!--/* (1) */-->
          <label for="name" name="name" th:errorclass="error-label">Name:</label>
          <input type="text" th:field="*{name}" th:errorclass="error-input">
          <br>
          <label for="email" name="email" th:errorclass="error-label">Email:</label>
          <input type="text" th:field="*{email}" th:errorclass="error-input">
          <br>
          <label for="age" name="age" th:errorclass="error-label">Age:</label>
          <input type="text" th:field="*{age}" th:errorclass="error-input">
          <br>
          <button id="confirm" name="confirm" type="submit" value="Submit">Confirm</button>
      </form>
    
    .. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
    .. list-table::
      :header-rows: 1
      :widths: 10 90
    
      * - 項番
        - 説明
      * - | (1)
        - | \ ``<form>``\ タグ内で、メッセージを包含するタグの\ ``th:errors``\ 属性に\ ``*{*}``\ を指定することで、
          | \ ``<form>``\ タグの\ ``th:object``\ 属性に指定したModelに関する全エラーメッセージを出力できる。
          | （なお、\ ``*{*}``\ の部分を\ ``*{all}``\ と指定しても同等である。）
          | ここではエラーメッセージ一覧をブロック要素として出力するために、\ ``div``\ を指定している。
          | また、CSSのクラスを\ ``class``\ 属性に指定する。
    
    .. tip:: \ **エラーメッセージを一覧で表示する際のHTML構造を独自に定義する方法**\
    
      \ ``th:errors="*{*}"``\ と指定した場合、各エラーは\ ``<br>``\ 区切りで出力される。
      \ ``<br>``\ 区切りではなく独自のHTML構造で出力したい場合は、\ ``#fields.allErrors()``\ メソッドを利用することで対応できる。
    
      以下に、実装例を示す。
    
        .. code-block:: html
    
          <ul th:if="${#fields.hasAnyErrors()}"> <!--/* (1) */-->
              <li th:each="err : ${#fields.allErrors()}" th:text="${err}"></li> <!--/* (2) */-->
          </ul>
    
        .. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
        .. list-table::
          :header-rows: 1
          :widths: 10 90
    
          * - 項番
            - 説明
          * - | (1)
            - | \ ``#fields.hasAnyErrors()``\ メソッドを利用してエラー有無を取得し、\ ``th:if``\ 属性を用いてエラーがない場合はタグを生成しないようにしている。
              | （なお、\ ``#fields.hasAnyErrors()``\ の部分を\ ``#fields.hasErrors('*')``\ と指定しても同等である。）
          * - | (2)
            - | \ ``#fields.allErrors()``\ メソッドを利用してすべてのエラーを取得し、\ ``th:each``\ 属性を用いて繰り返し処理を行い\ ``li``\ タグを生成している。
              | （なお、\ ``#fields.allErrors()``\ の部分を\ ``#fields.errors('*')``\ と指定しても同等である。）

例として、以下のCSSクラスを適用した場合の、エラーメッセージ出力例を示す。

.. code-block:: css

  .form-horizontal input {
      display: block;
      float: left;
  }

  .form-horizontal label {
      display: block;
      float: left;
      text-align: right;
      float: left;
  }

  .form-horizontal br {
      clear: left;
  }

  .error-label {
      color: #b94a48;
  }

  .error-input {
      border-color: #b94a48;
      margin-left: 5px;
  }

  .error-message-list {
      color: #b94a48;
      padding:5px 10px;
      background-color: #fde9f3;
      border:1px solid #c98186;
      border-radius:5px;
      margin-bottom: 10px;
  }

.. figure:: ./images_Validation/validations-has-errors2.png
  :width: 60%

| デフォルトでは、エラーメッセージにフィールド名は含まれず、どのフィールドのエラーメッセージなのかが分かりにくい。
| そのため、エラーメッセージを一覧で表示する場合は、エラーメッセージの中にフィールド名を含めるようにメッセージを定義する必要がある。
| エラーメッセージの定義方法については、「\ :ref:`ValidationMessageDef`\ 」を参照されたい。

.. note:: \ **エラーメッセージを一覧で表示する際の注意点**\

  エラーメッセージの出力順序は順不同であり、標準機能で出力順序を制御することはできない。そのため、出力順序を制御する(一定に保つ)必要がある場合は、エラー情報をソートするなどの拡張実装が必要となる。

  「エラーメッセージを一覧で表示する」方式では、

  * フィールド単位のエラーメッセージ定義
  * エラーメッセージの出力順序を制御するための拡張実装

  が必要となるため、「入力フィールドの横にエラーメッセージを表示する」方式に比べて対応コストが高くなる。
  \ **本ガイドラインでは、画面要件による制約がない場合は「入力フィールドの横にエラーメッセージを表示する」方式を推奨する。**\

  なお、エラーメッセージの出力順序を制御するための拡張方法としては、Spring Frameworkから提供されている\ ``org.springframework.validation.beanvalidation.LocalValidatorFactoryBean``\ の継承クラスを作成し、\ ``processConstraintViolations``\ メソッドをオーバーライドしてエラー情報をソートする方法などが考えられる。

.. note:: \ **@GroupSequenceアノテーションについて**\

  チェック順番を制御するための仕組みとして\ :url_hibernate_validator:`@GroupSequenceアノテーション </reference/en-US/html_single/#_code_groupsequence_code>`\ が提供されているが、この仕組みは以下のような動作になるため、エラーメッセージの出力順序を制御するための仕組みではないという点を補足しておく。

  * エラーが発生した場合に後続のグループのチェックが実行されない。
  * 同一グループ内のチェックで複数のエラー(複数の項目でエラー)が発生するとエラーメッセージの出力順序は順不同になる。

.. tabs::
  .. group-tab:: JSP

    エラーメッセージをまとめて表示する際に、\ ``<form:form>``\ タグの外に表示したい場合は以下のように\ ``<spring:nestedPath>``\ タグを使用する。
    
      .. code-block:: jsp
    
        <spring:nestedPath path="userForm">
            <form:errors path="*" element="div"
                cssClass="error-message-list" />
        </spring:nestedPath>
        <hr>
        <form:form modelAttribute="userForm" method="post"
            action="${pageContext.request.contextPath}/user/create">
            <form:label path="name" cssErrorClass="error-label">Name:</form:label>
            <form:input path="name" cssErrorClass="error-input" />
            <br>
            <form:label path="email" cssErrorClass="error-label">Email:</form:label>
            <form:input path="email" cssErrorClass="error-input" />
            <br>
            <form:label path="age" cssErrorClass="error-label">Age:</form:label>
            <form:input path="age" cssErrorClass="error-input" />
            <br>
            <form:button name="confirm">Confirm</form:button>
        </form:form>

  .. group-tab:: Thymeleaf

    エラーメッセージをまとめて表示する際に、\ ``th:object``\ 属性を指定した要素（\ ``<form>``\ タグなど）の外に表示したい場合は以下のように\ ``th:errors``\ 属性に\ ``Modelに格納されているフォームオブジェクトの属性名.*``\ で指定する。

      .. code-block:: html

        <div id="userForm-errors" th:errors="${userForm.*}" class="error-message-list"></div>
        <hr>
        <form th:object="${userForm}" method="post" th:action="@{/user/create}">
            <label for="name" name="name" th:errorclass="error-label">Name:</label>
            <input type="text" th:field="*{name}" th:errorclass="error-input">
            <br>
            <label for="email" name="email" th:errorclass="error-label">Email:</label>
            <input type="text" th:field="*{email}" th:errorclass="error-input">
            <br>
            <label for="age" name="age" th:errorclass="error-label">Age:</label>
            <input type="text" th:field="*{age}" th:errorclass="error-input">
            <br>
            <button id="confirm" name="confirm" type="submit" value="Submit">Confirm</button>
        </form>

|

日時フォーマットのチェック
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

| 日時フォーマットのチェックを行う場合には、Bean Validationの仕組みではなく、Springが提供する日時のフォーマットを指定する\ ``@DateTimeFormat``\ アノテーションの使用を推奨する。
| \ ``@DateTimeFormat``\ アノテーションの使用方法については、\ :ref:`ApplicationLayer-DateTimeFormat`\ を参照されたい。
| Bean Validationの\ ``@Pattern``\ アノテーションを使用することでも日時フォーマットのチェックは可能である。
| しかし、\ ``@Pattern``\ アノテーションを使用すると、日時フォーマットを正規表現で記述する必要があり、存在しない日時をチェックする場合には、記述が煩雑化する。
| そのため、\ ``@Pattern``\ アノテーションよりも\ ``@DateTimeFormat``\ アノテーションのほうが実装はシンプルになる。

| \ ``@DateTimeFormat``\ アノテーションはSpringが提供する型変換の仕組みのひとつであるので、入力エラーの場合には、Bean Validationのエラーメッセージではなく、型のミスマッチが発生した時にスローされる例外(\ ``TypeMismatchException``\ )の例外メッセージがそのまま画面へ表示される。
| 例外メッセージが画面に表示されることを避けるため、型のミスマッチが発生した際のエラーメッセージを\ **プロパティファイル**\ に設定する必要がある。
| 詳細は\ :ref:`ValidationTypeMismatch`\ を参照されたい。
|

.. _ValidationNestedBeanSingleItemCheck:

ネストしたBeanの単項目チェック
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

ネストしたBeanをBean Validationで検証する方法を説明する。

ECサイトにおける「注文」処理の例を考える。「注文」フォームでは、以下のチェックルールを設ける。

.. tabularcolumns:: |p{0.20\linewidth}|p{0.30\linewidth}|p{0.30\linewidth}|p{0.20\linewidth}|
.. list-table::
  :header-rows: 1
  :widths: 20 30 30 20

  * - フィールド名
    - 型
    - ルール
    - 説明
  * - | coupon
    - | \ ``java.lang.String``\
    - | 5文字以下
      | 半角英数字
    - | クーポンコード
  * - | receiverAddress.name
    - | \ ``java.lang.String``\
    - | 入力必須
      | 1文字以上
      | 50文字以下
    - | お届け先氏名
  * - | receiverAddress.postcode
    - | \ ``java.lang.String``\
    - | 入力必須
      | 1文字以上
      | 10文字以下
    - | お届け先郵便番号
  * - | receiverAddress.address
    - | \ ``java.lang.String``\
    - | 入力必須
      | 1文字以上
      | 100文字以下
    - | お届け先住所
  * - | senderAddress.name
    - | \ ``java.lang.String``\
    - | 入力必須
      | 1文字以上
      | 50文字以下
    - | 請求先氏名
  * - | senderAddress.postcode
    - | \ ``java.lang.String``\
    - | 入力必須
      | 1文字以上
      | 10文字以下
    - | 請求先郵便番号
  * - | senderAddress.address
    - | \ ``java.lang.String``\
    - | 入力必須
      | 1文字以上
      | 100文字以下
    - | 請求先住所

\ ``receiverAddress``\ と\ ``senderAddress``\ は、同じ項目であるため、同じフォームクラスを使用する。

* フォームクラス

  .. code-block:: java

    package com.example.sample.app.validation;

    import java.io.Serializable;

    import jakarta.validation.Valid;
    import jakarta.validation.constraints.NotNull;
    import jakarta.validation.constraints.Pattern;
    import jakarta.validation.constraints.Size;

    public class OrderForm implements Serializable {
        private static final long serialVersionUID = 1L;

        @Size(max = 5)
        @Pattern(regexp = "[a-zA-Z0-9]*")
        private String coupon;

        @NotNull // (1)
        @Valid // (2)
        private AddressForm receiverAddress;

        @NotNull
        @Valid
        private AddressForm senderAddress;

        // omitted setter/getter
    }

  .. code-block:: java

    package com.example.sample.app.validation;

    import java.io.Serializable;

    import jakarta.validation.constraints.NotNull;
    import jakarta.validation.constraints.Size;

    public class AddressForm implements Serializable {
        private static final long serialVersionUID = 1L;

        @NotNull
        @Size(min = 1, max = 50)
        private String name;

        @NotNull
        @Size(min = 1, max = 10)
        private String postcode;

        @NotNull
        @Size(min = 1, max = 100)
        private String address;

        // omitted setter/getter
    }

  .. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
  .. list-table::
    :header-rows: 1
    :widths: 10 90

    * - 項番
      - 説明
    * - | (1)
      - | 子フォーム自体が必須であることを示す。
        | この設定がない場合、\ ``receiverAddress``\ に\ ``null``\ が設定されても、正常とみなされる。
    * - | (2)
      - | ネストしたBeanのBean Validationを有効にするために、\ ``jakarta.validation.Valid``\ アノテーションを付与する。

* Controllerクラス

  前述のControllerと違いはない。

  .. code-block:: java

    package com.example.sample.app.validation;

    import org.springframework.stereotype.Controller;
    import org.springframework.validation.BindingResult;
    import org.springframework.validation.annotation.Validated;
    import org.springframework.web.bind.annotation.GetMapping;
    import org.springframework.web.bind.annotation.ModelAttribute;
    import org.springframework.web.bind.annotation.PostMapping;
    import org.springframework.web.bind.annotation.RequestMapping;

    @RequestMapping("order")
    @Controller
    public class OrderController {

        @ModelAttribute
        public OrderForm setupForm() {
            return new OrderForm();
        }

        @GetMapping(value = "order", params = "form")
        public String orderForm() {
            return "order/orderForm";
        }

        @PostMapping(value = "order", params = "confirm")
        public String orderConfirm(@Validated OrderForm form, BindingResult result) {
            if (result.hasErrors()) {
                return "order/orderForm";
            }
            return "order/orderConfirm";
        }
    }

* View

  .. tabs::
    .. group-tab:: JSP
  
      .. code-block:: jsp
  
        <!DOCTYPE html>
        <html>
        <%-- WEB-INF/views/order/orderForm.jsp --%>
        <head>
        <style type="text/css">
          /* omitted (same as previous sample) */
        </style>
        </head>
        <body>
            <form:form modelAttribute="orderForm" method="post"
                class="form-horizontal"
                action="${pageContext.request.contextPath}/order/order">
                <form:label path="coupon" cssErrorClass="error-label">Coupon Code:</form:label>
                <form:input path="coupon" cssErrorClass="error-input" />
                <form:errors path="coupon" cssClass="error-messages" />
                <br>
                <fieldset>
                    <legend>Receiver</legend>
                    <%-- (1) --%>
                    <form:errors path="receiverAddress"
                        cssClass="error-messages" />
                    <%-- (2) --%>
                    <form:label path="receiverAddress.name"
                        cssErrorClass="error-label">Name:</form:label>
                    <form:input path="receiverAddress.name"
                        cssErrorClass="error-input" />
                    <form:errors path="receiverAddress.name"
                        cssClass="error-messages" />
                    <br>
                    <form:label path="receiverAddress.postcode"
                        cssErrorClass="error-label">Postcode:</form:label>
                    <form:input path="receiverAddress.postcode"
                        cssErrorClass="error-input" />
                    <form:errors path="receiverAddress.postcode"
                        cssClass="error-messages" />
                    <br>
                    <form:label path="receiverAddress.address"
                        cssErrorClass="error-label">Address:</form:label>
                    <form:input path="receiverAddress.address"
                        cssErrorClass="error-input" />
                    <form:errors path="receiverAddress.address"
                        cssClass="error-messages" />
                </fieldset>
                <br>
                <fieldset>
                    <legend>Sender</legend>
                    <form:errors path="senderAddress"
                        cssClass="error-messages" />
                    <form:label path="senderAddress.name"
                        cssErrorClass="error-label">Name:</form:label>
                    <form:input path="senderAddress.name"
                        cssErrorClass="error-input" />
                    <form:errors path="senderAddress.name"
                        cssClass="error-messages" />
                    <br>
                    <form:label path="senderAddress.postcode"
                        cssErrorClass="error-label">Postcode:</form:label>
                    <form:input path="senderAddress.postcode"
                        cssErrorClass="error-input" />
                    <form:errors path="senderAddress.postcode"
                        cssClass="error-messages" />
                    <br>
                    <form:label path="senderAddress.address"
                        cssErrorClass="error-label">Address:</form:label>
                    <form:input path="senderAddress.address"
                        cssErrorClass="error-input" />
                    <form:errors path="senderAddress.address"
                        cssClass="error-messages" />
                </fieldset>
    
                <form:button name="confirm">Confirm</form:button>
            </form:form>
        </body>
        </html>
    
      .. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
      .. list-table::
        :header-rows: 1
        :widths: 10 90
    
        * - 項番
          - 説明
        * - | (1)
          - | 不正な操作により、\ ``receiverAddress.name``\ 、\ ``receiverAddress.postcode``\ 、\ ``receiverAddress.address``\ のすべて
            | がリクエストパラメータとして送信されない場合、\ ``receiverAddress``\ が\ ``null``\ とみなされ、この位置にエラーメッセージが表示される。
        * - | (2)
          - | 子フォームのフィールドは、\ ``親フィールド名.子フィールド名``\ で指定する。
  
    .. group-tab:: Thymeleaf
  
      .. code-block:: html
    
        <!DOCTYPE html>
        <html xmlns:th="http://www.thymeleaf.org">
        <!--/* WEB-INF/views/order/orderForm.html */-->
        <head>
        <style type="text/css">
          /* omitted (same as previous sample) */
        </style>
        </head>
        <body>
            <form th:object="${orderForm}" method="post"
                class="form-horizontal" th:action="@{/order/order}">
                <label for="coupon" name="coupon" th:errorclass="error-label">Coupon Code:</label>
                <input type="text" th:field="*{coupon}" th:errorclass="error-input">
                <span id="coupon-errors" th:errors="*{coupon}" class="error-messages"></span>
                <br>
                <fieldset>
                    <legend>Receiver</legend>
                    <!--/* (1) */-->
                    <span id="receiverAddress-errors" th:errors="*{receiverAddress}"
                        class="error-messages"></span>
                    <!--/* (2) */-->
                    <label for="receiverAddress.name" name="receiverAddress.name"
                        th:errorclass="error-label">Name:</label>
                    <input type="text" th:field="*{receiverAddress.name}"
                        th:errorclass="error-input" />
                    <span id="receiverAddress-name-errors" th:errors="*{receiverAddress.name}"
                        class="error-messages"></span>
                    <br>
                    <label for="receiverAddress.postcode" name="receiverAddress.postcode"
                        th:errorclass="error-label">Postcode:</label>
                    <input type="text" th:field="*{receiverAddress.postcode}"
                        th:errorclass="error-input" />
                    <span id="receiverAddress-postcode-errors" th:errors="*{receiverAddress.postcode}"
                        class="error-messages"></span>
                    <br>
                    <label for="receiverAddress.address" name="receiverAddress.address"
                        th:errorclass="error-label">Address:</label>
                    <input type="text" th:field="*{receiverAddress.address}"
                        th:errorclass="error-input" />
                    <span id="receiverAddress-address-errors" th:errors="*{receiverAddress.address}"
                        class="error-messages"></span>
                </fieldset>
                <br>
                <fieldset>
                    <legend>Sender</legend>
                    <span id="senderAddress-errors" th:errors="*{senderAddress}"
                        class="error-messages"></span>
                    <label for="senderAddress.name" name="senderAddress.name"
                        th:errorclass="error-label">Name:</label>
                    <input type="text" th:field="*{senderAddress.name}"
                        th:errorclass="error-input" />
                    <span id="senderAddress-name-errors" th:errors="*{senderAddress.name}"
                        class="error-messages"></span>
                    <br>
                    <label for="senderAddress.postcode" name="senderAddress.postcode"
                        th:errorclass="error-label">Postcode:</label>
                    <input type="text" th:field="*{senderAddress.postcode}"
                        th:errorclass="error-input" />
                    <span id="senderAddress-postcode-errors" th:errors="*{senderAddress.postcode}"
                        class="error-messages"></span>
                    <br>
                    <label for="senderAddress.address" name="senderAddress.address"
                        th:errorclass="error-label">Address:</label>
                    <input type="text" th:field="*{senderAddress.address}"
                        th:errorclass="error-input" />
                    <span id="senderAddress-address-errors" th:errors="*{senderAddress.address}"
                        class="error-messages"></span>
                </fieldset>
    
                <button id="confirm" name="confirm" type="submit" value="Submit">Confirm</button>
            </form>
        </body>
        </html>
  
      .. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
      .. list-table::
        :header-rows: 1
        :widths: 10 90
    
        * - 項番
          - 説明
        * - | (1)
          - | 不正な操作により、\ ``receiverAddress.name``\ 、\ ``receiverAddress.postcode``\ 、\ ``receiverAddress.address``\ のすべてがリクエストパラメータとして送信されない場合、\ ``receiverAddress``\ が\ ``null``\ とみなされ、この位置にエラーメッセージが表示される。
        * - | (2)
          - | 子フォームのフィールドは、\ ``親フィールド名.子フィールド名``\ で指定する。

フォームは、以下のように表示される。

.. figure:: ./images_Validation/validations-nested1.png
  :width: 60%

このフォームに対して、すべての入力フィールドを未入力のまま送信すると、以下のようにエラーメッセージが表示される。

.. figure:: ./images_Validation/validations-nested2.png
  :width: 60%

ネストしたBeanのバリデーションはコレクションに対しても有効である。

最初に説明した「ユーザー登録」フォームに住所を3件まで登録できるようにフィールドを追加する。住所には、前述の\ ``AddressForm``\ を利用する。

* フォームクラス

  \ ``AddressForm``\ のリストを、フィールドに追加する。

  .. code-block:: java

    package com.example.sample.app.validation;

    import java.io.Serializable;
    import java.util.ArrayList;
    import jakarta.validation.Valid;
    import jakarta.validation.constraints.NotNull;
    import jakarta.validation.constraints.Size;

    public class UserForm implements Serializable {

        private static final long serialVersionUID = 1L;

        @NotNull
        @Size(min = 1, max = 20)
        private String name;

        @NotNull
        @Size(min = 1, max = 50)
        @Email
        private String email;

        @NotNull
        @Min(0)
        @Max(200)
        private Integer age;

        @NotNull
        @Size(min = 1, max = 3) // (1)
        @Valid
        private ArrayList<AddressForm> addresses;

        // omitted setter/getter
    }

  .. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
  .. list-table::
    :header-rows: 1
    :widths: 10 90

    * - 項番
      - 説明
    * - | (1)
      - | コレクションのサイズチェックにも、\ ``@Size``\ アノテーションを使用できる。

|

* View

  .. tabs::
    .. group-tab:: JSP

      .. code-block:: jsp
    
        <!DOCTYPE html>
        <html>
        <%-- WEB-INF/views/user/createForm.jsp --%>
        <head>
        <style type="text/css">
          /* omitted (same as previous sample) */
        </style>
        </head>
        <body>
            <form:form method="post" action="${pageContext.request.contextPath}/user/create"
                modelAttribute="userForm" class="form-horizontal">
                <div class="form-group">
                    <div class="col-sm-10">
                        <form:errors path="addresses" class="text-danger" /><%-- (1) --%>
                    </div>
                </div>
                <c:forEach items="${ userForm.addresses }" varStatus="status"><%-- (2) --%>
                    <fieldset class="address">
                        <legend id="Address${ status.index }">Address${ f:h(status.index + 1) }</legend>
                        <div class="form-group">
                            <form:label path="addresses[${ status.index }].userName"
                                class="col-sm-2 control-label">UserName</form:label><%-- (3) --%>
                            <div class="col-sm-10">
                                <form:input path="addresses[${ status.index }].userName"
                                    class="form-control" placeholder="UserName" />
                                <form:errors path="addresses[${ status.index }].userName"
                                    class="text-danger" />
                            </div>
                        </div>
                        <div class="form-group">
                            <form:label path="addresses[${ status.index }].postCode"
                                class="col-sm-2 control-label">PostCode</form:label>
                            <div class="col-sm-10">
                                <form:input path="addresses[${ status.index }].postCode"
                                    class="form-control" placeholder="PostCode" />
                                <form:errors path="addresses[${ status.index }].postCode"
                                  class="text-danger" />
                            </div>
                        </div>
                        <div class="form-group">
                            <form:label path="addresses[${ status.index }].address"
                                class="col-sm-2 control-label">Address</form:label>
                            <div class="col-sm-10">
                                <form:input path="addresses[${ status.index }].address"
                                    class="form-control" placeholder="Address" />
                                <form:errors path="addresses[${ status.index }].address"
                                    class="text-danger" />
                            </div>
                        </div>
                        <c:if test="${ status.index > 0 }">
                            <div class="form-group">
                                <div class="col-sm-offset-2 col-sm-10">
                                    <form:button id="remove${ status.index }" name="remove"
                                        value="${ status.index }"
                                        class="btn btn-default">remove</form:button>
                                </div>
                            </div>
                        </c:if>
                    </fieldset>
                    <br>
                </c:forEach>
                <div class="form-group">
                    <div class="col-sm-offset-2 col-sm-10">
                        <form:button id="add" name="add" class="btn btn-default">add</form:button>
                    </div>
                </div>
                <div class="form-group">
                    <div class="col-sm-offset-2 col-sm-10">
                        <form:button id="validate" name="validate"
                            class="btn btn-default">validate</form:button>
                    </div>
                </div>
            </form:form>
        </body>
        </html>

      .. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
      .. list-table::
        :header-rows: 1
        :widths: 10 90
    
        * - 項番
          - 説明
        * - | (1)
          - | \ ``addresses``\ フィールドに対するエラーメッセージを表示する。
        * - | (2)
          - | 子フォームのコレクションを、\ ``<c:forEach>``\ タグを使ってループで処理する。
        * - | (3)
          - | コレクション中の子フォームのフィールドは、\ ``親フィールド名[インデックス].子フィールド名``\ で指定する。

    .. group-tab:: Thymeleaf

      .. code-block:: html
    
        <!DOCTYPE html>
        <html xmlns:th="http://www.thymeleaf.org">
        <!--/* WEB-INF/views/user/createForm.html */-->
        <head>
        <style type="text/css">
          /* omitted (same as previous sample) */
        </style>
        </head>
        <body>
            <form method="post" th:action="@{/user/create}" th:object="${userForm}"
                class="form-horizontal">
                <div class="form-group">
                    <div class="col-sm-10">
                        <span id="addresses.errors" th:errors="*{addresses}"
                            class="text-danger"></span><!--/* (1) */-->
                    </div>
                </div>
                <div th:each="addresses,status : ${userForm.addresses}"><!--/* (2) */-->
                    <fieldset class="address">
                        <legend th:id="'Address'+${status.index}"
                            th:text="|Address${status.index + 1}|"></legend>
                        <div class="form-group">
                            <label th:for="|addresses${status.index}.userName|"
                                class="col-sm-2 control-label">UserName</label>
                            <div class="col-sm-10">
                                <input type="text"
                                    th:field="*{addresses[__${status.index}__].userName}"
                                    class="form-control" placeholder="UserName" /><!--/* (3) */-->
                                <span th:id="'addresses'+${status.index}+'.userName.errors'"
                                    th:errors="*{addresses[__${status.index}__].userName}"
                                    class="text-danger"></span>
                            </div>
                        </div>
                        <div class="form-group">
                            <label th:for="|addresses${status.index}.postCode|"
                                class="col-sm-2 control-label">PostCode</label>
                            <div class="col-sm-10">
                                <input type="text"
                                    th:field="*{addresses[__${status.index}__].postCode}"
                                    class="form-control" placeholder="PostCode" />
                                <span th:id="'addresses'+${status.index}+'.postCode.errors'"
                                    th:errors="*{addresses[__${status.index}__].postCode}"
                                    class="text-danger"></span>
                            </div>
                        </div>
                        <div class="form-group">
                            <label th:for="|addresses${status.index}.address|"
                                class="col-sm-2 control-label">Address</label>
                            <div class="col-sm-10">
                                <input type="text"
                                    th:field="*{addresses[__${status.index}__].address}"
                                    class="form-control" placeholder="Address" />
                                <span th:id="'addresses'+${status.index}+'.address.errors'"
                                    th:errors="*{addresses[__${status.index}__].address}"
                                    class="text-danger"></span>
                            </div>
                        </div>
                        <div th:if="${status.index > 0}">
                            <div class="form-group">
                                <div class="col-sm-offset-2 col-sm-10">
                                    <button th:id="'remove'+${status.index}" name="remove"
                                        class="btn btn-default" type="submit"
                                        th:value="${status.index}">remove</button>
                                </div>
                            </div>
                        </div>
                    </fieldset>
                    <br>
                </div>
                <div class="form-group">
                    <div class="col-sm-offset-2 col-sm-10">
                        <button id="add" name="add" class="btn btn-default" type="submit"
                        value="Submit">add</button>
                    </div>
                </div>
                <div class="form-group">
                    <div class="col-sm-offset-2 col-sm-10">
                        <button id="validate" name="validate" class="btn btn-default" type="submit"
                            value="Submit">validate</button>
                    </div>
                </div>
            </form>
        </body>
        </html>

      .. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
      .. list-table::
         :header-rows: 1
         :widths: 10 90
    
         * - 項番
           - 説明
         * - | (1)
           - | \ ``addresses``\ フィールドに対するエラーメッセージを表示する。
         * - | (2)
           - | 子フォームのコレクションを、\ ``th:each``\ 属性を使ってループで処理する。
         * - | (3)
           - | コレクション中の子フォームのフィールドは、\ ``親フィールド名[インデックス].子フィールド名``\ で指定する。
             | なお、インデックスを先に評価させる必要があるため、プリプロセッシング式（\ ``__${...}__``\ ）を利用している。
             | プリプロセッシング式の詳細については、\ :ref:`view_thymeleaf_preprocessing-label`\ を参照されたい。

|

* Controllerクラス

  .. code-block:: java

    package com.example.sample.app.validation;

    import java.util.ArrayList;
    import org.springframework.stereotype.Controller;
    import org.springframework.ui.Model;
    import org.springframework.validation.BindingResult;
    import org.springframework.validation.annotation.Validated;
    import org.springframework.web.bind.annotation.GetMapping;
    import org.springframework.web.bind.annotation.ModelAttribute;
    import org.springframework.web.bind.annotation.PostMapping;
    import org.springframework.web.bind.annotation.RequestMapping;

    @Controller
    @RequestMapping("user")
    public class UserController {

        @ModelAttribute
        public UserForm setUpForm() {
            UserForm form = new UserForm();
            ArrayList<AddressForm> addresses = new ArrayList<>();
            addresses.add(new AddressForm());
            form.setAddresses(addresses);
            return form;
        }

        @GetMapping(value = "create", params = "form")
        public String createForm() {
            return "user/createForm";
        }

        @PostMapping(value = "create", params = "confirm")
        public String createConfirm(@Validated UserForm form, BindingResult result) {
            if (result.hasErrors()) {
                return "user/createForm";
            }
            return "user/createConfirm";
        }

        @PostMapping(value = "create", params = "add")
        public String handleAdd(UserForm form, Model model) {
            ArrayList<AddressForm> addresses = form.getAddresses();
            addresses.add(new AddressForm());
            model.addAttribute("addresses", addresses);
            return "user/createForm";
        }

        @PostMapping(value = "create", params = "remove")
        public String handleRemove(UserForm form, Model model, Integer remove) {
            ArrayList<AddressForm> addresses = form.getAddresses();
            if (remove != null && remove >= 0 && remove < addresses.size()) {
                addresses.remove(remove.intValue());
            }
            model.addAttribute("addresses", addresses);
            return "user/createForm";
        }
    }

  .. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
  .. list-table::
    :header-rows: 1
    :widths: 10 90

    * - 項番
      - 説明
    * - | (1)
      - | 「ユーザー登録」フォーム初期表示時に、一件の住所フォームを表示させるために、フォームオブジェクトを編集する。

|

フォームは、以下のように表示される。

.. figure:: ./images_Validation/validations-nested-collection1.png
  :width: 50%

「Add address」ボタンを2回押して、住所フォームを2件追加する。

.. figure:: ./images_Validation/validations-nested-collection2.png
  :width: 50%

このフォームに対して、すべての入力フィールドを未入力のまま送信すると、以下のようにエラーメッセージが表示される。

.. figure:: ./images_Validation/validations-nested-collection3.png
  :width: 50%

.. note::

  入力フィールドの追加/削除は、JavaScriptで実行することもできる。JavaScriptで実行する場合のコード例については、\ :ref:`ValidationWhenAddingRemovingInputFieldsUsingJavaScript`\ を参照されたい。

|

コレクション内の値のチェック
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

複数選択可能な画面項目（チェックボックスや複数選択ドロップダウンなど）を扱う際は、フォームクラスで画面項目を \ ``String``\ 等の基本型のコレクションとして扱うことが一般的である。

ここでは、Bean Validation 2.0の標準アノテーションである\ ``@NotEmpty``\ 及び共通ライブラリが提供する\ ``@ExistInCodeList``\ を例に、コレクション内の値の入力チェックを行う例を示す。

* フォームクラス

  .. code-block:: java

    package com.example.sample.app.validation;

    import java.util.List;
    
    import jakarta.validation.constraints.NotEmpty;
    
    import org.terasoluna.gfw.common.codelist.ExistInCodeList;

    public class SampleForm {
        @NotEmpty
        private List<@NotEmpty @ExistInCodeList(codeListId = "CL_ROLE") String> roles; // (1)

        public List<String> getRoles() {
            return roles;
        }

        public void setRoles(List<String> roles) {
            this.roles = roles;
        }
    }

  .. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
  .. list-table::
     :header-rows: 1
     :widths: 10 90

     * - 項番
       - 説明
     * - | (1)
       - | 入力チェック対象となるコレクションの型引数に対して\ ``@NotEmpty``\ アノテーション及び\ ``@ExistInCodeList``\ アノテーションを設定する。
         | \ ``@ExistInCodeList``\ アノテーションの\ ``codeListId``\ パラメータにチェック元となるコードリストを指定する。

* View

  .. tabs::
    .. group-tab:: JSP

      .. code-block:: jsp
    
        <form:form modelAttribute="sampleForm">
            <!-- (1) -->
            <form:checkboxes path="roles" items="${CL_ROLE}"/>
            <form:errors path="roles*"/>
            <form:button>Submit</form:button>
        </form:form>
    
      .. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
      .. list-table::
        :header-rows: 1
        :widths: 10 90
    
        * - 項番
          - 説明
        * - | (1)
          - |  \ ``<form:checkboxes>``\ を実装する。

    .. group-tab:: Thymeleaf

      .. code-block:: html
    
        <form th:object="${roleForCollectionForm}">
            <!-- (1) -->
            <span th:each="var : ${CL_ROLE}">
                <input type="checkbox" th:field="*{roles}" th:value="${var.key}" />
                <label th:for="${#ids.prev('roles')}" th:text="${var.value}" />
            </span>
            <span id="roles*.errors" th:errors="*{roles*}"></span>
            <button type="submit">Submit</button>
        </form>
    
      .. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
      .. list-table::
        :header-rows: 1
        :widths: 10 90
    
        * - 項番
          - 説明
        * - | (1)
          - |  チェックボックスを実装する。
    
      .. _ValidationIdsPrevMethod:
    
      .. note:: \ **#ids.prevメソッドについて**\
    
        \ ``#ids``\ を利用すると、繰り返し処理の中でIDを生成するのが容易になる。上記の実装例では、\ ``label``\ タグの\ ``for``\ 属性に\ ``#ids.prev``\ メソッドを利用して対応するチェックボックス（\ ``<input type="checkbox">``\ ）のIDを取得している。

        通常、\ ``#ids.prev``\ メソッドは直前に\ ``#ids.seq``\ メソッドを使用して生成されたIDを取得するために利用するが、チェックボックスに\ ``th:field``\ 属性を付与した場合は内部的に\ ``#ids.seq``\ メソッドと同等の処理を実行してIDを生成するため、\ ``#ids.prev``\ メソッドを利用してIDを取得することが可能である。
        
        \ ``#ids``\ の詳細については、\ :url_thymeleaf_tutorial:`Tutorial: Using Thymeleaf -IDs- </usingthymeleaf.html#ids>`\ を参照されたい。

|

.. _ValidationGroupValidation:

バリデーションのグループ化
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

バリデーショングループを作成し、一つのフィールドに対して、グループごとに入力チェックルールを指定することができる。

前述の「新規ユーザー登録」の例で、\ ``age``\ フィールドに「成年であること」というルールを追加する。「成年かどうか」は国によってルールが違うため、\ ``country``\ フィールドも追加する。

Bean Validationでグループを指定する場合、アノテーションの\ ``group``\ 属性に、グループを示す任意の\ ``java.lang.Class``\ オブジェクトを設定する。

ここでは、以下の3グループ(interface)を作成する。

.. tabularcolumns:: |p{0.50\linewidth}|p{0.50\linewidth}|
.. list-table::
  :header-rows: 1
  :widths: 50 50

  * - グループ
    - 成人条件
  * - \ ``Chinese``\
    - 18歳以上
  * - \ ``Japanese``\
    - 20歳以上
  * - \ ``Singaporean``\
    - 21歳以上

このグループを使ってバリデーションを実行する例を示す。

* フォームクラス

  .. code-block:: java

    package com.example.sample.app.validation;

    import java.io.Serializable;
    import java.util.List;

    import jakarta.validation.Valid;
    import jakarta.validation.constraints.Email;
    import jakarta.validation.constraints.Max;
    import jakarta.validation.constraints.Min;
    import jakarta.validation.constraints.NotNull;
    import jakarta.validation.constraints.Size;

    public class UserForm implements Serializable {

        private static final long serialVersionUID = 1L;

        // (1)
        public static interface Chinese {
        };

        public static interface Japanese {
        };

        public static interface Singaporean {
        };

        @NotNull
        @Size(min = 1, max = 20)
        private String name;

        @NotNull
        @Size(min = 1, max = 50)
        @Email
        private String email;

        @NotNull
        @Min(value = 18, groups = Chinese.class) // (2)
        @Min(value = 20, groups = Japanese.class)
        @Min(value = 21, groups = Singaporean.class)
        @Max(200)
        private Integer age;

        @NotNull
        @Size(min = 2, max = 2)
        private String country; // (3)

        // omitted setter/getter
    }

  .. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
  .. list-table::
    :header-rows: 1
    :widths: 10 90

    * - 項番
      - 説明
    * - | (1)
      - | グループクラスを指定するために、各グループをインタフェースで定義する。
    * - | (2)
      - | グループごとにルールを定義する。グループを指定するために、\ ``groups``\ 属性に対象のグループクラスを指定する。
        | \ ``groups``\ 属性を省略した場合、\ ``jakarta.validation.groups.Default``\ グループが使用される。
    * - | (3)
      - | グループを振り分けるための、フィールドを追加する。

|

* View

  .. tabs::
    .. group-tab:: JSP

      JSPに大きな変更はない。
    
      .. code-block:: jsp
    
        <form:form modelAttribute="userForm" method="post"
            class="form-horizontal"
            action="${pageContext.request.contextPath}/user/create">
            <form:label path="name" cssErrorClass="error-label">Name:</form:label>
            <form:input path="name" cssErrorClass="error-input" />
            <form:errors path="name" cssClass="error-messages" />
            <br>
            <form:label path="email" cssErrorClass="error-label">Email:</form:label>
            <form:input path="email" cssErrorClass="error-input" />
            <form:errors path="email" cssClass="error-messages" />
            <br>
            <form:label path="age" cssErrorClass="error-label">Age:</form:label>
            <form:input path="age" cssErrorClass="error-input" />
            <form:errors path="age" cssClass="error-messages" />
            <br>
            <form:label path="country" cssErrorClass="error-label">Country:</form:label>
            <form:select path="country" cssErrorClass="error-input">
                <form:option value="cn">China</form:option>
                <form:option value="jp">Japan</form:option>
                <form:option value="sg">Singapore</form:option>
            </form:select>
            <form:errors path="country" cssClass="error-messages" />
            <br>
            <form:button name="confirm">Confirm</form:button>
        </form:form>

    .. group-tab:: Thymeleaf

      テンプレートHTMLに大きな変更はない。
    
      .. code-block:: html
    
          <form th:object="${userForm}" method="post"
              class="form-horizontal" th:action="@{/user/create}">
              <label for="name" name="name" th:errorclass="error-label">Name:</label>
              <input type="text" th:field="*{name}" th:errorclass="error-input">
              <span id="name-errors" th:errors="*{name}" class="error-messages"></span>
              <br>
              <label for="email" name="email" th:errorclass="error-label">Email:</label>
              <input type="text" th:field="*{email}" th:errorclass="error-input">
              <span id="email-errors" th:errors="*{email}" class="error-messages"></span>
              <br>
              <label for="age" name="age" th:errorclass="error-label">Age:</label>
              <input type="text" th:field="*{age}" th:errorclass="error-input">
              <span id="age-errors" th:errors="*{age}" class="error-messages"></span>
              <br>
              <label for="country" name="country" th:errorclass="error-label">Country:</label>
              <select th:field="*{country}" th:errorclass="error-input">
                  <option value="cn">China</option>
                  <option value="jp">Japan</option>
                  <option value="sg">Singapore</option>
              </select>
              <span id="country-errors" th:errors="*{country}" class="error-messages"></span>
              <br>
              <button id="confirm" name="confirm" type="submit" value="Submit">Confirm</button>
          </form>

|

* Controllerクラス

  \ ``@Validated``\ に、対象のグループを設定することで、バリデーションルールを変更できる。

  .. code-block:: java

    package com.example.sample.app.validation;

    import jakarta.validation.groups.Default;

    import org.springframework.stereotype.Controller;
    import org.springframework.validation.BindingResult;
    import org.springframework.validation.annotation.Validated;
    import org.springframework.web.bind.annotation.GetMapping;
    import org.springframework.web.bind.annotation.ModelAttribute;
    import org.springframework.web.bind.annotation.PostMapping;
    import org.springframework.web.bind.annotation.RequestMapping;

    import com.example.sample.app.validation.UserForm.Chinese;
    import com.example.sample.app.validation.UserForm.Japanese;
    import com.example.sample.app.validation.UserForm.Singaporean;

    @Controller
    @RequestMapping("user")
    public class UserController {

        @ModelAttribute
        public UserForm setupForm() {
            UserForm form = new UserForm();
            return form;
        }

        @GetMapping(value = "create", params = "form")
        public String createForm() {
            return "user/createForm";
        }

        String createConfirm(UserForm form, BindingResult result) {
            if (result.hasErrors()) {
                return "user/createForm";
            }
            return "user/createConfirm";
        }

        @PostMapping(value = "create", params = { "confirm", "country=cn" }) // (1)
        public String createConfirmForChinese(@Validated({Chinese.class, Default.class }) // (2)
                UserForm form, BindingResult result) {
            return createConfirm(form, result);
        }

        @PostMapping(value = "create", params = { "confirm", "country=jp" })
        public String createConfirmForJapanese(@Validated({ Japanese.class,
                Default.class }) UserForm form, BindingResult result) {
            return createConfirm(form, result);
        }

        @PostMapping(value = "create", params = { "confirm", "country=sg" })
        public String createConfirmForSingaporean(@Validated({ Singaporean.class,
                Default.class }) UserForm form, BindingResult result) {
            return createConfirm(form, result);
        }
    }

  .. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
  .. list-table::
    :header-rows: 1
    :widths: 10 90

    * - 項番
      - 説明
    * - | (1)
      - | グループを振り分けるためのパラメータの条件を、\ ``param``\ 属性に追加する。
    * - | (2)
      - | \ ``@Min``\ 以外のアノテーションは、\ ``Default``\ グループに属しているため、\ ``Default``\ の指定も必要である。

この例では、各入力値の組み合わせに対するチェック結果は、以下の表の通りである。

.. tabularcolumns:: |p{0.20\linewidth}|p{0.20\linewidth}|p{0.20\linewidth}|p{0.40\linewidth}|
.. list-table::
  :header-rows: 1
  :widths: 20 20 20 40

  * - \ ``age``\ の値
    - \ ``country``\ の値
    - 入力チェック結果
    - エラーメッセージ
  * - | 17
    - | cn
    - | NG
    - | must be greater than or equal to 18
  * - |
    - | jp
    - | NG
    - | must be greater than or equal to 20
  * - |
    - | sg
    - | NG
    - | must be greater than or equal to 21
  * - | 18
    - | cn
    - | OK
    - |
  * - |
    - | jp
    - | NG
    - | must be greater than or equal to 20
  * - |
    - | sg
    - | NG
    - | must be greater than or equal to 21
  * - | 20
    - | cn
    - | OK
    - |
  * - |
    - | jp
    - | OK
    - |
  * - |
    - | sg
    - | NG
    - | must be greater than or equal to 21
  * - | 21
    - | cn
    - | OK
    - |
  * - |
    - | jp
    - | OK
    - |
  * - |
    - | sg
    - | OK
    - |

.. warning::

  このControllerの実装は、\ ``country``\ の値が、"cn"、"jp"、"sg"のいずれでもない場合のハンドリングが行われておらず、不十分である。\ ``country``\ の値が、想定外の場合に、400エラーが返却される。

次にチェック対象の国が増えたため、成人条件18歳以上をデフォルトルールとしたい場合を考える。

ルールは、以下のようになる。

.. tabularcolumns:: |p{0.50\linewidth}|p{0.50\linewidth}|
.. list-table::
  :header-rows: 1
  :widths: 50 50

  * - グループ
    - 成人条件
  * - \ ``Japanese``\
    - 20歳以上
  * - \ ``Singaporean``\
    - 21歳以上
  * - 上記以外の国(\ ``Default``\ )
    - 18歳以上

* フォームクラス

  \ ``Default``\ グループに意味を持たせるため、\ ``@Min``\ 以外のアノテーションにも、明示的に全グループを指定する必要がある。

  .. code-block:: java

    package com.example.sample.app.validation;

    import java.io.Serializable;
    import java.util.List;

    import jakarta.validation.Valid;
    import jakarta.validation.constraints.Email;
    import jakarta.validation.constraints.Max;
    import jakarta.validation.constraints.Min;
    import jakarta.validation.constraints.NotNull;
    import jakarta.validation.constraints.Size;
    import jakarta.validation.groups.Default;

    public class UserForm implements Serializable {

        private static final long serialVersionUID = 1L;

        public static interface Japanese {
        };

        public static interface Singaporean {
        };

        @NotNull(groups = { Default.class, Japanese.class, Singaporean.class }) // (1)
        @Size(min = 1, max = 20, groups = { Default.class, Japanese.class,
                Singaporean.class })
        private String name;

        @NotNull(groups = { Default.class, Japanese.class, Singaporean.class })
        @Size(min = 1, max = 50, groups = { Default.class, Japanese.class,
                Singaporean.class })
        @Email(groups = { Default.class, Japanese.class, Singaporean.class })
        private String email;

        @NotNull(groups = { Default.class, Japanese.class, Singaporean.class })
        @Min(value = 18, groups = Default.class) // (2)
        @Min(value = 20, groups = Japanese.class)
        @Min(value = 21, groups = Singaporean.class)
        @Max(value = 200, groups = { Default.class, Japanese.class, Singaporean.class })
        private Integer age;

        @NotNull(groups = { Default.class, Japanese.class, Singaporean.class })
        @Size(min = 2, max = 2, groups = { Default.class, Japanese.class,
                Singaporean.class })
        private String country;

        // omitted setter/getter
    }

  .. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
  .. list-table::
    :header-rows: 1
    :widths: 10 90

    * - 項番
      - 説明
    * - | (1)
      - | \ ``@Min``\ 以外のアノテーションにも、全グループを設定する。
    * - | (2)
      - | \ ``Default``\ グループに対するルールを設定する。

* View

  JSP/テンプレートHTMLに変更はない

* Controllerクラス

  .. code-block:: java

    package com.example.sample.app.validation;

    import org.springframework.stereotype.Controller;
    import org.springframework.validation.BindingResult;
    import org.springframework.validation.annotation.Validated;
    import org.springframework.web.bind.annotation.GetMapping;
    import org.springframework.web.bind.annotation.ModelAttribute;
    import org.springframework.web.bind.annotation.PostMapping;
    import org.springframework.web.bind.annotation.RequestMapping;

    import com.example.sample.app.validation.UserForm.Japanese;
    import com.example.sample.app.validation.UserForm.Singaporean;

    @Controller
    @RequestMapping("user")
    public class UserController {

        @ModelAttribute
        public UserForm setupForm() {
            UserForm form = new UserForm();
            return form;
        }

        @GetMapping(value = "create", params = "form")
        public String createForm() {
            return "user/createForm";
        }

        String createConfirm(UserForm form, BindingResult result) {
            if (result.hasErrors()) {
                return "user/createForm";
            }
            return "user/createConfirm";
        }

        @PostMapping(value = "create", params = { "confirm" })
        public String createConfirmForDefault(@Validated /* (1) */ UserForm form,
                BindingResult result) {
            return createConfirm(form, result);
        }

        @PostMapping(value = "create", params = { "confirm", "country=jp" })
        public String createConfirmForJapanese(
                @Validated(Japanese.class)  /* (2) */ UserForm form, BindingResult result) {
            return createConfirm(form, result);
        }

        @PostMapping(value = "create", params = { "confirm", "country=sg" })
        public String createConfirmForSingaporean(
                @Validated(Singaporean.class) UserForm form, BindingResult result) {
            return createConfirm(form, result);
        }
    }

  .. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
  .. list-table::
    :header-rows: 1
    :widths: 10 90

    * - 項番
      - 説明
    * - | (1)
      - | \ ``country``\ フィールド指定がない場合に、\ ``Default``\ グループが使用されるように設定する。
    * - | (2)
      - | \ ``country``\ フィールド指定がある場合に、\ ``Default``\ グループが含まれないように設定する。

バリデーショングループを使用する方法について、2パターン説明した。

前者は\ ``Default``\ グループをControllerクラスで使用し、後者は\ ``Default``\ グループをフォームクラスで使用した。

.. tabularcolumns:: |p{0.25\linewidth}|p{0.25\linewidth}|p{0.25\linewidth}|p{0.25\linewidth}|
.. list-table::
  :header-rows: 1
  :widths: 25 25 25 25

  * - パターン
    - メリット
    - デメリット
    - 使用の判断ポイント
  * - \ ``Default``\ グループをControllerクラスで使用
    - グループ化する必要のないルールは、\ ``group``\ 属性を設定する必要がない。
    - グループの全パターンを定義する必要があるので、グループパターンが多いと、定義が困難になる。
    - グループパターンが、数種類の場合に使用すべき(新規作成グループ、更新グループ、削除グループ等)
  * - \ ``Default``\ グループをフォームクラスで使用
    - デフォルトに属さないグループのみ定義すればよいため、パターンが多くても対応できる。
    - グループ化する必要のないルールにも、\ ``group``\ 属性を設定する必要があり、管理が煩雑になる。
    - グループパターンにデフォルト値を設定できる(グループの大多数に共通項がある)場合に使用すべき

| \ **使用の判断ポイントのどちらにも当てはまらない場合は、Bean Validationの使用が不適切であることが考えられる。**\
| 設計を見直したうえで、Spring Validatorの使用または業務ロジックチェックでの実装を検討すること。

.. note::

  これまでの例ではバリデーショングループの切り替えは、リクエストパラメータ等、\ ``@GetMapping``\ や\ ``@PostMapping``\ で指定できるパラメータによって行った。この方法では認証オブジェクトが有する権限情報など、\ ``@GetMapping``\ や\ ``@PostMapping``\ では扱えない情報でグループを切り替えることはできない。

  この場合は、\ ``@Validated``\ アノテーションを使用せず、\ ``org.springframework.validation.SmartValidator``\ を使用し、Controllerのハンドラメソッド内でグループを指定したバリデーションを行えばよい。

    .. code-block:: java

      @Controller
      @RequestMapping("user")
      public class UserController {

          @Inject
          SmartValidator smartValidator; // (1)

          // omitted

          @PostMapping(value = "create", params = "confirm")
          public String createConfirm(/* (2) */ UserForm form, BindingResult result) {
              // (3)
              Class<?> validationGroup = Default.class;
              // logic to determine validation group
              // if (xxx) {
              //     validationGroup = Xxx.class;
              // }
              smartValidator.validate(form, result, validationGroup); // (4)
              if (result.hasErrors()) {
                  return "user/createForm";
              }
              return "user/createConfirm";
          }

      }

    .. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
    .. list-table::
      :header-rows: 1
      :widths: 10 90

      * - 項番
        - 説明
      * - | (1)
        - | \ ``SmartValidator``\ をインジェクションする。\ ``SmartValidator``\ は\ ``<mvc:annotation-driven>``\ の設定が行われていれば使用できるため、別途Bean定義不要である。
      * - | (2)
        - | \ ``@Validated``\ アノテーションは使わない。
      * - | (3)
        - | バリデーショングループを決定する。
          | バリデーショングループを決定するロジックは、Helperクラスに委譲して、Controller内のロジックをシンプルな状態に保つことを推奨する。
      * - | (4)
        - | \ ``SmartValidator``\ の\ ``validate``\ メソッドを使用して、グループを指定したバリデーションを実行する。
          | グループの指定は可変長引数になっており、複数指定できる。

  基本的にはControllerにロジックを書くべきではないため、\ ``@GetMapping``\ や\ ``@PostMapping``\ の属性でルールを切り替えられるのであれば\ ``SmartValidator``\ は使わない方がよい。

|

.. _ValidationCorrelationCheck:

相関項目チェック
--------------------------------------------------------------------------------

複数フィールドにまたがる相関項目チェックには、Spring Validator(\ ``org.springframework.validation.Validator``\ インタフェースを実装した\ ``Validator``\ )、または、Bean Validationを用いる。

それぞれ説明するが、先にそれぞれの特徴と推奨する使い分けを述べる。

.. tabularcolumns:: |p{0.20\linewidth}|p{0.40\linewidth}|p{0.40\linewidth}|
.. list-table::
  :header-rows: 1
  :widths: 20 40 40

  * - 方式
    - 特徴
    - 用途
  * - | Spring Validator
    - | 特定のクラスに対する入力チェックの作成が容易である。
      | Controllerでの利用が不便。
    - | 特定のフォームに依存した業務要件固有の入力チェック実装
  * - | Bean Validation
    - | 入力チェックの作成はSpring Validatorほど容易でない。
      | Controllerでの利用が容易。
    - | 特定のフォームに依存しない、開発プロジェクト共通の入力チェック実装

|

Spring Validatorによる相関項目チェック実装
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

| 「パスワードリセット」処理を例に実装方法を説明する。
| 以下のルールを実装する。ここでは「パスワードリセット」のフォームに以下のチェックルールを設ける。

.. tabularcolumns:: |p{0.20\linewidth}|p{0.30\linewidth}|p{0.30\linewidth}|p{0.20\linewidth}|
.. list-table::
  :header-rows: 1
  :widths: 20 30 30 20

  * - フィールド名
    - 型
    - ルール
    - 説明
  * - | password
    - | \ ``java.lang.String``\
    - | 入力必須
      | 8文字以上
    - | パスワード
  * - | confirmPassword
    - | \ ``java.lang.String``\
    - | \ **passwordが入力されている場合、passwordと同じ値であること**\
    - | 確認用パスワード

「passwordが入力されている場合、passwordと同じ値であること」というルールは\ ``password``\ フィールドと\ ``confirmPassword``\ フィールドの両方の情報が必要であるため、相関項目チェックルールである。

* フォームクラス

  相関項目チェックルール以外は、これまで通りBean Validationのアノテーションで実装する。

  .. code-block:: java

    package com.example.sample.app.validation;

    import java.io.Serializable;

    import jakarta.validation.constraints.NotNull;
    import jakarta.validation.constraints.Size;

    public class PasswordResetForm implements Serializable {
        private static final long serialVersionUID = 1L;

        @NotNull
        @Size(min = 8)
        private String password;

        private String confirmPassword;

        // omitted setter/getter
    }

  .. note::

    パスワードは、通常ハッシュ化してデータベースに保存するため、最大値のチェックは行わなくても良い。

* Validatorクラス

  \ ``org.springframework.validation.Validator``\ インタフェースを実装して、相関項目チェックルールを実現する。

  .. code-block:: java

    package com.example.sample.app.validation;

    import java.util.Objects;

    import org.springframework.stereotype.Component;
    import org.springframework.util.StringUtils;
    import org.springframework.validation.Errors;
    import org.springframework.validation.Validator;

    @Component // (1)
    public class PasswordEqualsValidator implements Validator {

        @Override
        public boolean supports(Class<?> clazz) {
            return PasswordResetForm.class.isAssignableFrom(clazz); // (2)
        }

        @Override
        public void validate(Object target, Errors errors) {

            PasswordResetForm form = (PasswordResetForm) target;
            String password = form.getPassword();
            String confirmPassword = form.getConfirmPassword();

            if (!StringUtils.hasLength(password)) { // (3)
                return;
            }

            if (!Objects.equals(password, confirmPassword)) { // (4)
                errors.rejectValue(/* (5) */ "confirmPassword",
                /* (6) */ "PasswordEqualsValidator.passwordResetForm.password",
                /* (7) */ "password and confirm password must be same.");
            }
        }
    }

  .. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
  .. list-table::
    :header-rows: 1
    :widths: 10 90

    * - 項番
      - 説明
    * - | (1)
      - | \ ``@Component``\ を付与し、Validatorをコンポーネントスキャン対象にする。
    * - | (2)
      - | このValidatorのチェック対象であるかどうかを判別する。ここでは、\ ``PasswordResetForm``\ クラスをチェック対象とする。
    * - | (3)
      - | \ ``password``\ フィールドが未入力の場合は、このValidatorで相関チェックは行わない。
        | 相関チェックを必ず行う必要がある場合は、この判定ロジックは不要である。
    * - | (4)
      - | チェックロジックを実装する。
    * - | (5)
      - | エラー対象のフィールド名を指定する。
    * - | (6)
      - | エラーメッセージのコード名を指定する。ここではコードを、
        | "バリデータ名.フォーム属性名.プロパティ名"
        | とする。メッセージ定義は\ :ref:`ValidationMessageInApplicationMessages`\ を参照されたい。
    * - | (7)
      - | エラーメッセージをコードで解決できなかった場合に使用する、デフォルトメッセージを設定する。

  .. note::

    Spring Validator実装クラスは、使用するControllerと同じパッケージに配置することを推奨する。

* Controllerクラス

  .. code-block:: java

    package com.example.sample.app.validation;

    import org.springframework.validation.BindingResult;
    import org.springframework.validation.annotation.Validated;
    import org.springframework.web.bind.WebDataBinder;
    import org.springframework.web.bind.annotation.GetMapping;
    import org.springframework.web.bind.annotation.InitBinder;
    import org.springframework.web.bind.annotation.ModelAttribute;
    import org.springframework.web.bind.annotation.PostMapping;
    import org.springframework.web.bind.annotation.RequestMapping;

    import jakarta.inject.Inject;

    @Controller
    @RequestMapping("password")
    public class PasswordResetController {
        @Inject
        PasswordEqualsValidator passwordEqualsValidator; // (1)

        @ModelAttribute
        public PasswordResetForm setupForm() {
            return new PasswordResetForm();
        }

        @InitBinder
        public void initBinder(WebDataBinder binder) {
            binder.addValidators(passwordEqualsValidator); // (2)
        }

        @GetMapping(value = "reset", params = "form")
        public String resetForm() {
            return "password/resetForm";
        }

        @PostMapping(value = "reset")
        public String reset(@Validated PasswordResetForm form, BindingResult result) { // (3)
            if (result.hasErrors()) {
                return "password/resetForm";
            }
            return "redirect:/password/reset?complete";
        }

        @GetMapping(value = "reset", params = "complete")
        public String resetComplete() {
            return "password/resetComplete";
        }
    }

  .. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
  .. list-table::
    :header-rows: 1
    :widths: 10 90

    * - 項番
      - 説明
    * - | (1)
      - | 使用するSpring Validatorを、インジェクションする。
    * - | (2)
      - | \ ``@InitBinder``\ アノテーションがついたメソッド内で、\ ``WebDataBinder.addValidators``\ メソッドにより、Validatorを追加する。
        | これにより、\ ``@Validated``\ アノテーションでバリデーションをする際に、追加したValidatorも呼び出される。
    * - | (3)
      - | 入力チェックの実装は、これまで通りである。

* View

  .. tabs::
    .. group-tab:: JSP

      JSPに特筆すべき点はない。
    
      .. code-block:: jsp
    
        <!DOCTYPE html>
        <html>
        <%-- WEB-INF/views/password/resetForm.jsp --%>
        <head>
        <style type="text/css">
        /* omitted */
        </style>
        </head>
        <body>
            <form:form modelAttribute="passwordResetForm" method="post"
                class="form-horizontal"
                action="${pageContext.request.contextPath}/password/reset">
                <form:label path="password" cssErrorClass="error-label">Password:</form:label>
                <form:password path="password" cssErrorClass="error-input" />
                <form:errors path="password" cssClass="error-messages" />
                <br>
                <form:label path="confirmPassword" cssErrorClass="error-label">Password (Confirm):</form:label>
                <form:password path="confirmPassword"
                    cssErrorClass="error-input" />
                <form:errors path="confirmPassword" cssClass="error-messages" />
                <br>
                <form:button>Reset</form:button>
            </form:form>
        </body>
        </html>

      \ ``password``\ フィールドと、\ ``confirmPassword``\ フィールドに、別の値を入力してフォームを送信した場合は、以下のようにエラーメッセージが表示される。
      
      .. figure:: ./images_Validation/validations-correlation-check1.png
        :width: 60%
      
      .. note::
      
        \ ``<form:password>``\ タグを使用すると、再表示時に、データがクリアされる。

    .. group-tab:: Thymeleaf

      テンプレートHTMLに特筆すべき点はない。
    
      .. code-block:: html
    
        <!DOCTYPE html>
        <html xmlns:th="http://www.thymeleaf.org">
        <!--/* WEB-INF/views/password/resetForm.html */-->
        <head>
        <style type="text/css">
        /* omitted */
        </style>
        </head>
        <body>
            <form th:object="${passwordResetForm}" method="post"
                class="form-horizontal" th:action="@{/password/reset}">
                <label for="password" name="password" th:errorclass="error-label">Password:</label>
                <input type="password" th:field="*{password}" th:errorclass="error-input">
                <span id="password-errors" th:errors="*{password}"
                    class="error-messages"></span>
                <br>
                <label for="confirmPassword" name="confirmPassword" th:errorclass="error-label">Password (Confirm):</label>
                <input type="password" th:field="*{confirmPassword}"
                    th:errorclass="error-input">
                <span id="confirmPassword-errors" th:errors="*{confirmPassword}"
                    class="error-messages"></span>
                <br>
                <button type="submit" value="Submit">Reset</button>
            </form>
        </body>
        </html>

      \ ``password``\ フィールドと、\ ``confirmPassword``\ フィールドに、別の値を入力してフォームを送信した場合は、以下のようにエラーメッセージが表示される。
      
      .. figure:: ./images_Validation/validations-correlation-check1.png
        :width: 60%
      
      .. note::
      
        パスワード入力フィールド（\ ``<input type="password">``\ ）に\ ``th:field``\ 属性を付与すると、再表示時に、データがクリアされる。

.. _ValidationHowToCrossFieldValidationForMultiFieldHighlight:

.. note::

  相関チェック対象の複数フィールドに対してエラー情報を設定することも可能である。ただし、必ずエラーメッセージの表示とスタイル適用がセットで行われ、いずれか片方のみを行うことはできない。

  相関チェックエラーとなった両方のフィールドにスタイル適用したいが、エラーメッセージは1つだけ表示したいような場合は、エラーメッセージに空文字を設定することで実現することが可能である。

  以下に、\ ``password``\ フィールドと\ ``confirmPassword``\ フィールドにスタイルを適用し、\ ``confirmPassword``\ フィールドのみにエラーメッセージを表示する例を示す。

    .. code-block:: java

      package com.example.sample.app.validation;

      import java.util.Objects;

      import org.springframework.stereotype.Component;
      import org.springframework.util.StringUtils;
      import org.springframework.validation.Errors;
      import org.springframework.validation.Validator;

      @Component
      public class PasswordEqualsValidator implements Validator {

          @Override
          public boolean supports(Class<?> clazz) {
              return PasswordResetForm.class.isAssignableFrom(clazz);
          }

          @Override
          public void validate(Object target, Errors errors) {

              // omitted
              if (!Objects.equals(password, confirmPassword)) {
                  // register a field error for confirmPassword
                  errors.rejectValue("confirmPassword",
                            "PasswordEqualsValidator.passwordResetForm.confirmPassword",
                            "password and confirm password must be same.");

                  // register a field error for password
                  errors.rejectValue("password", // (1)
                         "PasswordEqualsValidator.passwordResetForm.password", // (2)
                         ""); // (3)
              }
          }
      }

    .. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
    .. list-table::
      :header-rows: 1
      :widths: 10 90
      :class: longtable

      * - 項番
        - 説明
      * - | (1)
        - | \ ``password``\ フィールドのエラーを登録する。
      * - | (2)
        - | エラーメッセージのコード名を指定する。この際、対応するエラーメッセージに空文字を指定する。
          | メッセージ定義は\ :ref:`ValidationMessageInApplicationMessages`\ を参照されたい。
      * - | (3)
        - | エラーメッセージをコードで解決できなかった場合に使用する、デフォルトメッセージを設定する。
          | 上記の例では空文字を設定している。

.. warning::

  \ ``@InitBinder``\ アノテーションを付与したメソッドでValidatorが登録されると、Validatorの \ ``supports``\ メソッドでValidatorのサポート対象の型かどうか判定される。このとき、サポート対象でない場合は\ ``java.lang.IllegalStateException``\ が発生する点に注意されたい。
    
  \ ``@InitBinder``\ アノテーションを付与したメソッドは、Modelに独自の型のオブジェクトが追加された際に必ず実行されるが、 \ ``@InitBinder("xxx")``\ でモデル名を指定することで、適用範囲を限定することが可能である。
    
  例えば以下のようなケースが該当するため、注意されたい。
    
  * 一つのControllerで複数のフォームを扱う場合（複数のフォームオブジェクトを \ ``@ModelAttribute``\ アノテーションを付与したメソッドで登録する場合や、ハンドラメソッドの引数として受け取る場合）
  * フォームオブジェクトに限らず、ハンドラメソッドの引数として受け取った\ ``Model``\ に、\ ``ResultMessages``\ オブジェクトや\ ``Page``\ オブジェクトなどの独自の型のオブジェクトを登録する場合
  * 同様に\ ``RedirectAttributes``\ に独自の型のオブジェクトを登録する場合
    
  以下に、一つのControllerで複数のフォームを扱う場合の実装例を示す。

    .. code-block:: java

      @Controller
      @RequestMapping("xxx")
      public class XxxController {
          // omitted
          @ModelAttribute("aaa")
          public AaaForm() {
              return new AaaForm();
          }

          @ModelAttribute("bbb")
          public BbbForm() {
              return new BbbForm();
          }

          @InitBinder("aaa")
          public void initBinderForAaa(WebDataBinder binder) {
              // add validators for AaaForm
              binder.addValidators(aaaValidator);
          }

          @InitBinder("bbb")
          public void initBinderForBbb(WebDataBinder binder) {
              // add validators for BbbForm
              binder.addValidators(bbbValidator);
          }
          // omitted
      }

.. note::

  相関項目チェックルールのチェック内容をバリデーショングループに応じて変更したい場合（例えば、特定のバリデーショングループが指定された場合だけ相関項目チェックを実施したい場合など）は、 \ ``org.springframework.validation.Validator``\ インターフェイスを実装する代わりに、 \ ``org.springframework.validation.SmartValidator``\ インターフェイスを実装し、validateメソッド内で処理を切り替えるとよい。

    .. code-block:: java

      package com.example.sample.app.validation;

      import org.apache.commons.lang3.ArrayUtils;
      import org.springframework.stereotype.Component;
      import org.springframework.validation.Errors;
      import org.springframework.validation.SmartValidator;

      @Component
      public class PasswordEqualsValidator implements SmartValidator { // Implements SmartValidator instead of Validator interface

          @Override
          public boolean supports(Class<?> clazz) {
              return PasswordResetForm.class.isAssignableFrom(clazz);
          }

          @Override
          public void validate(Object target, Errors errors) {
              validate(target, errors, new Object[] {});
          }

          @Override
          public void validate(Object target, Errors errors, Object... validationHints) {
              // Check validationHints(groups) and apply validation logic only when 'Update.class' is specified
              if (ArrayUtils.contains(validationHints, Update.class)) {
                  PasswordResetForm form = (PasswordResetForm) target;
                  String password = form.getPassword();
                  String confirmPassword = form.getConfirmPassword();

                  // omitted...
              }
          }
      }

|

Bean Validationによる相関項目チェック実装
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Bean Validationによって、相関項目チェックの実装するためには、独自バリデーションルールの追加を行う必要がある。

\ :ref:`ValidationCustomConstraint`\ にて説明する。

|

.. _ValidationMessageDef:

エラーメッセージの定義
--------------------------------------------------------------------------------

入力チェックエラーメッセージを変更する方法を説明する。

Spring MVCによるBean Validationのエラーメッセージは、以下の順で解決される。

#. | \ ``org.springframework.context.MessageSource``\ に定義されているメッセージの中に、ルールに合致するものがあればそれをエラーメッセージとして使用する (Springのルール)。
   | Springのデフォルトのルールについては、「\ :url_spring_javadoc:`DefaultMessageCodesResolverのJavaDoc </org/springframework/validation/DefaultMessageCodesResolver.html>`\ 」を参照されたい。
#. 1.でメッセージが見つからない場合、アノテーションの\ ``message``\ 属性に、指定されたメッセージからエラーメッセージを取得する (Bean Validationのルール)

  #. \ ``message``\ 属性に指定されたメッセージが、"{メッセージキー}"形式でない場合、そのテキストをエラーメッセージとして使用する。
  #. \ ``message``\ 属性に指定されたメッセージが、"{メッセージキー}"形式の場合、クラスパス直下のValidationMessages.propertiesから、メッセージキーに対応するメッセージを探す。

  #. メッセージキーに対応するメッセージが定義されている場合は、そのメッセージを使用する
  #. メッセージキーに対応するメッセージが定義されていない場合は、"{メッセージキー}"をそのままエラーメッセージとして使用する

基本的にエラーメッセージは、propertiesファイルに定義することを推奨する。

定義する箇所は、以下の2パターン存在する。

* \ ``org.springframework.context.MessageSource``\ が読み込むpropertiesファイル
* \ クラスパス直下のValidationMessages.properties

以下の説明では、ApplicationContext設定ファイルに次の設定があることを前提とし、前者を"application-messages.properties"、後者を"ValidationMessages.properties"と呼ぶ。

.. tabs::
  .. group-tab:: Java Config

    .. code-block:: java

      @Bean("messageSource")
      public MessageSource messageSource() {
          ResourceBundleMessageSource bean = new ResourceBundleMessageSource();
          bean.setBasenames("i18n/application-messages");
          return bean;
      }

  .. group-tab:: XML Config

    .. code-block:: xml

      <bean id="messageSource"
          class="org.springframework.context.support.ResourceBundleMessageSource">
          <property name="basenames">
              <list>
                  <value>i18n/application-messages</value>
              </list>
          </property>
      </bean>

.. figure:: ./images_Validation/validations-message-properties-position-image.png
  :width: 40%

.. warning::

  \ ``ValidationMessages.properties``\ ファイルは、クラスパスの直下に複数存在させてはいけない。

  クラスパスの直下に複数の\ ``ValidationMessages.properties``\ ファイルが存在する場合、いずれか１つのファイルが読み込まれ、他のファイルが読み込まれないため、適切なメッセージが表示されない可能性がある。

  * マルチプロジェクト構成を採用する場合は、\ ``ValidationMessages.properties``\ ファイルを複数のプロジェクトに配置しないように注意すること。
  * Bean Validation用の共通部品をjarファイルとして配布する際に、\ ``ValidationMessages.properties``\ ファイルをjarファイルの中に含めないように注意すること。

  \ :url_multi_blank:`ブランクプロジェクト <>`\ からプロジェクトを生成した場合は、\ ``xxx-web/src/main/resources``\ の直下に\ ``ValidationMessages.properties``\ が格納されている。

|

本ガイドラインでは、以下のように定義を分けることを推奨する。

.. tabularcolumns:: |p{0.50\linewidth}|p{0.50\linewidth}|
.. list-table::
  :header-rows: 1
  :widths: 50 50

  * - プロパティファイル名
    - 定義する内容
  * - | ValidationMessages.properties
    - | システムで定めたBean Validationのデフォルトエラーメッセージ
  * - | application-messages.properties
    - | 個別で上書きしたいBean Validationのエラーメッセージ
      | Spring Validatorで実装した入力チェックのエラーメッセージ

ValidationMessages.propertiesを用意しない場合は、\ :ref:`Hibernate Validatorが用意するデフォルトメッセージ <ValidationDefaultMessageInHibernateValidator>`\ が使用される。

\ ``MessageSource``\ と連携することで、日本語メッセージをNative to Asciiせずに直接扱うことができる。詳細は、\ :ref:`ValidationWithoutNative2Ascii`\ を参照されたい。

|

.. _ValidationMessageInValidationMessages:

ValidationMessages.propertiesに定義するメッセージ
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

クラスパス直下(通常src/main/resources)のValidationMessages.properties内の、Bean Validationのアノテーションの\ ``message``\ 属性に指定されたメッセージキーに対して、メッセージを定義する。

\ :ref:`ValidationBasicValidation`\ の初めに使用した、以下のフォームを用いて説明する。

* フォームクラス(再掲)

  .. code-block:: java

    public class UserForm implements Serializable {

        @NotNull
        @Size(min = 1, max = 20)
        private String name;

        @NotNull
        @Size(min = 1, max = 50)
        @Email
        private String email;

        @NotNull
        @Min(0)
        @Max(200)
        private Integer age;

        // omitted getter/setter
    }

* ValidationMessages.properties

  \ ``@NotNull``\ , \ ``@Size``\ , \ ``@Min``\ , \ ``@Max``\ , \ ``@Email``\ のエラーメッセージを変更する。

  .. code-block:: properties

    jakarta.validation.constraints.NotNull.message=is required.
    # (1)
    jakarta.validation.constraints.Size.message=size is not in the range {min} through {max}.
    jakarta.validation.constraints.Min.message=can not be less than {value}.
    jakarta.validation.constraints.Max.message=can not be greater than {value}.
    jakarta.validation.constraints.Email.message=is an invalid e-mail address.

  .. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
  .. list-table::
    :header-rows: 1
    :widths: 10 90

    * - 項番
      - 説明
    * - | (1)
      - | アノテーションに指定した属性値は、\ ``{属性名}``\ で埋め込むことができる。

この設定を加えた状態で、すべての入力フィールドを未入力のままフォームを送信すると、以下のように変更したエラーメッセージが、表示される。

.. figure:: ./images_Validation/validations-customize-message1.png
  :width: 60%

.. warning::

  Bean Validation標準のアノテーションやHibernate Validator独自のアノテーションには\ ``message``\ 属性に\ ``{アノテーションのFQCN.message}``\ という値が設定されているため、

    .. code-block:: properties

      アノテーションのFQCN.message=メッセージ

  という形式でプロパティファイルにメッセージを定義すればよいが、すべてのアノテーションが、この形式になっているわけではないので、
  対象のアノテーションのJavadocまたはソースコードを確認すること。


エラーメッセージに、フィールド名を含める場合は、以下のように、メッセージに\ ``{0}``\ を加える。

* ValidationMessages.properties

  \ ``@NotNull``\ 、\ ``@Size``\ 、\ ``@Min``\ 、\ ``@Max``\ 、\ ``@Email``\ のエラーメッセージを変更する。

  .. code-block:: properties

    jakarta.validation.constraints.NotNull.message="{0}" is required.
    jakarta.validation.constraints.Size.message=The size of "{0}" is not in the range {min} through {max}.
    jakarta.validation.constraints.Min.message="{0}" can not be less than {value}.
    jakarta.validation.constraints.Max.message="{0}" can not be greater than {value}.
    jakarta.validation.constraints.Email.message="{0}" is an invalid e-mail address.

エラーメッセージは、以下のように変更される。

.. figure:: ./images_Validation/validations-customize-message2.png
  :width: 60%

このままでは、フォームクラスのプロパティ名が表示されてしまい、ユーザーフレンドリではない。適切なフィールド名を表示したい場合は、\ **application-messages.propertiesに**\

.. code-block:: properties

  フォームのプロパティ名=表示するフィールド名

形式でフィールド名を定義すればよい。

これまでの例に、以下の設定を追加する。

* application-messages.properties

  .. code-block:: properties

    name=Name
    email=Email
    age=Age

エラーメッセージは、以下のように変更される。

.. figure:: ./images_Validation/validations-customize-message3.png
  :width: 60%

.. note::

  \ ``{0}``\ でフィールド名を埋め込めるのは、Bean Validationの機能ではなく、Springの機能である。したがって、フィールド名変更の設定は、Spring管理下のapplication-messages.properties(\ ``ResourceBundleMessageSource``\ )に定義する必要がある。

.. tip::

  Bean Validation 1.1より、\ :file:`ValidationMessages.properties`\ に指定するメッセージの中にExpression Language(以降、「EL式」と呼ぶ)を使用する事ができるようになった。Hibernate Validator 8.xでは、Expression Language 5.0以上をサポートしている。

  実行可能なEL式のバージョンは、アプリケーションサーバのバージョンによって異なる。そのため、EL式を使用する場合は、\ **アプリケーションサーバがサポートしているEL式のバージョンを確認した上で使用すること。**\

  以下に、Hibernate Validatorがデフォルトで用意している\ :file:`ValidationMessages.properties`\ に定義されているメッセージを例に、EL式の使用例を示す。

    .. code-block:: properties

      # ...
      # (1)
      jakarta.validation.constraints.DecimalMax.message  = must be less than ${inclusive == true ? 'or equal to ' : ''}{value}
      # ...

    .. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
    .. list-table::
      :header-rows: 1
      :widths: 10 90

      * - 項番
        - 説明
      * - | (1)
        - メッセージの中の 「\ ``${inclusive == true ? 'or equal to ' : ''}``\ 」の部分がEL式である。

          上記のメッセージ定義から実際に生成されるメッセージのパターンは、

          * must be less than or equal to {value}
          * must be less than {value}

          の2パターンとなる。(\ ``{value}``\ の部分には、\ ``@DecimalMax``\ アノテーションの \ ``value``\ 属性に指定した値が埋め込まれる)

          前者は\ ``@DecimalMax``\ アノテーションの \ ``inclusive``\ 属性に \ ``true``\ を指定した場合(又は指定しなかった場合)、
          後者は\ ``@DecimalMax``\ アノテーションの \ ``inclusive``\ 属性に \ ``false``\ を指定した場合に生成される。

          Bean ValidationにおけるEL式の扱いについては、\ :url_hibernate_validator:`Hibernate Validator Reference Guide(Interpolation with message expressions) </reference/en-US/html_single/#section-interpolation-with-message-expressions>`\ を参照されたい。

  また、\ :file:`ValidationMessages.properties`\ に指定するメッセージに \ ``${validatedValue}``\ を使用することで、エラーメッセージにチェック対象の値を含むことができる。

  以下に、 \ ``${validatedValue}``\ の使用例を示す。

    .. code-block:: properties

      # ...
      # (1)
      jakarta.validation.constraints.Pattern.message = The value entered "${validatedValue}" is invalid.
      # ...


    .. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
    .. list-table::
      :header-rows: 1
      :widths: 10 90
      :class: longtable

      * - 項番
        - 説明
      * - | (1)
        - | 上記のメッセージ定義から実際に生成されるメッセージは、 \ ``${validatedValue}``\ の部分にフォームに入力した値が埋め込まれる。
          | 入力値に機密情報を含む場合、機密情報がメッセージに表示されないようにするため、 \ ``${validatedValue}``\ を使用しないように注意すること。
          |
          | 詳細については、\ :url_hibernate_validator:`Hibernate Validator Reference Guide(Interpolation with message expressions) </reference/en-US/html_single/#section-interpolation-with-message-expressions>`\ を参照されたい。

|

.. _ValidationMessageInApplicationMessages:

application-messages.propertiesに定義するメッセージ
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

ValidationMessages.propertiesでシステムが利用するデフォルトのメッセージを定義したが、画面によっては、デフォルトメッセージから変更したい場合が出てくる。

その場合、application-messages.propertiesに、以下の形式でメッセージを定義する。

.. code-block:: properties

  アノテーション名.フォーム属性名.プロパティ名=対象のメッセージ

\ :ref:`ValidationMessageInValidationMessages`\ の設定がある前提で、以下の設定で\ ``email``\ と\ ``age``\ フィールドのメッセージを上書きする。

* application-messages.properties

  .. code-block:: properties

    # override messages
    # for email field
    Size.userForm.email=The size of "{0}" must be between {2} and {1}.
    # for age field
    NotNull.userForm.age="{0}" is compulsory.
    Min.userForm.age="{0}" must be greater than or equal to {1}.
    Max.userForm.age="{0}" must be less than or equal to {1}.

    # filed names
    name=Name
    email=Email
    age=Age

アノテーションの属性値は、\ ``{1}``\ 以降に埋め込まれる。なお、属性値のインデックス位置は、アノテーションの属性名のアルファベット順(昇順)となる。

例えば、\ ``@Size``\ のインデックス位置は、

* \ ``{0}``\  : プロパティ名 (物理名又は論理名)
* \ ``{1}``\  : \ ``max``\ 属性の値
* \ ``{2}``\  : \ ``min``\ 属性の値

| となる。
| 仕様の詳細については\ :url_spring_javadoc:`SpringValidatorAdapterのJavaDoc </org/springframework/validation/beanvalidation/SpringValidatorAdapter.html#getArgumentsForConstraint(java.lang.String,java.lang.String,jakarta.validation.metadata.ConstraintDescriptor)>`\ を参照されたい。

エラーメッセージは以下のように変更される。

.. figure:: ./images_Validation/validations-customize-message4.png
  :width: 60%

.. note::

  application-messages.propertiesのメッセージキーの形式は\ :url_spring_javadoc:`これ以外にも用意されている </org/springframework/validation/DefaultMessageCodesResolver.html>`\ が、デフォルトメッセージを一部上書きする目的で使用するのであれば、基本的に、\ ``アノテーション名.フォーム属性名.プロパティ名``\ 形式でよい。

|

.. _ValidationCustomConstraint:

How to extend
================================================================================

Bean Validationは標準で用意されているチェックルール以外に、独自ルール用アノテーションを作成する仕組みをもつ。

作成方法は大きく分けて、以下の観点で分かれる。

* 既存ルールの組み合わせ
* 新規ルールの作成

基本的には、以下の雛形を使用して、ルール毎にアノテーションを作成する。

.. code-block:: java

  package com.example.common.validation;

  import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
  import static java.lang.annotation.ElementType.CONSTRUCTOR;
  import static java.lang.annotation.ElementType.FIELD;
  import static java.lang.annotation.ElementType.METHOD;
  import static java.lang.annotation.ElementType.PARAMETER;
  import static java.lang.annotation.ElementType.TYPE_USE;
  import static java.lang.annotation.RetentionPolicy.RUNTIME;

  import java.lang.annotation.Documented;
  import java.lang.annotation.Repeatable;
  import java.lang.annotation.Retention;
  import java.lang.annotation.Target;

  import com.example.common.validation.Xxx.List;

  import jakarta.validation.Constraint;
  import jakarta.validation.Payload;

  @Documented
  @Constraint(validatedBy = {})
  @Target({ METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE })
  @Retention(RUNTIME)
  @Repeatable(List.class)
  public @interface Xxx {
      String message() default "{com.example.common.validation.Xxx.message}";

      Class<?>[] groups() default {};

      Class<? extends Payload>[] payload() default {};

      @Target({ METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE })
      @Retention(RUNTIME)
      @Documented
      @interface List {
          Xxx[] value();
      }
  }

|

.. _ValidationCombineExistingConstraint:

既存ルールを組み合わせたBean Validationアノテーションの作成
--------------------------------------------------------------------------------

システム共通で、

* 文字列は半角英数字の文字種に限定したい
* 数値は8桁までの正の数に限定したい

| または、ドメイン共通で、

* 「ユーザーID」は、4文字以上20文字以下の半角英字に制限したい
* 「年齢」は、1歳以上150歳以下に制限したい

| という制約がある場合を考える。
| これらは既存ルールの\ ``@Pattern``\ 、\ ``@Size``\ 、\ ``@Min``\ 、\ ``@Max``\ 等を組み合わせることでも実現できるが、
| 同じルールを複数の箇所で使用すると、設定内容が分散してしまい、メンテナンス性が悪化する。

| 複数のルールを組み合わせて一つのルールを作成することができる。
| 独自アノテーションを作成すると、正規表現パターンや、最大値・最小値などの値を共通化できるだけでなく、エラーメッセージも共通化できるというメリットがある。
| これにより、再利用性や保守性が高まる。複数のルールの組み合わせではなくても、一つのルールの属性を特定するだけでも効果的である。

以下に、実装例を示す。

* 半角英数字の文字種に限定する\ ``@Alphanumeric``\ アノテーションの実装例

  .. code-block:: java

    package com.example.common.validation;

    import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
    import static java.lang.annotation.ElementType.CONSTRUCTOR;
    import static java.lang.annotation.ElementType.FIELD;
    import static java.lang.annotation.ElementType.METHOD;
    import static java.lang.annotation.ElementType.PARAMETER;
    import static java.lang.annotation.ElementType.TYPE_USE;
    import static java.lang.annotation.RetentionPolicy.RUNTIME;

    import java.lang.annotation.Documented;
    import java.lang.annotation.Repeatable;
    import java.lang.annotation.Retention;
    import java.lang.annotation.Target;

    import com.example.common.validation.AlphaNumeric.List;

    import jakarta.validation.Constraint;
    import jakarta.validation.Payload;
    import jakarta.validation.ReportAsSingleViolation;
    import jakarta.validation.constraints.Pattern;

    @Documented
    @Constraint(validatedBy = {}) // (1)
    @Target({ METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE })
    @Retention(RUNTIME)
    @Repeatable(List.class)
    @ReportAsSingleViolation // (2)
    @Pattern(regexp = "[a-zA-Z0-9]*") // (3)
    public @interface AlphaNumeric {
        String message() default "{com.example.common.validation.AlphaNumeric.message}"; // (4)

        Class<?>[] groups() default {};

        Class<? extends Payload>[] payload() default {};

        @Target({ METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE })
        @Retention(RUNTIME)
        @Documented
        @interface List {
            AlphaNumeric[] value();
        }
    }

  .. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
  .. list-table::
    :header-rows: 1
    :widths: 10 90

    * - 項番
      - 説明
    * - | (1)
      - | 既存のアノテーションを利用して実装を行う場合、\ ``validatedBy``\ は空にしておく必要がある。
    * - | (2)
      - | エラーメッセージをまとめ、エラー時はこのアノテーションによるメッセージだけを変えるようにする。
    * - | (3)
      - | このアノテーションにより使用されるルールを定義する。
    * - | (4)
      - | エラーメッセージのデフォルト値を定義する。

* 8桁までの正の数に限定する\ ``@MaxDigits``\ アノテーションの実装例

  .. code-block:: java

    package com.example.common.validation;

    import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
    import static java.lang.annotation.ElementType.CONSTRUCTOR;
    import static java.lang.annotation.ElementType.FIELD;
    import static java.lang.annotation.ElementType.METHOD;
    import static java.lang.annotation.ElementType.PARAMETER;
    import static java.lang.annotation.ElementType.TYPE_USE;
    import static java.lang.annotation.RetentionPolicy.RUNTIME;

    import java.lang.annotation.Documented;
    import java.lang.annotation.Repeatable;
    import java.lang.annotation.Retention;
    import java.lang.annotation.Target;

    import com.example.common.validation.MaxDigits.List;

    import jakarta.validation.Constraint;
    import jakarta.validation.Payload;
    import jakarta.validation.ReportAsSingleViolation;
    import jakarta.validation.constraints.Max;
    import jakarta.validation.constraints.PositiveOrZero;

    @Documented
    @Constraint(validatedBy = {})
    @Target({ METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE })
    @Retention(RUNTIME)
    @Repeatable(List.class)
    @ReportAsSingleViolation
    @PositiveOrZero
    @Max(value = 99999999)
    public @interface MaxDigits {
        String message() default "{com.example.common.validation.MaxDigits.message}";

        Class<?>[] groups() default {};

        Class<? extends Payload>[] payload() default {};

        @Target({ METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE })
        @Retention(RUNTIME)
        @Documented
        @interface List {
            MaxDigits[] value();
        }
    }

* 「ユーザーID」のフォーマットを規定する\ ``@UserId``\ アノテーションの実装例

  .. code-block:: java

    package com.example.sample.domain.validation;

    import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
    import static java.lang.annotation.ElementType.CONSTRUCTOR;
    import static java.lang.annotation.ElementType.FIELD;
    import static java.lang.annotation.ElementType.METHOD;
    import static java.lang.annotation.ElementType.PARAMETER;
    import static java.lang.annotation.ElementType.TYPE_USE;
    import static java.lang.annotation.RetentionPolicy.RUNTIME;

    import java.lang.annotation.Documented;
    import java.lang.annotation.Repeatable;
    import java.lang.annotation.Retention;
    import java.lang.annotation.Target;

    import com.example.sample.domain.validation.UserId.List;

    import jakarta.validation.Constraint;
    import jakarta.validation.Payload;
    import jakarta.validation.ReportAsSingleViolation;
    import jakarta.validation.constraints.Pattern;
    import jakarta.validation.constraints.Size;

    @Documented
    @Constraint(validatedBy = {})
    @Target({ METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE })
    @Retention(RUNTIME)
    @Repeatable(List.class)
    @ReportAsSingleViolation
    @Size(min = 4, max = 20)
    @Pattern(regexp = "[a-z]*")
    public @interface UserId {
        String message() default "{com.example.sample.domain.validation.UserId.message}";

        Class<?>[] groups() default {};

        Class<? extends Payload>[] payload() default {};

        @Target({ METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE })
        @Retention(RUNTIME)
        @Documented
        @interface List {
            UserId[] value();
        }
    }

* 「年齢」の制限を規定する\ ``@Age``\ アノテーションの実装例

  .. code-block:: java

    package com.example.sample.domain.validation;

    import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
    import static java.lang.annotation.ElementType.CONSTRUCTOR;
    import static java.lang.annotation.ElementType.FIELD;
    import static java.lang.annotation.ElementType.METHOD;
    import static java.lang.annotation.ElementType.PARAMETER;
    import static java.lang.annotation.ElementType.TYPE_USE;
    import static java.lang.annotation.RetentionPolicy.RUNTIME;

    import java.lang.annotation.Documented;
    import java.lang.annotation.Repeatable;
    import java.lang.annotation.Retention;
    import java.lang.annotation.Target;

    import com.example.sample.domain.validation.Age.List;

    import jakarta.validation.Constraint;
    import jakarta.validation.Payload;
    import jakarta.validation.ReportAsSingleViolation;
    import jakarta.validation.constraints.Max;
    import jakarta.validation.constraints.Min;

    @Documented
    @Constraint(validatedBy = {})
    @Target({ METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE })
    @Retention(RUNTIME)
    @Repeatable(List.class)
    @ReportAsSingleViolation
    @Min(1)
    @Max(150)
    public @interface Age {
        String message() default "{com.example.sample.domain.validation.Age.message}";

        Class<?>[] groups() default {};

        Class<? extends Payload>[] payload() default {};

        @Target({ METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE })
        @Retention(RUNTIME)
        @Documented
        @interface List {
            Age[] value();
        }
    }

  .. note::

    1つのアノテーションに複数のルールを設定した場合、それらのAND条件が複合ルールとなる。Hibernate Validatorでは、OR条件を実現するための\ ``@ConstraintComposition``\ アノテーションが用意されている。

    詳細は、\ :url_hibernate_validator:`Hibernate Validatorのドキュメント </reference/en-US/html_single/#section-boolean-constraint-composition>`\ を参照されたい。

|

.. _ValidationImplementNewConstraint:

新規ルールを実装したBean Validationアノテーションの作成
--------------------------------------------------------------------------------

\ ``jakarta.validation.ConstraintValidator``\ インタフェースを実装し、そのValidatorを使用するアノテーションを作成することで、任意のルールを作成することができる。

用途としては、以下の3通りが挙げられる。

* 既存のルールの組み合わせでは表現できないルール
* 相関項目チェックルール
* 業務ロジックチェック

|

.. _ValidationCannotExpressExisting:

既存のルールの組み合わせでは表現できないルール
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

\ ``@Pattern``\ 、\ ``@Size``\ 、\ ``@Min``\ 、\ ``@Max``\ 等を組み合わせても表現できないルールは、\ ``jakarta.validation.ConstraintValidator``\ 実装クラスに記述する。

例として、IPv4形式のIPアドレス（Internet Protocol address）であることをチェックするルールを挙げる。

* アノテーション

  .. code-block:: java

    package com.example.common.validation;

    import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
    import static java.lang.annotation.ElementType.CONSTRUCTOR;
    import static java.lang.annotation.ElementType.FIELD;
    import static java.lang.annotation.ElementType.METHOD;
    import static java.lang.annotation.ElementType.PARAMETER;
    import static java.lang.annotation.ElementType.TYPE_USE;
    import static java.lang.annotation.RetentionPolicy.RUNTIME;

    import java.lang.annotation.Documented;
    import java.lang.annotation.Repeatable;
    import java.lang.annotation.Retention;
    import java.lang.annotation.Target;

    import com.example.common.validation.IPv4.List;
    import com.example.common.validation.IPv4Validator;

    import jakarta.validation.Constraint;
    import jakarta.validation.Payload;

    @Documented
    @Constraint(validatedBy = { IPv4Validator.class }) // (1)
    @Target({ METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE })
    @Retention(RUNTIME)
    @Repeatable(List.class)
    public @interface IPv4 {
        String message() default "{com.example.common.validation.IPv4.message}";

        Class<?>[] groups() default {};

        Class<? extends Payload>[] payload() default {};

        @Target({ METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE })
        @Retention(RUNTIME)
        @Documented
        @interface List {
            IPv4[] value();
        }
    }

  .. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
  .. list-table::
    :header-rows: 1
    :widths: 10 90

    * - 項番
      - 説明
    * - | (1)
      - | このアノテーションを使用したときに実行される\ ``ConstraintValidator``\ を指定する。複数指定することができる。

* Validator

  .. code-block:: java

    package com.example.common.validation;

    import jakarta.validation.ConstraintValidator;
    import jakarta.validation.ConstraintValidatorContext;

    public class IPv4Validator implements ConstraintValidator<IPv4, String> { // (1)

        @Override
        public void initialize(IPv4 constraintAnnotation) { // (2)
        }

        @Override
        public boolean isValid(String value, ConstraintValidatorContext context) { // (3)
            if (value == null) {
                return true; // (4)
            }
            return isIPv4Valid(value); // (5)
        }

        // This logic check IPv4 address like 192.168.0.1
        static boolean isIPv4Valid(String ipAddress) {
            String[] octets = ipAddress.split("\\.");
            if (octets.length != 4) {
                return false;
            }
            try {
                for (String octet: octets) {
                    int intOctet = Integer.parseInt(octet);
                    if (intOctet < 0 || 255 < intOctet) {
                        return false;
                    }
                }
            } catch (NumberFormatException e) {
                return false;
            }
            return true;
        }
    }

  .. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
  .. list-table::
    :header-rows: 1
    :widths: 10 90

    * - 項番
      - 説明
    * - | (1)
      - | ジェネリクスのパラメータに、対象のアノテーションとフィールドの型を指定する。
    * - | (2)
      - | \ ``initialize``\ メソッドに、初期化処理を実装する。
    * - | (3)
      - | \ ``isValid``\ メソッドで入力チェック処理を実装する。
    * - | (4)
      - | 入力値が、\ ``null``\ の場合は、正常とみなす。
    * - | (5)
      - | IPv4形式のIPアドレスであることのチェックを行う。

.. tip::

  \ :ref:`fileupload_validator`\ の例も、ここに分類される。また共通ライブラリでは、この実装として\ :ref:`@ExistInCodeList <codelist-validate>`\ を用意している。

|

.. _ValidationCorrelationItemCheck:

相関項目チェックルール
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

| \ :ref:`ValidationCorrelationCheck`\ で説明したように、Bean Validationによって複数のフィールドにまたがる相関項目チェックを実装できる。
| Bean Validationで相関項目チェックルールを実装する場合は、汎用的なルールを対象とすることを推奨する。

以下では、「あるフィールドとその確認用フィールドの内容が一致すること」というルールを実現する例を挙げる。

.. tip::

  共通ライブラリでは、2つのフィールドの内容を比較する相関項目チェックの実装として\ :ref:`@Compare <ValidationTerasolunaGfwList>`\ アノテーションを用意している。

  \ `@Compare`\ アノテーションを利用することで、このルールをより簡単に実現することができる。 詳細は\ :ref:`ValidationTerasolunaGfwHowToExtend`\ を参照されたい。

ここでは、内容が一致しない場合には確認用フィールドにエラーメッセージを表示する。

* アノテーション

  相関項目チェック用のアノテーションはクラスレベルに付与できるようにする。

  .. code-block:: java

    package com.example.common.validation;

    import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
    import static java.lang.annotation.ElementType.TYPE;
    import static java.lang.annotation.ElementType.TYPE_USE;
    import static java.lang.annotation.RetentionPolicy.RUNTIME;

    import java.lang.annotation.Documented;
    import java.lang.annotation.Repeatable;
    import java.lang.annotation.Retention;
    import java.lang.annotation.Target;

    import com.example.common.validation.Confirm.List;

    import jakarta.validation.Constraint;
    import jakarta.validation.Payload;

    @Documented
    @Constraint(validatedBy = { ConfirmValidator.class })
    @Target({ TYPE, ANNOTATION_TYPE, TYPE_USE }) // (1)
    @Retention(RUNTIME)
    @Repeatable(List.class)
    public @interface Confirm {
        String message() default "{com.example.common.validation.Confirm.message}";

        Class<?>[] groups() default {};

        Class<? extends Payload>[] payload() default {};

        /**
         * Field name
         */
        String field(); // (2)

        /**
         * ConfirmField name
         */
        String confirmField(); // (2)

        @Target({ TYPE, ANNOTATION_TYPE, TYPE_USE })
        @Retention(RUNTIME)
        @Documented
        @interface List {
            Confirm[] value();
        }
    }

  .. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
  .. list-table::
    :header-rows: 1
    :widths: 10 90

    * - 項番
      - 説明
    * - | (1)
      - | このアノテーションが、クラスまたはアノテーションにのみ付加できるように、対象を絞る。
    * - | (2)
      - | アノテーションに渡すパラメータを定義する。

* Validator

  .. code-block:: java

    package com.example.common.validation;

    import java.util.Objects;

    import org.springframework.beans.BeanWrapper;
    import org.springframework.beans.BeanWrapperImpl;

    import jakarta.validation.ConstraintValidator;
    import jakarta.validation.ConstraintValidatorContext;

    public class ConfirmValidator implements ConstraintValidator<Confirm, Object> {
        private String field;

        private String confirmField;

        private String message;

        public void initialize(Confirm constraintAnnotation) {
            field = constraintAnnotation.field();
            confirmField = constraintAnnotation.confirmField();
            message = constraintAnnotation.message();
        }

        public boolean isValid(Object value, ConstraintValidatorContext context) {
            BeanWrapper beanWrapper = new BeanWrapperImpl(value); // (1)
            Object fieldValue = beanWrapper.getPropertyValue(field); // (2)
            Object confirmFieldValue = beanWrapper.getPropertyValue(confirmField);
            boolean matched = Objects.equals(fieldValue, confirmFieldValue);
            if (matched) {
                return true;
            } else {
                context.disableDefaultConstraintViolation(); // (3)
                context.buildConstraintViolationWithTemplate(message)
                        .addPropertyNode(confirmField).addConstraintViolation(); // (4)
                return false;
            }
        }

    }

  .. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
  .. list-table::
    :header-rows: 1
    :widths: 10 90

    * - 項番
      - 説明
    * - | (1)
      - | JavaBeanのプロパティにアクセスする際に便利な\ ``org.springframework.beans.BeanWrapper``\ を使用する。
    * - | (2)
      - | \ ``BeanWrapper``\ 経由で、フォームオブジェクトからプロパティ値を取得する。
    * - | (3)
      - | デフォルトの\ ``ConstraintViolation``\ オブジェクトの生成を無効にする。
    * - | (4)
      - | 独自\ ``ConstraintViolation``\ オブジェクトを生成する。
        | \ ``ConstraintValidatorContext.buildConstraintViolationWithTemplate``\ で出力するメッセージを定義する。
        | \ ``ConstraintViolationBuilder.addPropertyNode``\ でエラーメッセージを出力したいフィールド名を指定する。
        | 詳細は、\ :url_jakarta_validation_apidocs:`ConstraintValidatorContextのJavaDoc </validation/constraintvalidatorcontext>`\ を参照されたい。

.. note::

  Spring Validatorによる相関項目チェックにて紹介したように、Bean Validationにおいても\ :ref:`相関チェック対象の複数フィールドに対してエラー情報を設定する<ValidationHowToCrossFieldValidationForMultiFieldHighlight>`\ ことが可能である。

  以下に、Bean Validationにて\ ``password``\ フィールドと\ ``confirmPassword``\ フィールドにスタイルを適用し、\ ``confirmPassword``\ フィールドのみにエラーメッセージを表示する例を示す。

    .. code-block:: java

      // omitted
      public class ConfirmValidator implements ConstraintValidator<Confirm, Object> {
          private String field;

          private String confirmField;

          private String message;

          public void initialize(Confirm constraintAnnotation) {
              // omitted
          }

          public boolean isValid(Object value, ConstraintValidatorContext context) {
              // omitted
              if (matched) {
                  return true;
              } else {
                  context.disableDefaultConstraintViolation();

                  //new ConstraintViolation to be generated for confirmField
                  context.buildConstraintViolationWithTemplate(message)
                          .addPropertyNode(confirmField).addConstraintViolation();

                  //new ConstraintViolation to be generated for field
                  context.buildConstraintViolationWithTemplate("") // (1)
                          .addPropertyNode(field).addConstraintViolation();

                  return false;
              }
          }

      }

    .. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
    .. list-table::
      :header-rows: 1
      :widths: 10 90

      * - 項番
        - 説明
      * - | (1)
        - | \ ``password``\ フィールドのエラーを登録する。この際、エラーメッセージに空文字を設定している。

この\ ``@Confirm``\ アノテーションを使用して、前述の「パスワードリセット」処理を再実装すると、以下のようになる。


* フォームクラス

  .. code-block:: java

    package com.example.sample.app.validation;

    import java.io.Serializable;

    import com.example.common.validation.Confirm;

    import jakarta.validation.constraints.NotNull;
    import jakarta.validation.constraints.Size;

    @Confirm(field = "password", confirmField = "confirmPassword") // (1)
    public class PasswordResetForm implements Serializable {
        private static final long serialVersionUID = 1L;

        @NotNull
        @Size(min = 8)
        private String password;

        private String confirmPassword;

        // omitted geter/setter
    }

  .. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
  .. list-table::
    :header-rows: 1
    :widths: 10 90

    * - 項番
      - 説明
    * - | (1)
      - | クラスレベルに\ ``@Confirm``\ アノテーションを付与する。
        | これにより\ ``ConstraintValidator.isValid``\ の引数にはフォームオブジェクトが渡る。

* Controllerクラス

  Validatorのインジェクションおよび\ ``@InitBinder``\ によるValidatorの追加は、不要になる。

  .. code-block:: java

    package com.example.sample.app.validation;

    import org.springframework.stereotype.Controller;
    import org.springframework.validation.BindingResult;
    import org.springframework.validation.annotation.Validated;
    import org.springframework.web.bind.annotation.GetMapping;
    import org.springframework.web.bind.annotation.ModelAttribute;
    import org.springframework.web.bind.annotation.PostMapping;
    import org.springframework.web.bind.annotation.RequestMapping;

    @Controller
    @RequestMapping("password")
    public class PasswordResetController {

        @ModelAttribute
        public PasswordResetForm setupForm() {
            return new PasswordResetForm();
        }

        @GetMapping(value = "reset", params = "form")
        public String resetForm() {
            return "password/resetForm";
        }

        @PostMapping(value = "reset")
        public String reset(@Validated PasswordResetForm form, BindingResult result) {
            if (result.hasErrors()) {
                return "password/resetForm";
            }
            return "redirect:/password/reset?complete";
        }

        @GetMapping(value = "reset", params = "complete")
        public String resetComplete() {
            return "password/resetComplete";
        }
    }

|

.. _ValidationBusinessLogicCheck:

業務ロジックチェック
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

| 業務ロジックチェックは、基本的には\ :ref:`ドメイン層のServiceで実装 <service-implementation-label>`\ し、結果メッセージは\ ``ResultMessages``\ オブジェクトに格納することを推奨している。
| したがって、\ :ref:`通常画面の上部などに表示されることを想定している <message-display>`\ 。

| 一方で、「入力されたユーザー名が既に登録済みかどうか」など、対象の入力フィールドに対する業務ロジックエラーメッセージを、フィールドの横に表示したい場合もある。
| このような場合は、ValidatorクラスにServiceクラスをインジェクションして、業務ロジックチェックを実行し、その結果を、\ ``ConstraintValidator.isValid``\ の結果に使用すればよい。

「入力されたユーザー名が既に登録済みかどうか」をBean Validationで実現する例を示す。

* Serviceクラス

  実装クラス(UserServiceImpl)は割愛する。

  .. code-block:: java

    package com.example.sample.domain.service.user;

    public interface UserService {

        boolean isUnusedUserId(String userId);

        // omitted other methods
    }

* アノテーション

  .. code-block:: java

    package com.example.sample.domain.validation;

    import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
    import static java.lang.annotation.ElementType.CONSTRUCTOR;
    import static java.lang.annotation.ElementType.FIELD;
    import static java.lang.annotation.ElementType.METHOD;
    import static java.lang.annotation.ElementType.PARAMETER;
    import static java.lang.annotation.ElementType.TYPE_USE;
    import static java.lang.annotation.RetentionPolicy.RUNTIME;

    import java.lang.annotation.Documented;
    import java.lang.annotation.Repeatable;
    import java.lang.annotation.Retention;
    import java.lang.annotation.Target;

    import com.example.sample.domain.validation.UnusedUserId.List;

    import jakarta.validation.Constraint;
    import jakarta.validation.Payload;

    @Documented
    @Constraint(validatedBy = { UnusedUserIdValidator.class })
    @Target({ METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE })
    @Retention(RUNTIME)
    @Repeatable(List.class)
    public @interface UnusedUserId {
        String message() default "{com.example.sample.domain.validation.UnusedUserId.message}";

        Class<?>[] groups() default {};

        Class<? extends Payload>[] payload() default {};

        @Target({ METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE })
        @Retention(RUNTIME)
        @Documented
        @interface List {
            UnusedUserId[] value();
        }
    }


* Validatorクラス

  .. code-block:: java

    package com.example.sample.domain.validation;

    import com.example.sample.domain.service.user.UserService;

    import jakarta.inject.Inject;
    import jakarta.validation.ConstraintValidator;
    import jakarta.validation.ConstraintValidatorContext;

    @Component // (1)
    public class UnusedUserIdValidator implements
                                      ConstraintValidator<UnusedUserId, String> {

        @Inject // (2)
        UserService userService;

        @Override
        public void initialize(UnusedUserId constraintAnnotation) {
        }

        @Override
        public boolean isValid(String value, ConstraintValidatorContext context) {
            if (value == null) {
                return true;
            }

            return userService.isUnusedUserId(value); // (3)
        }

    }

  .. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
  .. list-table::
    :header-rows: 1
    :widths: 10 90

    * - 項番
      - 説明
    * - | (1)
      - | Validatorクラスをコンポーネントスキャンの対象にする。
        | パッケージがBean定義ファイルの\ ``<context:component-scan base-package="..." />``\ の設定に含まれている必要がある。
    * - | (2)
      - | 呼び出すServiceクラスを、インジェクションする。
    * - | (3)
      - | 業務ロジックの結果を返却する。\ ``isValid``\ メソッド名で業務ロジックを記述せず、かならずServiceに処理を委譲すること。

|

.. _ValidationMethodValidation:

Method Validation 
--------------------------------------------------------------------------------

| Bean Validationによってメソッドの実引数と返り値の妥当性を確認する方法を説明する。
| 説明のために、本節ではこの方法をMethod Validationと呼ぶ。
| 防衛的プログラミングを行う場合などでは、Controller以外のクラスでメソッドの入出力を確認する必要がある。
| このとき、Bean Validationライブラリを利用すれば、Controllerで使用したBean Validationの制約アノテーションを再利用できる。
|

.. _ValidationMethodValidationOnSpringFrameworkHowToUseSettings:

アプリケーションの設定
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Spring Frameworkが提供するMethod Validationを使用する場合は、Spring Frameworkから提供されている\ ``org.springframework.validation.beanvalidation.MethodValidationPostProcessor``\ クラスをBean定義する必要がある。

\ ``MethodValidationPostProcessor``\ を定義するBean定義ファイルは、Method Validationを使用する箇所によって異なる。

ここでは、本ガイドラインが推奨するマルチプロジェクト環境でMethod Validationを使用するための設定例を示す。

* アプリケーション層用のプロジェクト(\ ``projectName-web``\ )
* ドメイン層用のプロジェクト(\ ``projectName-domain``\ )

の両プロジェクトの設定を変更する必要がある。

.. tabs::
  .. group-tab:: Java Config

    * \ :file:`projectName-domain/src/main/xxx/yyy/zzz/config/app/ProjectNameDomainConfig.java`\
    
      .. code-block:: java

        // (1)
        @Bean("validator")
        public LocalValidatorFactoryBean validator() {
            return new LocalValidatorFactoryBean();
        }

        @Bean
        public MethodValidationPostProcessor validationMethodValidationPostProcessor() {
            MethodValidationPostProcessor bean = new MethodValidationPostProcessor();
            bean.setValidator(validator());
            return bean;
        }

    * \ :file:`projectName-domain/src/main/xxx/yyy/zzz/config/web/SpringMvcConfig.java`\
    
      .. code-block:: java

        @EnableAspectJAutoProxy
        @EnableWebMvc
        @Configuration
        public class SpringMvcConfig implements WebMvcConfigurer {

            @Inject
            private LocalValidatorFactoryBean validator;

            // omitted

            // (3)
            @Override
            public Validator getValidator() {
                return validator;
            }

            // (4)
            @Bean
            public MethodValidationPostProcessor methodValidationPostProcessor() {
                MethodValidationPostProcessor bean = new MethodValidationPostProcessor();
                bean.setValidator(validator);
                return bean;
            }
   
    .. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
    .. list-table::
      :header-rows: 1
      :widths: 10 90
    
      * - 項番
        - 説明
      * - | (1)
        - \ ``LocalValidatorFactoryBean``\ をBean定義する。
      * - | (2)
        - \ ``MethodValidationPostProcessor``\ をBean定義し、ドメイン層のクラスのメソッドに対してMethod Validationが実行されるようにする。
    
          \ ``validator``\ プロパティには、(1)で定義したBeanを指定する。
      * - | (3)
        - \ ``WebMvcConfigurer``\ の\ ``getValidator``\ メソッドをOverrideし、(1)で定義したBeanを返却する。
    
          この設定がない場合は(1)で作成したものとは異なる\ ``Validator``\ インスタンスが生成されてしまう。
      * - | (4)
        - \ ``MethodValidationPostProcessor``\ をBean定義し、アプリケーション層のクラスのメソッドに対してMethod Validationが実行されるようにする。
    
          \ ``validator``\ プロパティには、(1)で定義したBeanを指定する。

  .. group-tab:: XML Config

    * \ :file:`projectName-domain/src/main/resources/META-INF/spring/projectName-domain.xml`\
    
      .. code-block:: xml
    
        <!-- (1) -->
        <bean id="validator"
              class="org.springframework.validation.beanvalidation.LocalValidatorFactoryBean"/>
    
        <!-- (2) -->
        <bean class="org.springframework.validation.beanvalidation.MethodValidationPostProcessor">
            <property name="validator" ref="validator" />
        </bean>
    
    * \ :file:`projectName-web/src/main/resources/META-INF/spring/spring-mvc.xml`\
    
      .. code-block:: xml
    
        <!-- (3) -->
        <mvc:annotation-driven validator="validator">
            <!-- ... -->
        </mvc:annotation-driven>
    
        <!-- (4) -->
        <bean class="org.springframework.validation.beanvalidation.MethodValidationPostProcessor">
            <property name="validator" ref="validator" />
        </bean>
    
    .. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
    .. list-table::
      :header-rows: 1
      :widths: 10 90
    
      * - 項番
        - 説明
      * - | (1)
        - \ ``LocalValidatorFactoryBean``\ をBean定義する。
      * - | (2)
        - \ ``MethodValidationPostProcessor``\ をBean定義し、
          ドメイン層のクラスのメソッドに対してMethod Validationが実行されるようにする。
    
          \ ``validator``\ プロパティには、(1)で定義したBeanを指定する。
      * - | (3)
        - \ ``<mvc:annotation-driven>``\ 要素の\ ``validator``\ 属性に、(1)で定義したBeanを指定する。
    
          この設定がない場合は(1)で作成したものとは異なる\ ``Validator``\ インスタンスが生成されてしまう。
      * - | (4)
        - \ ``MethodValidationPostProcessor``\ をBean定義し、
          アプリケーション層のクラスのメソッドに対してMethod Validationが実行されるようにする。
    
          \ ``validator``\ プロパティには、(1)で定義したBeanを指定する。

.. tip::

  \ ``LocalValidatorFactoryBean``\ は、Bean Validation(Hibernate Validator)が提供する\ ``Validator``\ クラスとSpring Frameworkを連携するためのラッパー\ ``Validator``\ オブジェクトを生成するためのクラスである。

  このクラスによって生成されたラッパー\ ``Validator``\ を使用することで、Spring Frameworkが提供するメッセージ管理機能(\ ``MessageSource``\ )やDIコンテナなどとの連携が行えるようになる。

.. tip::

  Spring Frameworkでは、DIコンテナで管理されているBeanのメソッド呼び出しに対するMethod Validationの実行を、AOPの仕組みを利用して行っている。

  \ ``MethodValidationPostProcessor``\ は、Method Validationを実行するためのAOPを適用するためのクラスである。

.. note::

  上記例では、各Beanの\ ``validator``\ プロパティに対して、同じ\ ``Validator``\ オブジェクト(インスタンス)を設定しているが、これは必ずしも必須ではない。ただし、特に理由がない場合は、同じオブジェクト(インスタンス)を設定しておくことを推奨する。

|

.. _ValidationMethodValidationOnSpringFrameworkHowToUseApplyTarget:

Method Validation対象のメソッドにするための定義方法
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

メソッドにMethod Validationを適用するには、対象のメソッドを含むことを示したアノテーションをクラスレベルに、Bean Validationの制約アノテーションをメソッドと仮引数にそれぞれ指定する必要がある。

「\ :ref:`ValidationMethodValidationOnSpringFrameworkHowToUseSettings`\ 」を行っただけでは、Method Validationを実行するAOPは適用されない。Method Validationを実行するAOPを適用するためには、インタフェース又はクラスに\ ``@ org.springframework.validation.annotation.Validated``\ アノテーションを付与する必要がある。

ここでは、インタフェースに対してアノテーションを指定する方法を紹介する。

.. code-block:: java

  package com.example.domain.service;

  import org.springframework.validation.annotation.Validated;

  @Validated // (1)
  public interface HelloService {
      // ...
  }

.. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
.. list-table::
  :header-rows: 1
  :widths: 10 90

  * - 項番
    - 説明
  * - | (1)
    - Method Validationの対象となるインタフェースに、\ ``Validated``\ アノテーションを指定する。

      上記例では、\ ``HelloService``\ インタフェースの実装メソッドに対して、Method Validationを実行するAOPが適用される。

.. tip::

  \ ``@Validated``\ アノテーションの\ ``value``\ 属性にグループインタフェースを指定することで、 指定したグループに属するValidationのみ実行する事も可能である。

  また、メソッドレベルに\ ``Validated``\ アノテーションを付与することで、メソッド毎にバリデーショングループを切り替える事も可能な仕組みとなっている。

  バリデーショングループについては、「\ :ref:`ValidationGroupValidation`\ 」を参照されたい。

|

| 次に、Bean Validationの制約アノテーションをメソッドや仮引数へ指定する方法を説明する。
| 具体的には、

* メソッドの引数
* メソッドの引数に指定されたJavaBeanのフィールド

に対してBean Validationの制約アノテーションを、

* メソッドの返り値
* メソッドの返り値として返却するJavaBeanのフィールド

に対してBean Validationの制約アノテーションを指定する。

| 以下に、具体的な指定方法について説明する。
| 以降の説明では、インタフェースにアノテーションを指定する方法を紹介する。
|
| まず、メソッドのシグネチャとして基本型(プリミティブやプリミティブラッパ型など)を使用するメソッドに対して、制約アノテーションを指定する方法について説明する。

.. code-block:: java

  package com.example.domain.service;

  import org.springframework.validation.annotation.Validated;

  import jakarta.validation.constraints.NotEmpty;

  @Validated
  public interface HelloService {

      // (2)
      @NotEmpty
      String hello(@NotEmpty /* (1) */ String message);

  }

.. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
.. list-table::
  :header-rows: 1
  :widths: 10 90

  * - 項番
    - 説明
  * - | (1)
    - Bean Validationの制約アノテーションをメソッドの引数アノテーションとして指定する。

      | \ ``@NotEmpty``\ は\ ``message``\ という引数がNull値と空文字を許可しないことを意味する制約である。
      | 引数にNull値もしくは空文字が指定された場合、\ ``jakarta.validation.ConstraintViolationException``\ が発生する。
  * - | (2)
    - Bean Validationの制約アノテーションをメソッドアノテーションとして指定する。

      上記例では、返り値がNull値もしくは空文字にならないことを示しており、返り値としてNull値もしくは空文字が返却された場合、\ ``jakarta.validation.ConstraintViolationException``\ が発生する。

|

次に、メソッドのシグネチャとしてJavaBeanを使用するメソッドに対して、Bean Validationの制約アノテーションを指定する方法について説明する。

ここでは、インタフェースに対してアノテーションを指定する方法を紹介する。

\ **Serviceインタフェース**\

.. code-block:: java

  package com.example.domain.service;

  import org.springframework.validation.annotation.Validated;

  import jakarta.validation.constraints.NotNull;

  @Validated
  public interface HelloService {

      @NotNull // (3)
      @Valid   // (4)
      HelloOutput hello(@NotNull /* (1) */ @Valid /* (2) */ HelloInput input);

  }

.. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
.. list-table::
  :header-rows: 1
  :widths: 10 90

  * - 項番
    - 説明
  * - | (1)
    - Bean Validationの制約アノテーションをメソッドの引数アノテーションとして指定する。

      \ ``input``\ という引数(JavaBean)がNull値を許可しない事を示しており、引数にNull値が指定された場合は、\ ``jakarta.validation.ConstraintViolationException``\ が発生する。
  * - | (2)
    - \ ``@jakarta.validation.Valid``\ アノテーションをメソッドの引数アノテーションとして指定する。

      | \ ``@Valid``\ アノテーションを付与する事で、引数のJavaBeanのフィールドに指定したBean Validationの制約アノテーションが有効となる。
      | JavaBeanに指定された制約を満たさない場合は\ ``jakarta.validation.ConstraintViolationException``\ が発生する。
  * - | (3)
    - Bean Validationの制約アノテーションをメソッドアノテーションとして指定する。

      返り値のJavaBeanがNull値にならないことを示しており、返り値としてNull値が返却された場合は例外が発生する。
  * - | (4)
    - \ ``@Valid``\ アノテーションをメソッドアノテーションとして指定する。

      | \ ``@Valid``\ アノテーションを付与する事で、返り値のJavaBeanのフィールドに指定したBean Validationの制約アノテーションが有効となる。
      | JavaBeanに指定された制約を満たさない場合は\ ``jakarta.validation.ConstraintViolationException``\ が発生する。

|

| 以下にJavaBeanの実装サンプルを紹介する。
| 基本的には、Bean Validationの制約アノテーションを指定するだけだが、JavaBeanが更にJavaBeanをネストしている場合は注意が必要になる。

\ **Input用のJavaBean**\

.. code-block:: java

  package com.example.domain.service;

  import java.time.LocalDate;

  import jakarta.validation.constraints.NotEmpty;
  import jakarta.validation.constraints.NotNull;
  import jakarta.validation.constraints.Past;

  public class HelloInput {

      @NotNull
      @Past
      private LocalDate visitDate;

      @NotEmpty
      private String visitMessage;

      private String userId;

      // ...

  }

\ **Output用のJavaBean**\

.. code-block:: java

  package com.example.domain.service;

  import java.time.LocalDate;

  import com.example.domain.model.User;

  import jakarta.validation.Valid;
  import jakarta.validation.constraints.NotEmpty;
  import jakarta.validation.constraints.NotNull;
  import jakarta.validation.constraints.Past;

  public class HelloOutput {

      @NotNull
      @Past
      private LocalDate acceptDate;

      @NotEmpty
      private String acceptMessage;

      @Valid // (5)
      private User user;

      // ...

  }

\ **Output用のJavaBean内でネストしているJavaBean**\

.. code-block:: java

  package com.example.domain.model;

  import java.time.LocalDate;

  import jakarta.validation.constraints.NotEmpty;
  import jakarta.validation.constraints.Past;

  public class User {

      @NotEmpty
      private String userId;

      @NotEmpty
      private String userName;

      @Past
      private LocalDate dateOfBirth;

      // ...

  }

.. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
.. list-table::
  :header-rows: 1
  :widths: 10 90

  * - 項番
    - 説明
  * - | (5)
    - ネストしたJavaBeanに指定しているBean Validationの制約アノテーションを有効にする場合は、
      \ ``@Valid``\ アノテーションをフィールドアノテーションとして指定する。

      | \ ``@Valid``\ アノテーションを付与する事で、ネストしたJavaBeanのフィールドに指定したBean Validationの制約アノテーションが有効となる。
      | ネストしたJavaBeanに指定された制約を満たさない場合は\ ``jakarta.validation.ConstraintViolationException``\ が発生する。

|

.. _ValidationMethodValidationOnSpringFrameworkHowToUseExceptionHandling:

制約違反時の例外ハンドリング
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

制約に違反した場合、\ ``jakarta.validation.ConstraintViolationException``\ が発生する。

\ ``ConstraintViolationException``\ が発生した場合、スタックトレースから発生したメソッドは特定できるが、具体的な違反内容が特定できない。

違反内容を特定するためには、\ ``ConstraintViolationException``\ をハンドリングしてログ出力を行う例外ハンドリングクラスを作成するとよい。

以下の例外ハンドリングクラスの作成例を示す。

.. code-block:: java

  package com.example.app;

  import org.slf4j.Logger;
  import org.slf4j.LoggerFactory;
  import org.springframework.web.bind.annotation.ControllerAdvice;
  import org.springframework.web.bind.annotation.ExceptionHandler;

  import jakarta.validation.ConstraintViolationException;

  @ControllerAdvice
  public class ConstraintViolationExceptionHandler {

      private static final Logger logger = LoggerFactory.getLogger(ConstraintViolationExceptionHandler.class);

      // (1)
      @ExceptionHandler
      public String handleConstraintViolationException(ConstraintViolationException e){
          // (2)
          if (logger.isErrorEnabled()) {
              logger.error("ConstraintViolations[\n{}\n]", e.getConstraintViolations());
          }
          return "common/error/systemError";
      }

  }

.. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
.. list-table::
  :header-rows: 1
  :widths: 10 90

  * - 項番
    - 説明
  * - | (1)
    - \ ``ConstraintViolationException``\ をハンドリングするための\ ``@ExceptionHandler``\ メソッドを作成する。

      メソッドの引数として、\ ``ConstraintViolationException``\ を受け取るようにする。
  * - | (2)
    - メソッドの引数で受け取った\ ``ConstraintViolationException``\ が保持している違反内容(\ ``ConstraintViolation``\ の\ ``Set``\ )をログに出力する。

.. note::

  \ ``@ControllerAdvice``\ アノテーションの詳細については「\ :ref:`application_layer_controller_advice`\ 」を参照されたい。

.. warning::

  \ ``ConstraintViolation#getMessage``\ メソッドを使用することでエラーメッセージを取得することができるが、Springの機能によるメッセージ補完は行われないため、エラーメッセージに \ ``{0}``\ でフィールド名を埋め込むことはできない。
    
  代わりに、フィールド名は\ ``ConstraintViolation#getPropertyPath``\ メソッドで取得することが可能である。
    
  Springの機能によるメッセージ補完については、\ :ref:`ValidationMessageInValidationMessages`\ のNoteを参照されたい。

  \ ``ConstraintViolation``\ の詳細については、\ :url_hibernate_validator:`Hibernate Validatorのリファレンス </reference/en-US/html_single/#section-constraint-violation-methods>`\ を参照されたい。

|   

Appendix
================================================================================

Hibernate Validatorが用意する入力チェックルール
--------------------------------------------------------------------------------

| Hibernate ValidatorはBean Validationで定義されたアノテーションに加え、独自の検証用アノテーションを提供している。
| 検証に使用することができるアノテーションのリストは、\ :url_hibernate_validator:`こちら </reference/en-US/html_single/#validator-defineconstraints-spec>`\ を参照されたい。

|

.. _ValidationJsr380Doc:

Bean Validationのチェックルール
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Bean Validationの標準アノテーション(\ ``jakarta.validation.*``\ )を以下に示す。

詳細は、\ :url_jakarta_validation:`Bean Validation specification(Built-in Constraint definitions) <#builtinconstraints>`\ を参照されたい。

.. tabularcolumns:: |p{0.15\linewidth}|p{0.30\linewidth}|p{0.30\linewidth}|p{0.25\linewidth}|
.. list-table::
  :header-rows: 1
  :widths: 15 30 30 25
  :class: longtable

  * - アノテーション
    - 対象の型
    - 説明
    - 使用例
  * - \ ``@NotNull``\
    - 任意
    - 対象のフィールドが、\ ``null``\ でないことを検証する。
    - .. code-block:: java

        @NotNull
        private String id;
            
  * - \ ``@NotEmpty``\
    - \ ``Collection``\ 、\ ``Map``\ 、Array、任意の\ ``CharSequence``\ インタフェースの実装クラスに適用可能
    - | \ ``null``\ 、または空文字でないことを検証する。
      | Stringの入力必須チェックについては\ ``@NotNull``\ ではなくこちらを使用することを推奨する。（2.0から追加）
    - .. code-block:: java

        @NotEmpty
        private String password;
            
  * - \ ``@NotBlank``\
    - 任意の\ ``CharSequence``\ インタフェースの実装クラスに適用可能
    - | \ ``null``\ 、空文字(\ ``""``\ )、空白のみでないことを検証する。（2.0から追加）
    - .. code-block:: java

        @NotBlank
        private String userId;
            
  * - \ ``@Null``\
    - 任意
    - | 対象のフィールドが、\ ``null``\ であることを検証する。
      | (例：グループ検証での使用)
    - .. code-block:: java

        @Null(groups={Update.class})
        private String id;
            
  * - \ ``@Pattern``\
    - \ ``String``\
    - | 対象のフィールドが正規表現にマッチするかどうか
      | (Hibernate Validator実装では、任意の\ ``CharSequence``\ インタフェースの実装クラスにも適用可能)
    - .. code-block:: java

        @Pattern(regexp = "[0-9]+")
        private String tel;
            
  * - \ ``@Min``\
    - | \ ``BigDecimal``\ , \ ``BigInteger``\ , \ ``byte``\ , \ ``short``\ , \ ``int``\ , \ ``long``\ およびラッパー
      | (Hibernate Validator実装では、任意の\ ``Number``\ の継承クラス,\ ``CharSequence``\ インタフェースの実装クラスにも適用可能。ただし、文字列が数値表現の場合に限る。)
    - 値が、最小値以上であるかどうかを検証する。
    - @Max参照
  * - \ ``@Max``\
    - | \ ``BigDecimal``\ , \ ``BigInteger``\ , \ ``byte``\ , \ ``short``\ , \ ``int``\ , \ ``long``\ およびラッパー
      | (Hibernate Validator実装では任意の\ ``Number``\ の継承クラス,\ ``CharSequence``\ インタフェースの実装クラスにも適用可能。ただし、文字列が数値表現の場合に限る。)
    - 値が、最大値以下であるかどうかを検証する。
    - .. code-block:: java

        @Min(1)
        @Max(100)
        private int quantity;
            
  * - \ ``@DecimalMin``\
    - \ ``BigDecimal``\ , \ ``BigInteger``\ , \ ``String``\ , \ ``byte``\ , \ ``short``\ , \ ``int``\ , \ ``long``\ およびラッパー
      (Hibernate Validator実装では任意の\ ``Number``\ の継承クラス,\ ``CharSequence``\ インタフェースの実装クラスにも適用可能)
    - | \ ``Decimal``\ 型の値が、最小値以上であるかどうかを検証する。
      | \ ``inclusive = false``\ を指定する事で、最小値より大きいかどうかを検証するように動作を変更する事ができる。
    - \ ``@DecimalMax``\ 参照
  * - \ ``@DecimalMax``\
    - \ ``BigDecimal``\ , \ ``BigInteger``\ , \ ``String``\ , \ ``byte``\ , \ ``short``\ , \ ``int``\ , \ ``long``\ およびラッパー
      (Hibernate Validator実装では任意の\ ``Number``\ の継承クラス,\ ``CharSequence``\ インタフェースの実装クラスにも適用可能)
    - | \ ``Decimal``\ 型の値が、最大値以下であるかどうかを検証する。
      | \ ``inclusive = false``\ を指定する事で、最大値より小さいかどうかを検証するように動作を変更する事ができる。
    - .. code-block:: java

        @DecimalMin("0.0")
        @DecimalMax("99999.99")
        private BigDecimal price;
            
  * - \ ``@Positive``\
    - \ ``BigDecimal``\ , \ ``BigInteger``\ , \ ``byte``\ , \ ``short``\ , \ ``int``\ , \ ``long``\ , \ ``float``\ , \ ``double``\ およびラッパー
    - | 値が正の数値（0を含まない）であるかどうかを検証する。（2.0から追加）
    - .. code-block:: java

        @Positive
        private int deposit;
            
  * - \ ``@PositiveOrZero``\
    - \ ``BigDecimal``\ , \ ``BigInteger``\ , \ ``byte``\ , \ ``short``\ , \ ``int``\ , \ ``long``\ , \ ``float``\ , \ ``double``\ およびラッパー
    - | 値が正の数値（0を含む）であるかどうかを検証する。（2.0から追加）
    - .. code-block:: java

        @PositiveOrZero
        private int deposit;
            
  * - \ ``@Negative``\
    - \ ``BigDecimal``\ , \ ``BigInteger``\ , \ ``byte``\ , \ ``short``\ , \ ``int``\ , \ ``long``\ , \ ``float``\ , \ ``double``\ およびラッパー
    - | 値が負の数値（0を含まない）であるかどうかを検証する。（2.0から追加）
    - .. code-block:: java

        @Negative
        private int deposit;
            
  * - \ ``@NegativeOrZero``\
    - \ ``BigDecimal``\ , \ ``BigInteger``\ , \ ``byte``\ , \ ``short``\ , \ ``int``\ , \ ``long``\ , \ ``float``\ , \ ``double``\ およびラッパー
    - | 値が正の数値（0を含む）であるかどうかを検証する。（2.0から追加）
    - .. code-block:: java

        @NegativeOrZero
        private int deposit;
            
  * - \ ``@Size``\
    - \ ``String``\ (文字列の長さ), \ ``Collection``\ (要素のサイズ), \ ``Map``\ (要素のサイズ), Array(配列の長さ)
      (Hibernate Validator実装では、任意の\ ``CharSequence``\ インタフェースの実装クラスにも適用可能)
    - | 要素の長さ(要素のサイズ)が\ ``min``\ と\ ``max``\ の間のサイズか検証する。
      | \ ``min``\ と\ ``max``\ は省略可能であるが、デフォルトは\ ``min=0``\ ,\ ``max= Integer.MAX_VALUE``\ となる。
    - .. code-block:: java

        @Size(min=4, max=64)
        private String password;
            
  * - \ ``@Digits``\
    - \ ``BigDecimal``\ , \ ``BigInteger``\ , \ ``String``\ , \ ``byte``\ , \ ``short``\ , \ ``int``\ , \ ``long``\ およびラッパー
    - | 値が指定された範囲内の数値であるかチェックする。
      | \ ``integer``\ に最大整数の桁を指定し、\ ``fraction``\ に最大小数桁を指定する。
    - .. code-block:: java

        @Digits(integer=6, fraction=2)
        private BigDecimal price;
            
  * - \ ``@AssertTrue``\
    - \ ``boolean``\ ,\ ``Boolean``\
    - 対象のフィールドが\ ``true``\ であることを検証する(例：規約に同意したかどうか)
    - .. code-block:: java

        @AssertTrue
        private boolean checked;
            
  * - \ ``@AssertFalse``\
    - \ ``boolean``\ ,\ ``Boolean``\
    - 対象のフィールドが\ ``false``\ であることを検証する
    - .. code-block:: java

        @AssertFalse
        private boolean checked;
            
  * - \ ``@Future``\
    - \ ``Date``\ , \ ``Calendar``\ および\ ``JSR-310 Date and Time API``\ で提供されるクラス
    - | 未来であるか検証する。
      | \ ``Date``\ のように日時を持つ型では未来日時であるか検証し、\ ``java.time.LocalDate``\ のように日付のみ持つ型では未来日付であるか検証する。
    - .. code-block:: java

        @Future
        private LocalDate eventDate;
            
  * - \ ``@FutureOrPresent``\
    - \ ``Date``\ , \ ``Calendar``\ および\ ``JSR-310 Date and Time API``\ で提供されるクラス
    - | 現在または未来であるか検証する。（2.0から追加）
      | \ ``Date``\ のように日時を持つ型では未来日時であるか検証し、\ ``java.time.LocalDate``\ のように日付のみ持つ型では未来日付であるか検証する。
    - .. code-block:: java

        @FutureOrPresent
        private LocalDate eventDate;
            
  * - \ ``@Past``\
    - \ ``Date``\ , \ ``Calendar``\ および\ ``JSR-310 Date and Time API``\ で提供されるクラス
    - | 過去であるか検証する。
      | \ ``Date``\ のように日時を持つ型では過去日時であるか検証し、\ ``java.time.LocalDate``\ のように日付のみ持つ型では過去日付であるか検証する。
    - .. code-block:: java

        @Past
        private LocalDate eventDate;
            
  * - \ ``@PastOrPresent``\
    - \ ``Date``\ , \ ``Calendar``\ および\ ``JSR-310 Date and Time API``\ で提供されるクラス
    - | 現在または過去であるか検証する。（2.0から追加）
      | \ ``Date``\ のように日時を持つ型では過去日時であるか検証し、\ ``java.time.LocalDate``\ のように日付のみ持つ型では過去日付であるか検証する。
    - .. code-block:: java

        @PastOrPresent
        private LocalDate eventDate;
            
  * - \ ``@Email``\
    - 任意の\ ``CharSequence``\ インタフェースの実装クラスに適用可能
    - | E-mailアドレスとして妥当であること検証する。（2.0から追加）
    - .. code-block:: java

        @Email
        private String email;
            
  * - \ ``@Valid``\
    - 任意の非プリミティブ型
    - 関連付けられているオブジェクトについて、再帰的に検証を行う。
    - .. code-block:: java

        @Valid
        private List<Employer> employers;
            
        @Valid
        private Dept dept;

.. warning::

  \ ``@Size``\ アノテーションでは、サロゲートペアと呼ばれるchar型2つ（32ビット）で表される文字に対する考慮がされていない。

  サロゲートペアを含む文字列をチェック対象とした場合、カウントした文字数が実際の入力文字数より多くカウントされる可能性があるため注意すること。

  サロゲートペアを含む文字列の文字列長については、\ :ref:`StringProcessingHowToGetSurrogatePairStringLength`\ を参照されたい。

.. warning::

  E-mailの形式は\ :url_ietf_rfc:`RFC2822 </rfc2822.txt>`\ で定義されているが、\ ``@Email``\ は厳密にRFC2822に準拠していることをチェックするものではない。

  例えばマルチバイト文字（全角文字）を含んでいても\ ``@Email``\ でのチェックをパスすることが確認されている。また、実際に利用されているEmailアドレスも、必ずしもRFC2822に厳密に準拠しているわけではない。

  これらの注意点を考慮した上で、利用・サポートするSMTPサーバなどによって適切なルールでの入力チェックを実装することを推奨する。実装の際は、\ :ref:`ValidationCombineExistingConstraint`\ を参照されたい。

.. warning::

  \ ``@Past``\ 、\ ``@Future``\ 、\ ``@PastOrPresent``\ 、\ ``@FutureOrPresent``\ アノテーションでは検証を\ ``compareTo``\ メソッドで行っており、検証対象の型により日付のみ検証するか日時を検証するかが異なる。

  このため、日付項目に\ ``Date``\ 型を利用していると以下のような事象が発生する可能性がある。

    * 現在日付を入力しているにも関わらず\ ``@Past``\ でのチェックをパスしてしまう。
    * 現在日付を入力しているにも関わらず\ ``@FutureOrPresent``\ でのチェックをパスできない。

  日付時刻の検証を行う場合は適切な型を利用するよう留意されたい。

.. note::

  Bean Validationが提供する\ ``ClockProvider``\ を実装することで、\ ``@Past``\ 、\ ``@Future``\ 、\ ``@PastOrPresent``\ 、\ ``@FutureOrPresent``\ の基準となる日付を変更することが出来る。

  なお、実装した\ ``ClockProvider``\ を適用するには、\ ``LocalValidatorFactoryBean``\ の継承クラスを作成し、\ ``postProcessConfiguration``\ メソッドをオーバーライドすれば良い。

  \ ``ClockProvider``\ を実装したクラスの例に関しては、\ :url_hibernate_validator:`Hibernate Validator Reference Guide(ClockProvider and temporal validation tolerance) </reference/en-US/html_single/#section-clock-provider>`\ を参照されたい。

|

.. _ValidationValidatorList:

Hibernate Validatorのチェックルール
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Hibernate Validatorの代表的なアノテーション(\ ``org.hibernate.validator.constraints.*``\ )を以下に示す。

詳細は、\ :url_hibernate_validator:`Hibernate Validator仕様 </reference/en-US/html_single/#validator-defineconstraints-hv-constraints>`\ を参照されたい。

.. tabularcolumns:: |p{0.15\linewidth}|p{0.30\linewidth}|p{0.30\linewidth}|p{0.25\linewidth}|
.. list-table::
  :header-rows: 1
  :widths: 15 30 30 25

  * - アノテーション
    - 対象の型
    - 説明
    - 使用例
  * - \ ``@CreditCardNumber``\
    - 任意の\ ``CharSequence``\ インタフェースの実装クラスに適用可能
    - | Luhnアルゴリズムでクレジットカード番号が妥当かどうかを検証する。使用可能な番号かどうかをチェックするわけではない。
      | \ ``ignoreNonDigitCharacters = true``\ を指定する事で、数字以外の文字を無視して検証する事ができる。
    - .. code-block:: java

        @CreditCardNumber
        private String cardNumber;
            
  * - \ ``@ISBN``\
    - 任意の\ ``CharSequence``\ インタフェースの実装クラスに適用可能
    - | ISBNの形式として妥当であること（番号の長さとチェックディジット）を検証する。
      | \ ``type``\ を指定する事で、ISBNの形式（ISBN-10とISBN-13）の選択が出来る。デフォルトではISBN-13となる。
      | 検証時には、ISBN以外のすべての文字（0-9までの数字とX以外の文字）は無視される。
      | このため、番号の一部を"\ ``-``\ "を利用して区切ることが出来る。（例：978-161-729-045-9）
    - .. code-block:: java

        @ISBN
        private String bookNumber;
            
  * - \ ``@URL``\
    - 任意の\ ``CharSequence``\ インタフェースの実装クラスに適用可能
    - URLとして妥当であること検証する。\ ``java.net.URL``\ のコンストラクタを使用して文字列検証を行っており、
      URLとして妥当とされるプロトコルはJVMがサポートするプロトコル(\ ``http``\ ,\ ``https``\ ,\ ``file``\ ,\ ``jar``\ など)に依存する。
    - .. code-block:: java

        @URL
        private String url;

.. warning::

    従来、Hibernate Validatorの独自アノテーションであった\ ``@Email``\ 、\ ``@NotBlank``\ 、\ ``@NotEmpty``\ は、Bean Validation 2.0よりデフォルトで提供されるようになった。これに伴い、Hibernate Validator 6.0より、Hibernate Validatorが提供する\ ``@Email``\ 、\ ``@NotBlank``\ 、\ ``@NotEmpty``\ は非推奨となった。引き続き使用することは出来るが、Bean Validationで提供されるアノテーションを使用することを推奨する。

.. tip::

  \ ``@URL``\ にて、JVMがサポートしていないプロトコルについても妥当として検証したい場合、Hibernateから提供されている\ ``org.hibernate.validator.constraintvalidators.RegexpURLValidator``\ を使用する。当該クラスは\ ``@URL``\ アノテーションに対応するValidatorクラスで、URL形式であるかを正規表現で検証しており、JVMがサポートしていないプロトコルについても妥当として検証可能である。

  * アプリケーション全体の\ ``@URL``\ のチェックルールを変更してもよい場合には、\ :url_hibernate_validator:`JavaDoc </api/org/hibernate/validator/constraints/URL.html>`\ に記載されているように、XMLにてValidatorクラスを\ ``RegexpURLValidator``\ に変更する。
  * 一部の項目だけに正規表現による検証を適用し、\ ``@URL``\ はデフォルトのルールを使用したい場合には、新規アノテーション、および\ ``RegexpURLValidator``\ と同様の検証を行う\ ``jakarta.validation.ConstraintValidator``\ 実装クラスを作成し、必要な項目に作成したアノテーションによる検証を適用する。

  など、用途に応じた適用を行えばよい。

  XMLによるチェックルール変更の詳細については\ :url_hibernate_validator:`Hibernateのリファレンス </reference/en-US/html_single/#section-configuration-validation-xml>`\ を、新規アノテーションの作成方法については、\ :ref:`ValidationImplementNewConstraint`\ をそれぞれ参照されたい。

|

.. _ValidationDefaultMessageInHibernateValidator:

Hibernate Validatorが用意するデフォルトメッセージ
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

hibernate-validator-<version>.jar内のorg/hibernate/validatorに、ValidationMessages.propertiesのデフォルト値が定義されている。

| 各言語に対応したValidationMessages.propertiesについては \ :url_hibernate_validator_github:`org/hibernate/validator <>`\ を参照されたい。

.. note::

  Hibernate Validator 6.1.0より日本語メッセージに対応している。

|

.. _ValidationTerasolunaGfw:

共通ライブラリが用意する入力チェックルール
--------------------------------------------------------------------------------

共通ライブラリでは、独自の検証用アノテーションを提供している。ここでは、共通ライブラリで提供しているアノテーションを使用した入力チェックルールの指定方法について説明する。

|

terasoluna-gfw-commonのチェックルール
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

\ :url_gfw:`terasoluna-gfw-common </terasoluna-gfw-common-libraries/terasoluna-gfw-common>`\ が提供するアノテーション(\ ``org.terasoluna.gfw.common.codelist.*``\ )を以下に示す。

.. tabularcolumns:: |p{0.15\linewidth}|p{0.30\linewidth}|p{0.30\linewidth}|p{0.25\linewidth}|
.. list-table::
  :header-rows: 1
  :widths: 15 30 30 25

  * - アノテーション
    - 対象の型
    - 説明
    - 使用例
  * - \ ``@ExistInCodeList``\
    - | \ ``Character``\
      | \ ``CharSequence``\ の実装クラス
      | (\ ``String``\ , \ ``StringBuilder``\ など)
      | \ ``Number``\ の継承クラス
      | (\ ``Integer``\ , \ ``Long``\ など)
    - 値がコードリストに含まれているかどうかを検証する。
    - \ :ref:`@ExistInCodeList <codelist-validate>`\ 参照

|

terasoluna-gfw-codepointsのチェックルール
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

\ :url_gfw:`terasoluna-gfw-codepoints </terasoluna-gfw-common-libraries/terasoluna-gfw-codepoints>`\ が提供するアノテーション(\ ``org.terasoluna.gfw.common.codepoints.*``\ )を以下に示す。なお、\ ``terasoluna-gfw-codepoints``\ はバージョン5.1.0.RELEASE以上で利用することができる。

.. tabularcolumns:: |p{0.15\linewidth}|p{0.30\linewidth}|p{0.30\linewidth}|p{0.25\linewidth}|
.. list-table::
  :header-rows: 1
  :widths: 15 30 30 25

  * - アノテーション
    - 対象の型
    - 説明
    - 使用例
  * - \ ``@ConsistOf``\
    - | \ ``CharSequence``\ の実装クラス
      | (\ ``String``\ , \ ``StringBuilder``\ など)
    - チェック対象の文字列が指定したコードポイント集合に全て含まれるかどうかを検証する。
    - \ :ref:`@ConsistOf <StringProcessingHowToUseCodePointsValidator>`\ 参照

|

.. _ValidationTerasolunaGfwList:

terasoluna-gfw-validatorのチェックルール
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

\ :url_gfw:`terasoluna-gfw-validator </terasoluna-gfw-common-libraries/terasoluna-gfw-validator>`\ が提供するアノテーション(\ ``org.terasoluna.gfw.common.validator.constraints.*``\ )を以下に示す。なお、\ ``terasoluna-gfw-validator``\ はバージョン5.1.0.RELEASE以上で利用することができる。

.. tabularcolumns:: |p{0.15\linewidth}|p{0.30\linewidth}|p{0.30\linewidth}|p{0.25\linewidth}|
.. list-table::
  :header-rows: 1
  :widths: 15 30 30 25
  :class: longtable

  * - アノテーション
    - 対象の型
    - 説明
    - 使用例
  * - \ ``@ByteMin``\
    - | \ ``CharSequence``\ の実装クラス
      | (\ ``String``\ , \ ``StringBuilder``\ など)
    - | 値のバイト長が最小値以上であることを検証する。
      |
      | \ **[アノテーションの属性]**\
      | \ ``long value``\  - バイト長の最小値を指定する。
      | \ ``String charset``\  - 値をバイトシーケンスに符号化する際に使用する文字セットを指定する。デフォルト値は\ ``UTF-8``\ 。
    - .. code-block:: java

        @ByteMin(value = 1, charset = "Shift_JIS")
        private String id;

  * - \ ``@ByteMax``\
    - | \ ``CharSequence``\ の実装クラス
      | (\ ``String``\ , \ ``StringBuilder``\ など)
    - | 値のバイト長が最大値以下であることを検証する。
      |
      | \ **[アノテーションの属性]**\
      | \ ``long value``\  - バイト長の最大値を指定する。
      | \ ``String charset``\  - 値をバイトシーケンスに符号化する際に使用する文字セットを指定する。デフォルト値は\ ``UTF-8``\ 。
    - .. code-block:: java

        @ByteMax(100)
        private String id;

  * - \ ``@ByteSize``\
    - | \ ``CharSequence``\ の実装クラス
      | (\ ``String``\ , \ ``StringBuilder``\ など)
    - | 値のバイト長が最小値と最大値の範囲内であることを検証する。（**5.4.2から追加**）
      | \ ``@ByteMin``\ と \ ``@ByteMax``\ を組み合わせて使う場合は、こちらを使うことを推奨する。
      |
      | \ **[アノテーションの属性]**\
      | \ ``long min``\  - バイト長の最小値を指定する。デフォルト値は\ ``0``\ 。
      | \ ``long max``\  - バイト長の最大値を指定する。デフォルト値は\ ``Long.MAX_VALUE``\ 。
      | \ ``String charset``\  - 値をバイトシーケンスに符号化する際に使用する文字セットを指定する。デフォルト値は\ ``UTF-8``\ 。
    - .. code-block:: java

        @ByteSize(min = 1, max = 100)
        private String id;

  * - \ ``@Compare``\
    - | \ ``Comparable``\ インタフェースの実装クラスをプロパティにもつ任意のJavaBeanに適用可能
    - | 指定したプロパティの値の比較結果が正しいことを検証する。
      |
      | \ **[アノテーションの属性]**\
      | \ ``String left``\  - オブジェクト内の比較元としたいプロパティ名を指定する。検証エラーとなった場合は、このプロパティにメッセージを表示される。
      | \ ``String right``\  - オブジェクト内の比較先としたいプロパティ名を指定する。
      | \ ``org.terasoluna.gfw.common.validator.constraints.Compare.Operator operator``\  - 比較方法を示す列挙型\ ``Operator``\ の値を指定する。指定可能な値は以下の通り。

      * \ ``EQUAL``\  : \ ``left = right``\ である
      * \ ``NOT_EQUAL``\  : \ ``left != right``\ である
      * \ ``GREATER_THAN``\  : \ ``left > right``\ である
      * \ ``GREATER_THAN_OR_EQUAL``\  : \ ``left >= right``\ である
      * \ ``LESS_THAN``\  : \ ``left < right``\ である
      * \ ``LESS_THAN_OR_EQUAL``\  : \ ``left <= right``\ である

      | \ ``NOT_EQUAL``\ は、terasoluna-gfw-validator 5.3.2.RELEASE以上で利用可能な値である。
      |
      | \ ``boolean requireBoth``\  - \ ``left``\ 属性と\ ``right``\ 属性で指定したフィールドの両方が入力されている（\ ``null``\ でない）必要があるかどうかを指定する。

      * \ ``true``\  : どちらか一方だけ入力されている場合は検証エラーとする。ただし、両方とも未入力の場合は検証成功とする
      * \ ``false``\  : どちらか一方でも入力されている場合は検証成功とする（デフォルト）

      | \ ``org.terasoluna.gfw.common.validator.constraints.Compare.Node node``\  - エラーメッセージを出力するパスを示す列挙型\ ``Node``\ の値を指定する。指定可能な値は以下の通り。

      * \ ``PROPERTY``\  : \ ``left``\ 属性で指定したフィールドのエラーとして出力する（デフォルト）
      * \ ``ROOT_BEAN``\  : チェックを実施したオブジェクトのエラーとして出力する

    - メールアドレスと確認用に入力したメールアドレスが一致することをチェックし、フォーム全体のエラーメッセージとして表示する場合、以下のように実装する。

      .. code-block:: java

        @Compare(left = "email",
                right = "confirmEmail",
                operator = Compare.Operator.EQUAL,
                requireBoth = true,
                node = Compare.Node.ROOT_BEAN)
        public class UserRegisterForm {
            private String email;
            private String confirmEmail;
        }

      |

      期間の開始日と終了日が両方入力された場合は、開始日が終了日以前であることをチェックし、期間の開始日にエラーメッセージを表示する場合、以下のように実装する。

      .. code-block:: java

        @Compare(left = "form",
                right = "to",
                operator = Compare.Operator.LESS_THAN_OR_EQUAL)
        public class Period {
            private LocalDate from;
            private LocalDate to;
        }

.. note:: \ **相関項目チェックにおける入力必須について**\
  
  単項目チェックにおいては、入力フィールドが入力されている（ \ ``null``\ でない）かどうかは \ ``@NotNull``\ を併用してチェックすればよい。しかし、相関項目チェックにおいては、「どちらか一方でも入力した場合は、もう一方の入力を強制する」といった、 \ ``@NotNull``\ の併用だけでは実現できない場合がある。このため、\ ``@Compare``\ では、チェック対象の入力必須を制御する \ ``requireBoth``\ 属性を提供しており、これを併用して要件に応じたチェックを実装することができる。

  なお、入力フィールドが未入力の場合に \ ``null``\ がバインドされる場合のみ、 \ ``requireBoth``\ 属性が利用できる。Spring MVCでは文字列の入力フィールドに未入力の状態でフォームを送信した場合、デフォルトでは、フォームオブジェクトに\ ``null``\ ではなく、空文字がバインドされることに注意しなければならない。  文字列フィールドが未入力の場合に、空文字ではなく、\ ``null``\ をフォームオブジェクトにバインドするには、\ :ref:`ValidationStringTrimmerEditor`\ を参照されたい。
  
  期間の開始日が終了日以前であることのチェックを例に、想定されるチェック要件と設定の例を以下に示す。
  
    .. tabularcolumns:: |p{0.50\linewidth}|p{0.50\linewidth}|
    .. list-table::
      :header-rows: 1
      :widths: 50 50
      :class: longtable

      * - チェック要件
        - 設定例
      * - \ ``from``\ と \ ``to``\ がともに必須で、\ ``from``\ と \ ``to``\ の比較チェックを行う。
        - \ ``from``\ と \ ``to``\ に \ ``@NotNull``\ を付与し、 \ ``requireBoth``\ 属性はデフォルト値（ \ ``false``\ ）を使用する。

          .. code-block:: java

            @Compare(left = "from", right = "to", operator = Compare.Operator.LESS_THAN_OR_EQUAL)
            public class Period {
                @NotNull
                LocalDate from;
                @NotNull
                LocalDate to;
            }

      * - \ ``from``\ だけ必須だが、 \ ``to``\ も入力された時は比較チェックする。
        - \ ``from``\ にだけ \ ``@NotNull``\ を付与し、 \ ``requireBoth``\ 属性はデフォルト値（ \ ``false``\ ）を使用する。

          .. code-block:: java

            @Compare(left = "from", right = "to", operator = Compare.Operator.LESS_THAN_OR_EQUAL)
            public class Period {
                @NotNull
                LocalDate from;
                LocalDate to;
            }

      * - \ ``from``\ と \ ``to``\ がともに必須ではなく、 \ ``from``\ と \ ``to``\ が両方入力された時だけ比較チェックする。どちらか一方だけが入力された場合は比較チェックを行わない。
        - \ ``@NotNull``\ は付与せず、 \ ``requireBoth``\ 属性はデフォルト値（ \ ``false``\ ）を使用する。

          .. code-block:: java

            @Compare(left = "from", right = "to", operator = Compare.Operator.LESS_THAN_OR_EQUAL)
            public class Period {
                LocalDate from;
                LocalDate to;
            }

      * - \ ``from``\ と \ ``to``\ がともに必須ではないが、 \ ``from``\ か \ ``to``\ のどちら一方でも入力した場合は、必ず両方入力して比較チェックを行う。
        - \ ``@NotNull``\ は付与せず、 \ ``requireBoth``\ 属性に \ ``true``\ を設定する。

          .. code-block:: java

            @Compare(left = "from", right = "to", operator = Compare.Operator.LESS_THAN_OR_EQUAL, requireBoth = true)
            public class Period {
                LocalDate from;
                LocalDate to;
            }

|

.. _ValidationDefaultMessageInTerasolunaGfw:

共通ライブラリが用意するデフォルトメッセージ
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

共通ライブラリの各Jar内のContributorValidationMessages.propertiesファイルに、ValidationMessages.propertiesのデフォルト値が定義されている。

| 各言語に対応したValidationMessages.propertiesが定義されており、\ :doc:`../WebApplicationDetail/Internationalization`\ の仕組みによりメッセージが決定される。
| 対応する言語については各ライブラリ（\ :url_gfw:`terasoluna-gfw-commonのjar </terasoluna-gfw-common-libraries/terasoluna-gfw-common/src/main/resources>`\ 、\ :url_gfw:`terasoluna-gfw-codepointsのjar </terasoluna-gfw-common-libraries/terasoluna-gfw-codepoints/src/main/resources>`\ 、\ :url_gfw:`terasoluna-gfw-validatorのjar </terasoluna-gfw-common-libraries/terasoluna-gfw-validator/src/main/resources>`\ ）を参照されたい。

.. code-block:: properties

  # terasoluna-gfw-common
  org.terasoluna.gfw.common.codelist.ExistInCodeList.message = Does not exist in {codeListId}

  # terasoluna-gfw-codepoints
  org.terasoluna.gfw.common.codepoints.ConsistOf.message = not consist of specified code points

  # terasoluna-gfw-validator
  org.terasoluna.gfw.common.validator.constraints.ByteMin.message = must be greater than or equal to {value} bytes
  org.terasoluna.gfw.common.validator.constraints.ByteMax.message = must be less than or equal to {value} bytes
  org.terasoluna.gfw.common.validator.constraints.ByteSize.message = must be between {min} and {max} bytes
  org.terasoluna.gfw.common.validator.constraints.Compare.message = invalid combination of {left} and {right}

.. note::

  共通ライブラリでは、共通ライブラリの各Jar内のContributorValidationMessages.propertiesファイルで提供している。

  ContributorValidationMessages.propertiesファイルはHibernate Validatorのメッセージ定義ファイルである。
  
  他のBean Validation実装ライブラリを利用する場合はデフォルトメッセージが適用されないことに注意されたい。

|

.. _ValidationTerasolunaGfwHowToUse:

共通ライブラリのチェックルールの適用方法
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

以下の手順で、共通ライブラリのチェックルールを適用する。

| 使用したいチェックルールに応じて、依存ライブラリを追加する。\ ``terasoluna-gfw-validator``\ を追加する例を以下に示す。
| なお、\ ``terasoluna-gfw-common``\ はブランクプロジェクトのデフォルト設定で使用可能であり、依存ライブラリを追加する必要はない。

.. code-block:: xml

  <dependencies>
      <dependency>
          <groupId>org.terasoluna.gfw</groupId>
          <artifactId>terasoluna-gfw-validator</artifactId>
      </dependency>
  </dependencies>

あとは\ :ref:`ValidationBasicValidation`\ で説明したように、JavaBeanのプロパティにアノテーションを付与すればよい。

.. note::

  Bean Validationでは、アノテーションの属性値の不正により検証が実行できない場合、\ ``jakarta.validation.ValidationException``\ がスローされる。スタックトレースに出力される原因を参照し、属性値を適切な値に修正すること。
    
  詳細は、\ :url_jakarta_validation:`Bean Validation specification(Exception model) <#exception>`\ を参照されたい。

|

.. _ValidationTerasolunaGfwHowToExtend:

共通ライブラリのチェックルールの拡張方法
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

共通ライブラリで提供しているチェックルールを利用して、任意のルールを作成することができる。

以下では、\ :ref:`ValidationCorrelationItemCheck`\ で独自に実装した\ ``@Confirm``\ アノテーションを、共通ライブラリで提供しているチェックルールを利用して作成する例を紹介する。

\ :ref:`ValidationCombineExistingConstraint`\ で説明したように、\ ``@Compare``\ を利用して\ ``@Confirm``\ アノテーションを作成する。

.. code-block:: java

  package com.example.sample.domain.validation;

  import java.lang.annotation.Documented;
  import java.lang.annotation.Repeatable;
  import java.lang.annotation.Retention;
  import java.lang.annotation.Target;

  import org.terasoluna.gfw.common.validator.constraints.Compare;

  import com.example.sample.domain.validation.Confirm.List;

  import jakarta.validation.Constraint;
  import jakarta.validation.OverridesAttribute;
  import jakarta.validation.Payload;

  @Documented
  @Constraint(validatedBy = {})
  @Target({ TYPE, ANNOTATION_TYPE, TYPE_USE }) // (1)
  @Retention(RUNTIME)
  @Repeatable(List.class)
  @Compare(left = "", right = "", operator = Compare.Operator.EQUAL, requireBoth = true) // (2)
  public @interface Confirm {

      @OverridesAttribute(constraint = Compare.class, name = "message") // (3)
      String message() default "{com.example.sample.domain.validation.Confirm.message}";

      Class<?>[] groups() default {};

      Class<? extends Payload>[] payload() default {};

      @OverridesAttribute(constraint = Compare.class, name = "right") // (4)
      String field();

      @OverridesAttribute(constraint = Compare.class, name = "left") // (5)
      String confirmField();

      @Documented
      @Target({ TYPE, ANNOTATION_TYPE, TYPE_USE })
      @Retention(RUNTIME)
      @interface List {
          Confirm[] value();
      }
  }

.. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
.. list-table::
  :header-rows: 1
  :widths: 10 90

  * - 項番
    - 説明
  * - | (1)
    - | このアノテーションを付与できる場所を、クラスまたはアノテーションに限定する。
  * - | (2)
    - | \ ``@Compare``\ アノテーションの\ ``operator``\ 属性に\ ``Compare.Operator.EQUAL``\ (同値であること)を指定する。どちらか一方が未入力の場合はエラーとするため、\ ``requireBoth``\ 属性に\ ``true``\ を指定する。
  * - | (3)
    - | \ ``@Compare``\ アノテーションの\ ``message``\ 属性をオーバーライドし、エラー時に\ ``message``\ 属性に指定したメッセージが使用されるようにする。
  * - | (4)
    - | \ ``@Compare``\ アノテーションの\ ``right``\ 属性をオーバーライドし、属性名を\ ``field``\ に変更する。
  * - | (5)
    - | 同様に\ ``left``\ 属性をオーバーライドし、属性名を\ ``confirmField``\ に変更する。

.. note::

  「\ :ref:`ValidationCombineExistingConstraint`\ 」では\ ``@ReportAsSingleViolation``\ を付与する方法を紹介しているが、\ ``@ReportAsSingleViolation``\ を付与するとラップされた\ ``@Compare``\ のエラーメッセージは使用されず、\ ``@Confirm``\ のエラーメッセージのみが表示される。\ ``@Confirm``\ はフォームオブジェクトに対する入力チェックであるため、エラーメッセージはフォームオブジェクトに割り当てられ、実際に表示したい\ ``field``\ 属性に指定したフィールドには割り当てられない。
     
  これを回避するためには、\ ``@ReportAsSingleViolation``\ を付与せず、\ ``@Confirm``\ の\ ``message``\ 属性で\ ``@Compare``\ の\ ``message``\ 属性をオーバーライドする必要がある。これにより、\ ``@Compare``\ のルールに従い\ ``left``\ 属性（つまり\ ``@Confirm``\ の\ ``field``\ 属性）に\ ``@Confirm``\ のエラーメッセージを割り当てることができるようになる。

\ :ref:`ValidationCorrelationItemCheck`\ で実装したアノテーションの代わりに、上記で作成したアノテーションを使用する。

.. code-block:: java

  package com.example.sample.app.validation;

  import java.io.Serializable;

  import com.example.sample.domain.validation.Confirm;

  import jakarta.validation.constraints.NotEmpty;
  import jakarta.validation.constraints.NotNull;
  import jakarta.validation.constraints.Size;

  @Confirm(field = "password", confirmField = "confirmPassword") // (1)
  public class PasswordResetForm implements Serializable {
      private static final long serialVersionUID = 1L;

      @NotNull // (2)
      @Size(min = 8)
      private String password;

      @NotEmpty // (3)
      private String confirmPassword;

      // omitted geter/setter
  }

.. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
.. list-table::
  :header-rows: 1
  :widths: 10 90

  * - 項番
    - 説明
  * - | (1)
    - | クラスレベルに\ ``@Confirm``\ アノテーションを付与する。
  * - | (2)
    - | \ ``password``\ フィールドが\ ``null``\ の場合は\ ``@Confirm``\ の検証はパスするため、\ ``null``\ チェックは\ ``@NotNull``\ アノテーションを付与して行う。
  * - | (3)
    - | \ ``confirmPassword``\ フィールドには、\ ``@NotEmpty``\ アノテーションを付与する。

|

.. _ValidationTypeMismatch:

型のミスマッチ
--------------------------------------------------------------------------------

フォームオブジェクトの\ ``String``\ 以外のフィールドに対して、変換不可能な値を送信した場合は\ ``org.springframework.beans.TypeMismatchException``\ がスローされる。

「新規ユーザー登録」処理の例では「Age」フィールドは\ ``Integer``\ で定義されているが、このフィールドに対して整数に変換できない値を入力すると、以下のようなエラーメッセージが表示される。

.. figure:: ./images_Validation/validations-typemismatch1.png
  :width: 60%

例外の原因がそのまま表示されてしまい、エラーメッセージとしては不適切である。型がミスマッチの場合のエラーメッセージは、\ ``org.springframework.context.MessageSource``\ が読み込むpropertiesファイル(application-messages.properties)に定義できる。

以下のルールで、エラーメッセージを定義すればよい。

.. tabularcolumns:: |p{0.35\linewidth}|p{0.40\linewidth}|p{0.25\linewidth}|
.. list-table::
  :widths: 35 40 25
  :header-rows: 1

  * - メッセージキー
    - メッセージ内容
    - 用途
  * - \ ``typeMismatch``\
    - 型ミスマッチエラーのデフォルトメッセージ
    - システム全体のデフォルト値
  * - \ ``typeMismatch.対象のFQCN``\
    - 特定の型ミスマッチエラーのデフォルトメッセージ
    - システム全体のデフォルト値
  * - \ ``typeMismatch.フォーム属性名.プロパティ名``\
    - 特定のフォームのフィールドに対する型ミスマッチエラーのメッセージ
    - 画面毎に変更したいメッセージ

application-messages.propertiesに以下の定義を行った場合、

.. code-block:: properties

  # typemismatch
  typeMismatch="{0}" is invalid.
  typeMismatch.int="{0}" must be an integer.
  typeMismatch.double="{0}" must be a double.
  typeMismatch.float="{0}" must be a float.
  typeMismatch.long="{0}" must be a long.
  typeMismatch.short="{0}" must be a short.
  typeMismatch.java.lang.Integer="{0}" must be an integer.
  typeMismatch.java.lang.Double="{0}" must be a double.
  typeMismatch.java.lang.Float="{0}" must be a float.
  typeMismatch.java.lang.Long="{0}" must be a long.
  typeMismatch.java.lang.Short="{0}" must be a short.
  typeMismatch.java.time.LocalDate="{0}" is not a date.

  # filed names
  name=Name
  email=Email
  age=Age

エラーメッセージは、次のように変更される。

.. figure:: ./images_Validation/validations-typemismatch2.png
  :width: 60%

| \ :ref:`ValidationMessageInApplicationMessages`\ で説明したように、\ ``{0}``\ でフィールド名を埋めることができる。
| \ **基本的にデフォルトメッセージは定義しておくこと**\ 。

.. tip::

  メッセージキーのルールの詳細は、\ :url_spring_javadoc:`DefaultMessageCodesResolverのJavaDoc </org/springframework/validation/DefaultMessageCodesResolver.html>`\ を参照されたい。

|

.. _ValidationStringTrimmerEditor:

文字列フィールドが未入力の場合にnullをバインドする
--------------------------------------------------------------------------------

これまで説明してきたように、Spring MVCでは文字列の入力フィールドに未入力の状態でフォームを送信した場合、デフォルトでは、フォームオブジェクトに\ ``null``\ ではなく、空文字がバインドされる。

この場合、「未入力は許容するが、入力された場合は6文字以上であること」という要件を、既存のアノテーションで満たすことができない。

| 文字列フィールドが未入力の場合に、空文字ではなく、\ ``null``\ をフォームオブジェクトにバインドするには、
| 以下のように\ ``org.springframework.beans.propertyeditors.StringTrimmerEditor``\ を使用すればよい。

.. code-block:: java

  @Controller
  @RequestMapping("xxx")
  public class XxxController {

      @InitBinder
      public void initBinder(WebDataBinder binder) {
          // bind empty strings as null
          binder.registerCustomEditor(String.class, new StringTrimmerEditor(true));
      }

      // omitted ...
  }

この設定により、Controller毎に空文字を\ ``null``\ とみなすかどうかを設定できる。

プロジェクト全体で空文字を\ ``null``\ にしたい場合は、プロジェクト共通設定として\ :ref:`@ControllerAdvice <application_layer_controller_advice>`\ で設定すればよい。

.. code-block:: java

  @ControllerAdvice
  public class XxxControllerAdvice {

      @InitBinder
      public void initBinder(WebDataBinder binder) {
          // bind empty strings as null
          binder.registerCustomEditor(String.class, new StringTrimmerEditor(true));
      }

      // omitted ...
  }

| この設定を行った場合は、フォームオブジェクトの文字列フィールドに設定される空文字がすべて\ ``null``\ になる。
| したがって、必須チェックに、かならず\ ``@NotNull``\ が必要であることに注意しないといけない。

.. tip:: \ **Spring Framework 4.0 より追加された@ControllerAdviceアノテーションの属性について**\

  \ ``@ControllerAdvice``\ アノテーションの属性を指定することで、\ ``@ControllerAdvice``\ が付与されたクラスで実装したメソッドを適用するControllerを柔軟に指定できるように改善されている。

  属性の詳細については、\ :ref:`@ControllerAdviceの属性 <application_layer_controller_advice_attribute>`\ を参照されたい。

|

.. _ValidationWithoutNative2Ascii:

Native to Asciiを行わないメッセージの読み込み
--------------------------------------------------------------------------------

Native to Asciiを行わずにBean Validationのメッセージ（\ ``ValidationMessage.properties``\ ）を読み込む方法紹介する。

日本語メッセージをNative to Asciiせずに直接扱いたい場合、Springの \ ``MessageSource``\ と連携すると簡単に実装することができる。

以下のように定義すると、\ ``MessageSource``\ の機能で読み込まれたメッセージが\ ``Hibernate Validator``\ の中で使用されるようになる。

.. tabs::
  .. group-tab:: Java Config

    * Bean定義

      \ ``XxxDomainConfig.java``\ 

      .. code-block:: java

        // (1)
        @Bean("validator")
        public LocalValidatorFactoryBean validator(
                ResourceBundleMessageSource resourceBundleMessageSource) {
            LocalValidatorFactoryBean bean = new LocalValidatorFactoryBean();
            bean.setValidationMessageSource(resourceBundleMessageSource());
            return bean;
        }

        // (2)
        @Bean
        public ResourceBundleMessageSource resourceBundleMessageSource() {
            ResourceBundleMessageSource bean = new ResourceBundleMessageSource();
            bean.setBasenames("ValidationMessages"); // (3)
            bean.setDefaultEncoding("UTF-8");
            return bean;
        }

        // (4)
        @Bean
        public MethodValidationPostProcessor notAsciiValidationMethodValidationPostProcessor() {
            MethodValidationPostProcessor bean = new MethodValidationPostProcessor();
            bean.setValidator(validator());
            return bean;
        }

      \ ``SpringMvcConfig.java``\ 
    
      .. code-block:: java

        @EnableAspectJAutoProxy
        @EnableWebMvc
        @Configuration
        public class SpringMvcConfig implements WebMvcConfigurer {

            @Inject
            private LocalValidatorFactoryBean validator;

            // omitted

            // (5)
            @Override
            public Validator getValidator() {
                return validator;
            }

            // (6)
            @Bean
            public MethodValidationPostProcessor methodValidationPostProcessor() {
                MethodValidationPostProcessor bean = new MethodValidationPostProcessor();
                bean.setValidator(validator);
                return bean;
            }
   
      .. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
      .. list-table::
        :header-rows: 1
        :widths: 10 90
    
        * - 項番
          - 説明
        * - | (1)
          - \ ``LocalValidatorFactoryBean``\ をBean定義する。
        * - | (2)
          - \ ``MessageSource``\ の定義。ここでは\ ``ResourceBundleMessageSource``\ を使用する。
        * - | (3)
          - \ ``ApplicationContext``\ に読み込ませるリソースバンドルを指定する。
        * - | (4)
          - | \ :ref:`ValidationMethodValidation`\ を利用する際には、\ ``MethodValidationPostProcessor``\ の\ ``validator``\ プロパティに(1)で定義したBeanを指定する。  
            | Method Validationを利用しない場合、このBean定義は不要である。
        * - | (5)
          - \ ``WebMvcConfigurer``\ の\ ``getValidator``\ メソッドをOverrideし、(1)で定義したBeanを返却する。
        * - | (6)
          - \ (4)と同様である。

  .. group-tab:: XML Config

    * Bean定義

      \ ``xxx-domain.xml``\ 

      .. code-block:: xml

        <!-- (1) -->
        <bean id="validator" class="org.springframework.validation.beanvalidation.LocalValidatorFactoryBean">
            <property name="validationMessageSource">
                <!-- (2) -->
                <bean class="org.springframework.context.support.ResourceBundleMessageSource">
                    <property name="basenames">
                        <list>
                            <value>ValidationMessages</value> <!-- (3) -->
                        </list>
                    </property>
                    <property name="defaultEncoding" value="UTF-8" />
                </bean>
            </property>
        </bean>
    
        <!-- (4) -->
        <bean class="org.springframework.validation.beanvalidation.MethodValidationPostProcessor">
            <property name="validator" ref="validator" />
        </bean>
    
      \ ``spring-mvc.xml``\ 
    
      .. code-block:: xml
    
        <!-- (5) -->
        <mvc:annotation-driven validator="validator">
            <!-- ommited -->
        </mvc:annotation-driven>
    
        <!-- (6) -->
        <bean class="org.springframework.validation.beanvalidation.MethodValidationPostProcessor">
            <property name="validator" ref="validator" />
        </bean>
    
      .. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
      .. list-table::
        :header-rows: 1
        :widths: 10 90
    
        * - 項番
          - 説明
        * - | (1)
          - \ ``LocalValidatorFactoryBean``\ をBean定義する。
        * - | (2)
          - \ ``MessageSource``\ の定義。ここでは\ ``ResourceBundleMessageSource``\ を使用する。
        * - | (3)
          - \ ``ApplicationContext``\ に読み込ませるリソースバンドルを指定する。
        * - | (4)
          - | \ :ref:`ValidationMethodValidation`\ を利用する際には、\ ``MethodValidationPostProcessor``\ の\ ``validator``\ プロパティに(1)で定義したBeanを指定する。  
            | Method Validationを利用しない場合、このBean定義は不要である。
        * - | (5)
          - \ ``<mvc:annotation-driven>``\ 要素の\ ``validator``\ 属性に、(1)で定義したBeanを指定する。
        * - | (6)
          - \ (4)と同様である。

.. note::

  \ ``MessageSource``\ の機能を利用することで、プロパティファイルの配置先がクラスパス直下に制限されなくなる。また、複数のプロパティファイルを指定することもできるようになる。

|

.. _ValidationOsCommandInjection:

OSコマンドインジェクション対策
--------------------------------------------------------------------------------

ここでは、セキュリティ脆弱性の一種であるOSコマンドインジェクションとその対策について説明する。

|

OSコマンドインジェクションとは
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

OSコマンドインジェクションとは、アプリケーション内でユーザー入力文字列からコマンド実行文字列を組み立てている箇所がある場合に、ユーザー入力文字列の中に悪意のあるコマンドが送り込まれると、コンピュータを不正に操られてしまう問題である。

.. tip::

  詳細は、OWASPの\ :url_owasp_community:`解説ページ </attacks/Command_Injection>`\ などを参照されたい。

Javaでは\ ``ProcessBuilder``\ クラスや、\ ``Runtime``\ クラスの\ ``exec``\ メソッドを用いてコマンドを実行する際に、実行するコマンドとして以下のものを利用する場合に、OSコマンドインジェクションが発生する可能性がある。

* \ ``/bin/sh``\ （Unix系の場合）や\ ``cmd.exe``\ （Windowsの場合）
* ユーザーが入力した文字列

以下では、\ ``/bin/sh``\ を利用する場合にOSコマンドインジェクションが発生する例を示す。

.. code-block:: java

  ProcessBuilder pb = new ProcessBuilder("/bin/sh", "-c", script); // (1)
  Process p = pb.start();

.. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
.. list-table::
  :header-rows: 1
  :widths: 10 90

  * - 項番
    - 説明
  * - | (1)
    - | 例えば、\ ``script``\ に"exec.sh ; cat /etc/passwd" が入ると、文字列中のセミコロンが\ ``/bin/sh``\ により区切り文字として解釈され、"cat /etc/passwd"が実行される。
      | そのため、標準出力の扱い方によっては\ ``/etc/passwd``\ が出力される可能性がある。

.. warning:: **ScriptEngineやScriptTemplateViewResolverの利用について**

  Java SE 6より追加された\ ``ScriptEngine``\ や、Spring Framework 4.2より追加された\ ``ScriptTemplateViewResolver``\ では、JVM上で別言語（\ ``Ruby``\ や\ ``Python``\ など）を使用することができる。

  これらの機能を利用して別言語のコードを実行する場合、コードの書き方によってはOSコマンドインジェクションが発生する可能性があるため、利用には十分注意すること。

|

対策方法
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

OSコマンドインジェクションを起こさないためには、可能な限り外部プロセスの実行を避ける。ただし諸般の事情により外部プロセスの実行がどうしても必要な場合、以下の対策を行った上で外部プロセス実行を実装すること。

* 極力、\ ``/bin/sh``\ （Unix系の場合）や\ ``cmd.exe``\ （Windowsの場合）を使用したコマンド実行を行わない
* ユーザーにより入力された文字が、アプリケーションとして許可されたものであるか、ホワイトリスト方式を用いてチェックする

以下では、ユーザーが入力したコマンドと引数が指定された文字列で構成されているかをホワイトリスト方式でチェックするルールの例を示す。

.. code-block:: java

  @Pattern(regexp = "batch0\\d\\.sh") // (1)
  private String cmdStr;

  @Pattern(regexp = "[\\w=_]+")  // (2)
  private String arg;

.. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
.. list-table::
  :header-rows: 1
  :widths: 10 90

  * - 項番
    - 説明
  * - | (1)
    - | コマンドとして \ ``batch0X.sh``\ （Xは0から9までの半角数字）のみ許可するルールを指定する。
  * - | (2)
    - | 引数として、無害な文字である半角英数字（\\w）、"\ ``=``\ "、"\ ``_``\ "から構成された文字列のみ許可するルールを指定する。

.. note::

  この例では、コマンドや引数にパスが含まれないようなルールとすることで、ディレクトリトラバーサルを起こさないようにしている。
      
\ ``@Pattern``\ を利用する場合、\ ``@Pattern``\ に指定された正規表現がそのままエラーメッセージとして出力され、以下の点でメッセージとしては不適切である。

* エラーの意味が不明確となり、ユーザに優しくない
* 脆弱性への対策のためのロジックが利用者に露呈してしまう

.. figure:: ./images_Validation/validations-os-command-injection.png
  :width: 60%

エラーの意味を明確にし、かつ、ロジックを隠蔽するために、application-messages.propertiesに適切なメッセージを定義する。メッセージの定義方法については、\ :ref:`ValidationMessageInApplicationMessages`\ を参照されたい。

.. code-block:: properties

  Pattern.cmdForm.cmdStr = permit command name: batch00.sh - batch09.sh
  Pattern.cmdForm.arg = permit parameter characters and symbols: alphanumeric, =, _

.. figure:: ./images_Validation/validations-os-command-injection2.png
  :width: 60%

|

.. _ValidationWhenAddingRemovingInputFieldsUsingJavaScript:

入力フィールドの追加/削除をJavaScriptで実行する場合
--------------------------------------------------------------------------------

\ :ref:`ValidationNestedBeanSingleItemCheck`\ のコレクションに対するバリデーションの場合について、add/removeボタンを押下してAddress入力フィールドを追加/削除する処理を、サーバサイドではなくJavaScriptで実行した場合のコード例を以下に示す。

* Controllerクラス

  \ :ref:`ValidationNestedBeanSingleItemCheck`\ にある\ ``UserController``\ から\ ``handleAdd``\ メソッドと\ ``handleRemove``\ メソッドを削除する。

* View

  .. tabs::
    .. group-tab:: JSP

      .. code-block:: jsp

        <!DOCTYPE html>
        <html>
        <%-- WEB-INF/views/user/createForm.jsp --%>
        <head>
            <%-- omitted --%>
            <script type="text/javascript" src="${pageContext.request.contextPath}/webjars/jquery/jquery.min.js"></script>
            <script src="${pageContext.request.contextPath}/webjars/bootstrap/js/bootstrap.min.js"></script>
            <script type="text/javascript" src="${pageContext.request.contextPath}/resources/app/js/AddressesView.js"></script> <%-- (1) --%>
        </head>
        <body>
            <form:form method="post" action="${pageContext.request.contextPath}/user/create" modelAttribute="userForm" class="form-horizontal">
                <%-- omitted --%>
                <c:forEach items="${ userForm.addresses }" varStatus="status">
                    <fieldset class="address">
                        <%-- omitted --%>
                        <c:if test="${ status.index > 0 }">
                            <div class="form-group">
                                <div class="col-sm-offset-2 col-sm-10">
                                    <form:button id="remove${ status.index }" name="remove" data-action="remove-address" class="btn btn-default">remove</form:button> <%-- (2) --%>
                                </div>
                            </div>
                        </c:if>
                    </fieldset>
                    <br>
                </c:forEach>
                <div class="form-group">
                    <div class="col-sm-offset-2 col-sm-10">
                        <form:button id="add" name="add" data-action="add-address" class="btn btn-default">add</form:button> <%-- (3) --%>
                    </div>
                </div>
                <%-- omitted --%>
            </form:form>
        </body>
        </html>

      .. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
      .. list-table::
        :header-rows: 1
        :widths: 10 90

        * - 項番
          - 説明
        * - | (1)
          - | 使用するJavaScriptファイルを読み込んでいる。
        * - | (2)
          - | カスタムデータ属性（\ ``data-action``\ ）を設定することでremoveボタン押下時にJavaScriptの\ ``removeAddress``\ が実行される。
        * - | (3)
          - | カスタムデータ属性（\ ``data-action``\ ）を設定することでaddボタン押下時にJavaScriptの\ ``addAddress``\ が実行される。

    .. group-tab:: Thymeleaf

      .. code-block:: html

        <!DOCTYPE html>
        <html xmlns:th="http://www.thymeleaf.org">
        <!--/* WEB-INF/views/user/createForm.html */-->
        <head>
            <!-- omitted -->
            <script type="text/javascript" th:src="@{/webjars/jquery/jquery.min.js}"></script>
            <script th:src="@{/webjars/bootstrap/js/bootstrap.min.js}"></script>
            <script type="text/javascript" th:src="@{/resources/app/js/AddressesView.js"></script> <!-- (1) -->
        </head>
        <body>
            <form method="post" th:action="@{/user/create}" th:object="${userForm}" class="form-horizontal">
                <!-- omitted -->
                <div th:each="addresses,status : ${userForm.addresses}">
                    <fieldset class="address">
                        <!-- omitted -->
                        <div th:if="${status.index > 0}">
                            <div class="form-group">
                                <div class="col-sm-offset-2 col-sm-10">
                                    <button th:id="'remove'+${status.index}" name="remove" data-action="remove-address" class="btn btn-default" type="submit" value="Submit">remove</button> <!-- (2) -->
                                </div>
                            </div>
                        </div>
                    </fieldset>
                    <br>
                </div>
                <div class="form-group">
                    <div class="col-sm-offset-2 col-sm-10">
                        <button id="add" name="add" data-action="add-address" class="btn btn-default" type="submit" value="Submit">add</button> <!-- (3) -->
                    </div>
                </div>
                <!-- omitted -->
            </form>
        </body>
        </html>

      .. tabularcolumns:: |p{0.10\linewidth}|p{0.90\linewidth}|
      .. list-table::
        :header-rows: 1
        :widths: 10 90

        * - 項番
          - 説明
        * - | (1)
          - | 使用するJavaScriptファイルを読み込んでいる。
        * - | (2)
          - | カスタムデータ属性（\ ``data-action``\ ）を設定することでremoveボタン押下時にJavaScriptの\ ``removeAddress``\ が実行される。
        * - | (3)
          - | カスタムデータ属性（\ ``data-action``\ ）を設定することでaddボタン押下時にJavaScriptの\ ``addAddress``\ が実行される。

* JavaScript

  .. code-block:: javascript

    // webapp/resources/app/js/AddressesView.js

    function addressTemplate(number) {
        return `
    <fieldset class="address">
        <legend id="Address${number}">Address${number + 1}</legend>
        <div class="form-group">
            <label for="addresses${number}.userName" class="col-sm-2 control-label">UserName</label>
            <div class="col-sm-10">
                <input id="addresses${number}.userName" name="addresses[${number}].userName" placeholder="UserName" class="form-control" type="text" />
            </div>
        </div>
        <div class="form-group">
            <label for="addresses${number}.postCode" class="col-sm-2 control-label">PostCode</label>
            <div class="col-sm-10">
                <input id="addresses${number}.postCode" name="addresses[${number}].postCode" placeholder="PostCode" class="form-control" type="text" />
            </div>
        </div>
        <div class="form-group">
            <label for="addresses${number}.address" class="col-sm-2 control-label">Address</label>
            <div class="col-sm-10">
                <input id="addresses${number}.address" name="addresses[${number}].address" placeholder="Address" class="form-control" type="text" />
            </div>
        </div>
        <div class="form-group">
            <div class="col-sm-offset-2 col-sm-10">
                <button id="remove${number}" data-action="remove-address" class="btn btn-default">remove</button>
            </div>
        </div>
    </fieldset>
    <br />
    `;
    }

    class AddressesView {
        constructor() {
            this.addressSize = $("fieldset.address").length;
        }

        addAddress() {
            const newHtml = addressTemplate(this.addressSize);
            const $lastFieldset = $("fieldset.address").last();

            if ($lastFieldset.length > 0) {
                // Insert after the last <br>
                $lastFieldset.next("br").after($(newHtml));
            } else {
                // If no fieldset exists, console a warning
                console.warn("No existing fieldset found");
            }

            this.addressSize++;
        }

        removeAddress($fieldset) {
            $fieldset.next().remove(); // remove <br>
            $fieldset.remove(); // remove <fieldset>
            this.addressSize = $("fieldset.address").length; // Update size after removal

            // Reindex all fieldsets after removal
            this.reindexAddresses();
        }

        reindexAddresses() {
            $("fieldset.address").each(function (index) {
                const $fieldset = $(this);

                // Update legend text and id
                $fieldset
                    .find("legend")
                    .text(`Address${index + 1}`)
                    .attr("id", `Address${index}`);

                // Update id, name, and for attributes for each input field
                // UserName
                $fieldset.find(`input[name^="addresses"][name$=".userName"]`).attr({
                    id: `addresses${index}.userName`,
                    name: `addresses[${index}].userName`,
                });
                $fieldset.find(`label[for^="addresses"][for$=".userName"]`).attr("for", `addresses${index}.userName`);

                // PostCode
                $fieldset.find(`input[name^="addresses"][name$=".postCode"]`).attr({
                    id: `addresses${index}.postCode`,
                    name: `addresses[${index}].postCode`,
                });
                $fieldset.find(`label[for^="addresses"][for$=".postCode"]`).attr("for", `addresses${index}.postCode`);

                // Address
                $fieldset.find(`input[name^="addresses"][name$=".address"]`).attr({
                    id: `addresses${index}.address`,
                    name: `addresses[${index}].address`,
                });
                $fieldset.find(`label[for^="addresses"][for$=".address"]`).attr("for", `addresses${index}.address`);

                // Remove button
                $fieldset.find('button[data-action="remove-address"]').attr("id", `remove${index}`);
            });
        }
    }

    $(function () {
        const addressesView = new AddressesView();

        $('[data-action="add-address"]').click(function (e) {
            e.preventDefault();
            addressesView.addAddress();
        });

        // Use event delegation to handle dynamically added elements as well
        $(document).on("click", '[data-action="remove-address"]', function (e) {
            e.preventDefault();

            const $this = $(this); // this button
            const $fieldset = $this.closest("fieldset.address"); // Get the closest fieldset

            if ($fieldset.length > 0) {
                addressesView.removeAddress($fieldset);
            } else {
                console.error("Could not find parent fieldset");
            }
        });
    });

.. raw:: latex

  \newpage