Light Servlet Validator Plugin
0.2

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

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以外の型で受け取る

Validatorプラグインを利用すると、リクエストパラメータをString以外の型で受け取ることが可能です。

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

この場合、リクエストパラメータfooが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プラグインは、バリデーションエラーメッセージをリソースバンドルとして読み込みます。 ルールに従ってリソースバンドルファイルを作成することでエラーメッセージをカスタマイズできます。 リソースバンドルを作成する際のルールは、以下のとおりです。

リソースバンドルファイルに記述する内容は以下の通りです。すべてのキーを記述しなくても構いません。 ファイルに記述されていないキーについては、デフォルトのメッセージが適用されます。 プレースホルダを記述すると、下表の「プレースホルダ」欄に示す内容に置換されます。プレースホルダの書式など、 メッセージの記述方法は、java.text.MessageFormatの仕様に従います。

キー 内容 プレースホルダ
message.error.alphabet_or_number AlphabetOrNumberルール違反のメッセージ {0}:パラメータの値
message.error.decimal_max.allow_equiv DecimalMaxルール違反のメッセージ(allowEquiv要素がtrueの場合) {0}:パラメータの値
{1}:指定した最大値
message.error.decimal_max.not_allow_equiv DecimalMaxルール違反のメッセージ(allowEquiv要素がfalseの場合) {0}:パラメータの値
{1}:指定した最大値
message.error.decimal_min.allow_equiv DecimalMinルール違反のメッセージ(allowEquiv要素がtrueの場合) {0}:パラメータの値
{1}:指定した最小値
message.error.decimal_min.not_allow_equiv DecimalMinルール違反のメッセージ(allowEquiv要素がfalseの場合) {0}:パラメータの値
{1}:指定した最小値
message.error.length Lengthルール違反のメッセージ(最大値・最小値とも指定した場合) {0}:パラメータの値
{1}:指定した最小値
{2}:指定した最大値
message.error.length.min Lengthルール違反のメッセージ(最小値のみ指定した場合) {0}:パラメータの値
{1}:指定した最小値
{2}:最大値(デフォルト値)
message.error.length.max Lengthルール違反のメッセージ(最大値のみ指定した場合) {0}:パラメータの値
{1}:最小値(デフォルト値)
{2}:指定した最大値
message.error.max_digits MaxDigitsルール違反のメッセージ {0}:パラメータの値
{1}:指定した整数部桁数
{2}:指定した少数部桁数
message.error.max_digits.integer MaxDigitsルール違反のメッセージ(整数部のみ指定した場合) {0}:パラメータの値
{1}:指定した整数部桁数
{2}:少数部桁数(デフォルト値)
message.error.max_digits.fraction MaxDigitsルール違反のメッセージ(小数部のみ指定した場合) {0}:パラメータの値
{1}:整数部桁数(デフォルト値)
{2}:指定した少数部桁数
message.error.max.allow_equiv Maxルール違反のメッセージ(allowEquiv要素がtrueの場合) {0}:パラメータの値
{1}:指定した最大値
message.error.max.not_allow_equiv Maxルール違反のメッセージ(allowEquiv要素がfalseの場合) {0}:パラメータの値
{1}:指定した最大値
message.error.min.allow_equiv Minルール違反のメッセージ(allowEquiv要素がtrueの場合) {0}:パラメータの値
{1}:指定した最小値
message.error.min.not_allow_equiv Minルール違反のメッセージ(allowEquiv要素がfalseの場合) {0}:パラメータの値
{1}:指定した最小値
message.error.not_empty NotEmptyルール違反のメッセージ {0}:パラメータの値
message.error.not_null NotNullルール違反のメッセージ {0}:パラメータの値
message.error.regexp_pattern RegexpPatternルール違反のメッセージ {0}:パラメータの値
{1}:指定した正規表現パターン
message.error.type.integer パラメータをintまたはInteger型に変換できない場合のメッセージ {0}:パラメータの値
message.error.type.long パラメータをlonまたはLong型に変換できない場合のメッセージ {0}:パラメータの値
message.error.type.float パラメータをfloatまたはFloat型に変換できない場合のメッセージ {0}:パラメータの値
message.error.type.double パラメータをdoubleまたはDouble型に変換できない場合のメッセージ {0}:パラメータの値
message.error.type.big_decimal パラメータをBigDecimal型に変換できない場合のメッセージ {0}:パラメータの値
message.error.type.date パラメータをDate型に変換できない場合のメッセージ {0}:パラメータの値
{1}:日付フォーマット
message.item_name 項目名が指定された場合に、メッセージの先頭に付加される文(詳細は後述) {0}:項目名
上記以外の任意のキー バリデーションルールアノテーションのmessage要素、 または@ItemNameアノテーションのvalue要素でキーを指定した場合に適用される(詳細は後述) バリデーションルールアノテーションの場合は上記の各ルールに従う。@ItemNameの場合はプレースホルダは無効。
バリデーションルールアノテーションのmessage要素にメッセージを指定する

バリデーションルールアノテーションには、message要素を指定することができます。

message要素には、プレースホルダを含むメッセージそのもの、または、リソースバンドルに記述された 任意のキーを指定することができます。 メッセージを指定する場合は、以下のように記述します。メッセージは、リソースバンドルに記述する場合と同様、 javax.text.MessageFormatの仕様に従って記述します。

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

上記のアノテーションによる検査でバリデーションエラーが発生した場合は、 message要素で指定したバリデーションエラーメッセージが適用されます。 このとき、もしバリデーションエラーメッセージリソースファイルにメッセージが定義されていても無視されます。

message要素には、以下の書式で、バリデーションエラーメッセージリソースファイルに記述されるキーを指定することもできます。

@AlphabetOrNumber(message="{my.app.message.alphabet_or_number}")

このように、message要素の文字列全体が{}で囲まれている場合、その内部の文字列がメッセージリソースのキーと判断され、 該当するメッセージがバリデーションエラーメッセージリソースファイルから読み込まれます。 この書式は、メッセージを国際化する場合に便利です。

項目名の指定

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

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

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

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

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

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

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

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

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

@ItemName("{my.app.itemname}")

このように、指定する項目名の文字列全体が{}で囲まれている場合、その文字列がメッセージリソースのキーと判断され、 該当するメッセージがバリデーションエラーメッセージリソースファイルから読み込まれます。 この書式は、メッセージを国際化する場合に便利です。

バリデーションエラーのデフォルトメッセージ

バリデーションエラー時のデフォルトのメッセージは以下の通りです。デフォルトメッセージは日本語のみ用意されています。

キー デフォルトメッセージ
message.error.alphabet_or_number '{0}'は不正です。半角英数字でなければなりません。
message.error.decimal_max.allow_equiv '{0}'は不正です。{1}以下でなければなりません。
message.error.decimal_max.not_allow_equiv '{0}'は不正です。{1}より小さい値でなければなりません。
message.error.decimal_min.allow_equiv '{0}'は不正です。{1}以上でなければなりません。
message.error.decimal_min.not_allow_equiv '{0}'は不正です。{1}より大きい値でなければなりません。
message.error.length '{0}'は不正です。{1}文字以上{2}文字以下でなければなりません。
message.error.length.min '{0}'は不正です。{1}文字以上でなければなりません。
message.error.length.max '{0}'は不正です。{2}文字以下でなければなりません。
message.error.max_digits '{0}'は不正です。整数部は{1}桁以下、小数部は{2}桁以下でなければなりません。
message.error.max_digits.integer '{0}'は不正です。整数部は{1}桁以下でなければなりません。
message.error.max_digits.fraction '{0}'は不正です。小数部は{2}桁以下でなければなりません。
message.error.max.allow_equiv '{0}'は不正です。{1}以下でなければなりません。
message.error.max.not_allow_equiv '{0}'は不正です。{1}より小さい値でなければなりません。
message.error.min.allow_equiv '{0}'は不正です。{1}以上でなければなりません。
message.error.min.not_allow_equiv '{0}'は不正です。{1}より大きい値でなければなりません。
message.error.not_empty この項目は必ず入力してください。
message.error.not_null この項目は必ず入力してください。
message.error.regexp_pattern '{0}'は不正です。
message.error.type.integer '{0}'は正しい整数ではありません。
message.error.type.long '{0}'は正しい整数ではありません。
message.error.type.float '{0}'は正しい数値ではありません。
message.error.type.double '{0}'は正しい数値ではありません。
message.error.type.big_decimal '{0}'は正しい数値ではありません。
message.error.type.date '{0}'は正しい数値ではありません。
message.item_name {0}に誤りがあります。

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

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

  1. HTTPサービスメソッドの引数またはJavaBeanのフィールドに指定するアノテーションを作成します。アノテーションには、 バリデーションルールの内容を端的に示すような名前をつけます。メタアノテーションとして、最低限下記のものを指定する必要があります。
  2. 入力値の検査およびエラーメッセージの生成を行うクラスを作成します。 このクラスは、ValidationRuleインターフェースを実装します。 なお、Validatorプラグインが標準で提供するバリデーションルールアノテーションには、前述のとおり、 すべてmessage要素が定義されていますが、カスタムバリデーションルールで、 message要素を使ったメッセージ指定の機能を実現したい場合は、 ValidationRule.getMessage(MessageResource, String, Annotation)メソッドで 目的の処理を実装する必要があります。(Validatorプラグインが自動的にmessage要素を読み込むわけではありません。)
  3. 必要に応じて、バリデーションエラー時のメッセージとキーをリソースバンドルファイルに登録します。

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.2