Light Servlet Validator Plugin
0.4

Light Servlet Validator Plugin API仕様 バージョン0.4

FlatServe Validatorプラグインは、FlatServeに対してクライアントから送信されたリクエストパラメータのバリデーションを 行うためのプラグインです。

参照先:
          説明

パッケージ
com.small_it_office.flatserve.validator バリデーション機能を利用するためのクラスを提供します。
com.small_it_office.flatserve.validator.rule バリデーションルールに関するパッケージです。

 

FlatServe Validatorプラグインは、FlatServeに対してクライアントから送信されたリクエストパラメータのバリデーションを 行うためのプラグインです。 HTTPサービスメソッドの引数や、引数のJavaBeanのフィールドに対して、バリデーションルールをあらわす アノテーションを記述することで、リクエストパラメータの値が適切かどうかを検査し、ルールに合致しない場合に バリデーションエラーとすることができます。

また、Validatorプラグインを導入すると、リクエストパラメータを数値型や日付型で受け取ることができるようになります。 これは、Validatorプラグインは、アノテーションによるバリデーションルールのほか、 リクエストパラメータが引数の型に合致するかどうかの検査も行うことができるためです。 FlatServe Coreだけでは、パラメータの型をチェックする機能がないため、StringとString配列以外の型でリクエストパラメータを 受け取ることができません。

バリデーションルールの指定方法

引数で受け取るリクエストパラメータのバリデーションを行うには、以下の例のように、 バリデーションルールをあらわすアノテーションを記述します。

@HttpService
public HtmlTextResponse serviceMethod1(@Pram("foo") @AlphabetOrNumber String foo) {
    ...

この例では、fooという名前のリクエストパラメータに対して、 AlphabetOrNumberルールが適用されます。 アルファベットでも数値でもない文字が含まれる場合にバリデーションエラーと判断され、serviceMethod1は実行されません。

引数でJavaBeanを受け取る場合は、JavaBeanのフィールドにアノテーションを記述します。

@HttpService
public HtmlTextResponse serviceMethod2(MyBean myBean) {
    ...
}
public class MyBean {
    @AlphabetOrNumber
    private String foo;
    ...
}

リクエストパラメータをString以外の型で受け取る

FlatServe Coreモジュールだけでは、HTTPサービスメソッドが受け取ることができるリクエストパラメータの引数の型はStringだけですが、 Validatorプラグインを利用すると、数値型など、String以外の型に変換して受け取ることができます。

@HttpService
public HtmlTextResponse serviceMethod3(@Pram("foo") int foo) {
    ...

上記の例の場合、リクエストパラメータfooの値をint型に変換する際に、int型で表現できる書式にしたがっているかどうか、 Validatorプラグインが自動的に検査します。 数値以外の文字が含まれるなど、リクエストパラメータfooがint型として表現できない場合は、バリデーションエラーとなります。

StringやString[]以外でリクエストパラメータを受け取ることができる型は、以下に示すもの、およびその配列型です。

パラメータのフォーマット

パラメータを数値や日付の型で受け取る場合、パラメータのフォーマットを指定することができます。

数値のフォーマット

数値のフォーマットを指定する場合、以下のように@NumberFormat アノテーションを利用します。

public HtmlTextResponse serviceMethod4(@Pram("foo") @NumberFormat("#,##0") int foo) {
    ...

上記の例では、「,」によって3桁に区切られた形式の数値がリクエストパラメータで送信されることを想定しています。

日付のフォーマット

日付のフォーマットを指定する場合、以下のように@DateFormat アノテーションを利用します。

public HtmlTextResponse serviceMethod5(@Pram("foo") @DateFormat("yyyy/MM/dd HH:mm:ss.SSS") Date foo) {
    ...

java.util.Date型でパラメータを受け取る際、@DateFormatアノテーションを 指定していない場合は、デフォルトの日付フォーマット"yyyy-MM-dd"が適用されます。

バリデーションエラー時の応答方法

バリデーションエラーと判断された場合、バリデーションエラーを表す応答をクライアントに返す必要があります。 以下ではその方法について解説します。

バリデーションエラー応答メソッドを利用する

バリデーションエラー発生時に、専用のエラー応答メソッドによって応答を返すことができます。この方法を利用するには、 実行しようとするHTTPサービスクラス内にバリデーションエラー応答メソッドを定義し、 HTTPサービスメソッド側で、@OnValidationError アノテーションによって、バリデーションエラー応答メソッドの名前を記述します。

@HttpService
@OnValidationError("onValidationError")
public HtmlTextResponse serviceMethod6(@Pram("foo") @AlphabetOrNumber String foo) {
    ...
}

//serviceMethod6でバリデーションエラーが発生した場合の応答メソッド
public HtmlTextResponse onValidtionError(ValidationErrors errors) {
    ...
}

上記の例では、serviceMethod6メソッドを実行しようとしてバリデーションエラーが発生した場合に、 onValidationErrorメソッドがバリデーションエラー応答メソッドとして実行されます。

バリデーションエラー応答メソッドは、以下のルールで実装します。

バリデーションエラー応答クラスを利用する

バリデーションエラー応答クラスは、バリデーションエラー応答メソッドが指定されていない場合に、デフォルトの応答処理として エラー応答処理を行うクラスです。アプリケーション内で一つだけ定義することができます。

バリデーションエラー時に応答を行うためのクラスを定義します。このクラスは、 ValidationErrorResponseインターフェースを実装します。 responseValidationErrorメソッドがエラー応答を送信します。応答の送信方法は、HTTPサービスメソッドと同様です。

アプリケーションの初期化時に、このクラスのインスタンスを生成し、 ValidatorConfigオブジェクトに格納します。ValidatorConfig は、Config#addOptionalConfigメソッドでConfigオブジェクトにセットする必要があります。

応答処理が存在しない場合

上記で説明したバリデーションエラー応答メソッド、バリデーションエラー応答クラスのいずれも指定されていない場合は、 ValidatorプラグインはValidationExceptionをthrowします。

エラーメッセージ

バリデーションエラーが発生すると、ValidationErrorオブジェクトが生成され、 アプリケーション利用者向けのエラーメッセージが格納されます。エラーメッセージはデフォルトで用意されていますが、 カスタマイズすることもできます。 以下では、バリデーションエラーメッセージをカスタマイズする方法や、デフォルトメッセージについて解説します。

バリデーションエラーメッセージリソースファイルを作成する

Validatorプラグインは、バリデーションエラーメッセージをリソースバンドルとして読み込みます。このファイルをバリデーションエラーメッセージリソースファイルと呼びます。 エラーメッセージをカスタマイズしたい場合は、リソースバンドルファイルを作成し、カスタマイズしたいバリデーションエラーに対応するキーに対してエラーメッセージを記述します。各バリデーションエラーに対応するリソースバンドルのキーを以下に示します。

バリデーションルール キー
AlphabetOrNumber message.error.alphabet_or_number
DecimalMax message.error.decimal_max
DecimalMin message.error.decimal_min
Length message.error.length
MaxDigits message.error.max_digits
Max message.error.max
Min message.error.min
NotEmpty message.error.not_empty
NotNull message.error.not_null
RegexpPattern message.error.regexp_pattern
パラメータをintまたはInteger型に変換できない場合 message.error.type.integer
パラメータをlonまたはLong型に変換できない場合 message.error.type.long
パラメータをfloatまたはFloat型に変換できない場合 message.error.type.float
パラメータをdoubleまたはDouble型に変換できない場合 message.error.type.double
パラメータをBigDecimal型に変換できない場合 message.error.type.big_decimal
パラメータをDate型に変換できない場合 message.error.type.date
項目名が指定された場合に、メッセージの先頭に付加される文(詳細は後述) message.item_name

バリデーションエラーメッセージリソースファイルには、上記のすべてのキーを記述する必要はありません。カスタマイズしたいメッセージだけを記述することができます。 以下に例を示します。

message.error.length={ErrorValue}は不正です。{min}から{max}までの値を入力してください。

{}で囲まれた部分はプレースホルダであり、以下の要領で文字列が置換されます。プレースホルダを置換した文字列にさらにプレースホルダが 記述されている場合、再帰的に置換処理されます。

プレースホルダの文字列 置換後の文字列
"ErrorValue" バリデーションエラーとなった値
"NumberFormat" 期待する数値フォーマット(該当ルールのみ)
"DateFormat" 期待する日付フォーマット(該当ルールのみ)
アノテーションの要素名 ルールアノテーションの要素で指定した値
メッセージリソースファイルに定義されたキー 定義された値
上記以外 文字列は置換されない

作成したバリデーションエラーメッセージリソースファイルを適用するには、FlatServeの初期化時にリソースバンドル名を設定オブジェクトにセットする必要があります。 Validatorプラグインの設定オブジェクトについて詳細はValidatorプラグインの設定を参照してください。

バリデーションルールアノテーションのmessage要素にメッセージを指定する

com.small_it_office.flatserve.validator.ruleパッケージで提供されるバリデーションルールアノテーションには、message要素を指定することができます。 message要素にはエラーメッセージを記述できます。プレースホルダを指定することも可能です。

@AlphabetOrNumber(message="{ErrorValue}には半角英数字以外の文字が含まれています")

以下の要領で、message要素にバリデーションエラーメッセージリソースファイルに記述されるキーのプレースホルダのみを指定することは、 国際化・地域化が容易となるため良い方法です。

@AlphabetOrNumber(message="{my.app.message.alphabet_or_number}")
項目名の指定

メッセージに出力するための、パラメータの項目名をアノテーションで指定できます。 項目名が指定された場合、エラーメッセージに項目名が明示されるため、 アプリケーション利用者にとってわかりやすいエラーメッセージとすることができます。

項目名の指定は、以下のように@ItemNameアノテーションで行います。 JavaBeanでパラメータを受け取る場合はフィールドに@ItemNameアノテーションを指定します。

public HtmlTextResponse serviceMethod7(@Param("foo") @AlphabetOrNumber @ItemName("テスト項目") String foo){
    ...

このように項目を指定した場合、バリデーションエラー時のメッセージは、デフォルトで以下のようになります。 (ここではパラメータの値を'ABC!'とします)

テスト項目に誤りがあります。'ABC!'は不正です。半角英数字でなければなりません。

もし項目名が指定されていなければ、メッセージは単純に

'ABC!'は不正です。半角英数字でなければなりません。

だけです。このように、項目名を指定すれば、ルール違反のメッセージ(上記の例では「'ABC!'は不正です…」の部分)の前に、 項目名を示す文(上記の例では「テスト項目に誤りがあります。」)が付加されます。 項目名を示す文は、他のエラーメッセージと同様、カスタマイズできます。カスタマイズする場合は、 ルール違反であることを示すメッセージが連結されることを念頭に置き、不自然なメッセージにならないよう配慮する必要があります。

@ItemNameアノテーションは、バリデーションエラーメッセージリソースファイルに記述されるキーをプレースホルダで指定することもできます。 それ以外のプレースホルダは指定できません。

@ItemName("{my.app.itemname}")
バリデーションエラーのデフォルトメッセージ

バリデーションエラー時のデフォルトのメッセージは以下の通りです。このメッセージが定義されたバリデーションエラーメッセージリソースファイルは、 Validatorプラグインのライブラリjarファイル内に含まれます。デフォルトメッセージは日本語のみ用意されています。

キー デフォルトメッセージ
message.error.alphabet_or_number '{ErrorValue}'は不正です。半角英数字でなければなりません。
message.error.decimal_max '{ErrorValue}'は不正です。値が大きすぎるか、または数値ではありません。
message.error.decimal_min '{ErrorValue}'は不正です。値が小さすぎるか、または数値ではありません。
message.error.length '{ErrorValue}'は不正です。文字数が許容範囲ではありません。
message.error.max_digits '{ErrorValue}'は不正です。桁数が許容範囲でないか、または数値ではありません。
message.error.max '{ErrorValue}'は不正です。値が大きすぎるか、または数値ではありません。
message.error.min '{ErrorValue}'は不正です。値が小さすぎるか、または数値ではありません。
message.error.not_empty この項目は必ず入力してください。
message.error.not_null この項目は必ず入力してください。
message.error.regexp_pattern '{ErrorValue}'は不正です。
message.error.type.integer '{0}'は正しい整数ではありません。
message.error.type.long '{ErrorValue}'は正しい整数ではありません。
message.error.type.float '{ErrorValue}'は正しい数値ではありません。
message.error.type.double '{ErrorValue}'は正しい数値ではありません。
message.error.type.big_decimal '{ErrorValue}'は正しい数値ではありません。
message.error.type.date '{ErrorValue}'は正しい日付ではありません。
message.item_name {ErrorValue}に誤りがあります。

カスタムバリデーションルールを作成する方法

バリデーションルールは自由に作成することができます。カスタムバリデーションルールを作成する手順は以下のようになります。

  1. HTTPサービスメソッドの引数またはJavaBeanのフィールドに指定するアノテーションを作成します。アノテーションには、 バリデーションルールの内容を端的に示すような名前をつけます。このアノテーションは、以下に示す要件を満たす必要があります。
  2. 入力値の検査を行うクラスを作成します。 このクラスは、抽象クラスMessageProcessValidationRuleを 継承します。
  3. 必要に応じて、バリデーションエラー時のメッセージをバリデーションエラーメッセージリソースファイルに登録します。

上記の要領で作成したアノテーション、検査クラス、およびバリデーションエラーメッセージリソースファイルに登録するメッセージの例を以下に示します。

//アノテーション
....
import com.small_it_office.flatserve.validator.rule.ValidationRuleClass;

@ValidationRuleClass(AcceptOnlyRule.class)
@Target({ElementType.PARAMETER, ElementType.FIELD })
@Retention(RetentionPolicy.RUNTIME)
public @interface AcceptOnly {
    char[] value();
    String message() default "{message.acceptonly}";
}
//検査クラス
public class AcceptOnlyRule extends MessageProcessValidationRule<AcceptOnly> {
    public boolean isValid(Object value, Object rawValue, AcceptOnly annotation) {
        char[] letters = annotation.value();
        String valueString = rawValue.toString();
        Arrays.sort(letters);
        for(int i = 0; i < valueString.length(); i++) {
            char c = valueString.charAt(i);
            if (Arrays.binarySearch(letters, c) < 0) {
                return false;
            }
        }
        return true;
    }
}
#バリデーションエラーメッセージリソースファイルの定義
message.acceptonly='{ErrorValue}'には、受け入れられない文字が含まれています。

Validatorプラグインの設定

Validatorプラグインの設定は、ValidatorConfigオブジェクトで行います。 このオブジェクトをValidatorプラグイン設定オブジェクトと呼びます。 ApplicationInitializerの初期化処理で、以下のように設定を行います。

public Config init(ServletConfig servletConfig) {
    ValidatorConfig validatorConfig = new ValidatorConfig();
    validatorConfig.setMessageBundleName("my-message");
    validatorConfig.setDefaultErrorResponse(new MyErrorResponse());
    Config config = new Config();
    config.addOptionalConfig(validatorConfig);
    return config;
}

設定可能な項目についての詳細は、APIドキュメントを参照してください。 また、FlatServeの設定方法の基本については、FlatServeコアモジュールのドキュメントを参照してください。

国際化・地域化

Validatorプラグインは、バリデーションエラーメッセージと、ログ出力メッセージおよび例外メッセージを、 リソースバンドルを使って読み込んでいます。デフォルトで提供されているメッセージは日本語のみですが、 各ロケールに対応したリソースバンドルファイルを作成することで地域化することができます。

バリデーションエラーメッセージ

デフォルトのエラーメッセージのリソースバンドル名は、flatserve-vlidation-error-messagesです。 JARファイル内にはflatserve-vlidation-error-messages_ja.propertiesファイルが含まれているため、 日本語のメッセージはそのまま利用可能です。 その他の言語で記述されたバリデーションエラーメッセージのリソースバンドルファイルを、クラスパスが通った ディレクトリに配置することで国際化・地域化できます。 たとえば、バリデーションエラーメッセージを英語化する場合は、flatserve-vlidation-error-messages_en.propertiesを クラスパス上に配置します。実行時に適用されるロケールは、ValidatorConfigで設定します。 指定がない場合は実行環境のデフォルトロケールが適用されます。

また、バリデーションエラーメッセージをカスタマイズする場合は、 バリデーションエラーメッセージリソースファイルを作成するに示した方法でメッセージを作成します。 この場合もリソースバンドルを利用するため、国際化・地域化対応したメッセージを作成することが可能です。

ログ出力メッセージおよび例外メッセージ

ログ出力メッセージおよび例外メッセージのリソースバンドル名は、flatserve-vlidator-messagesです。 JARファイル内にはflatserve-vlidator-messages_ja.propertiesファイルが含まれているため、 日本語のメッセージはそのまま利用可能です。 その他の言語で記述されたメッセージのリソースバンドルファイルを、クラスパスが通った ディレクトリに配置することで国際化・地域化できます。 たとえば、メッセージを英語化する場合は、flatserve-vlidator-messages_en.propertiesをクラスパス上に配置します。 実行時のロケールは、FlatServeコアモジュールの設定オブジェクトによって指定できます。 指定しない場合は、実行環境のデフォルトロケールが適用されます。


Light Servlet Validator Plugin
0.4