|
Light Servlet Validator Plugin 0.3 |
||||||||
前 次 | フレームあり フレームなし |
参照先:
説明
パッケージ | |
---|---|
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; ... }
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メソッドがバリデーションエラー応答メソッドとして実行されます。
バリデーションエラー応答メソッドは、以下のルールで実装します。
ValidationErrors
、
java.lang.Object[]、javax.servlet.http.HttpServletRequest、javax.servlet.http.HttpServletResponse、javax.servlet.ServletConfigです。
引数の順序は任意です。また、引数がなくてもかまいません。
ValidationErrors
は、ValidationError
のコレクションです。
ValidationError
には、バリデーションエラーが発生した項目や、エラーメッセージが含まれます。
Object[]を引数とした場合、サービスメソッドが受け取る予定だった引数の配列が渡されます。ただし、バリデーションエラーとなった値については
Object[]配列に格納されず、代わりにnullが格納されます。
バリデーションエラー応答クラスは、バリデーションエラー応答メソッドが指定されていない場合に、デフォルトの応答処理として エラー応答処理を行うクラスです。アプリケーション内で一つだけ定義することができます。
バリデーションエラー時に応答を行うためのクラスを定義します。このクラスは、
ValidationErrorResponse
インターフェースを実装します。
responseValidationErrorメソッドがエラー応答を送信します。応答の送信方法は、HTTPサービスメソッドと同様です。
アプリケーションの初期化時に、このクラスのインスタンスを生成し、
ValidatorConfig
オブジェクトに格納します。ValidatorConfig
は、Config#addOptionalConfigメソッドでConfigオブジェクトにセットする必要があります。
上記で説明したバリデーションエラー応答メソッド、バリデーションエラー応答クラスのいずれも指定されていない場合は、
ValidatorプラグインはValidationException
をthrowします。
バリデーションエラーが発生すると、ValidationError
オブジェクトが生成され、
アプリケーション利用者向けのエラーメッセージが格納されます。エラーメッセージはデフォルトで用意されていますが、
カスタマイズすることもできます。
以下では、バリデーションエラーメッセージをカスタマイズする方法や、デフォルトメッセージについて解説します。
Validatorプラグインは、バリデーションエラーメッセージをリソースバンドルとして読み込みます。 ルールに従ってリソースバンドルファイルを作成することでエラーメッセージをカスタマイズできます。 リソースバンドルを作成する際のルールは、以下のとおりです。
Validatorプラグイン設定オブジェクト
を生成し、
ValidatorConfig.setMessageBundleName(String)
でリソースバンドル名を指定する。
(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要素には、プレースホルダを含むメッセージそのもの、または、リソースバンドルに記述された 任意のキーを指定することができます。 メッセージを指定する場合は、以下のように記述します。メッセージは、リソースバンドルに記述する場合と同様、 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}に誤りがあります。 |
バリデーションルールは自由に作成することができます。カスタムバリデーションルールを作成する手順は以下のようになります。
@ValidationRuleClass
:入力値の検査を行うクラスを指定します。
(後述)
ValidationRule
インターフェースを実装します。
なお、Validatorプラグインが標準で提供するバリデーションルールアノテーションには、前述のとおり、
すべてmessage要素が定義されていますが、カスタムバリデーションルールで、
message要素を使ったメッセージ指定の機能を実現したい場合は、
ValidationRule.getMessage(MessageResource, String, Annotation)
メソッドで
目的の処理を実装する必要があります。(Validatorプラグインが自動的にmessage要素を読み込むわけではありません。)
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.3 |
||||||||
前 次 | フレームあり フレームなし |