|
Light Servlet Validator Plugin 0.4 |
||||||||
前 次 | フレームあり フレームなし |
参照先:
説明
パッケージ | |
---|---|
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; ... }
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メソッドがバリデーションエラー応答メソッドとして実行されます。
バリデーションエラー応答メソッドは、以下のルールで実装します。
ValidationErrors
、
java.lang.Object[]、javax.servlet.http.HttpServletRequest、javax.servlet.http.HttpServletResponse、javax.servlet.ServletConfigです。
引数の順序は任意です。また、引数がなくてもかまいません。
ValidationErrors
は、ValidationError
のコレクションです。
ValidationError
には、バリデーションエラーが発生した項目や、エラーメッセージが含まれます。
Object[]を引数とした場合、HTTPリクエストで送信されたデータの配列が渡されます。この配列は、HTTPサービスメソッドの引数の並び順で格納されます。
引数にない値は格納されません。各要素は引数の型に変換される前の、入力されたままのデータとなります。引数の型がJavaBeanの場合は、
パラメータ名(必ずString型)をキー、入力値を値とするMap型となります。
バリデーションエラー応答クラスは、バリデーションエラー応答メソッドが指定されていない場合に、デフォルトの応答処理として エラー応答処理を行うクラスです。アプリケーション内で一つだけ定義することができます。
バリデーションエラー時に応答を行うためのクラスを定義します。このクラスは、
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プラグインの設定を参照してください。
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}に誤りがあります。 |
バリデーションルールは自由に作成することができます。カスタムバリデーションルールを作成する手順は以下のようになります。
@ValidationRuleClass
で、
入力値の検査を行うクラスを指定します。
(後述)
MessageProcessValidationRule
を
継承します。
上記の要領で作成したアノテーション、検査クラス、およびバリデーションエラーメッセージリソースファイルに登録するメッセージの例を以下に示します。
//アノテーション .... 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プラグインの設定は、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 |
||||||||
前 次 | フレームあり フレームなし |