リクエストパラメータとフォーム
readingParameters() は、サーブレットリクエストや送信されたフォームが提供する文字列のフラットな Map を、Map や JSON 文書を読むのと同じスキーマで読み取ります。文字列はプロパティの型の値を表すテキストであり、キーはネストした値のパスです。
record SearchForm(String q, Integer page, Boolean includeArchived, @Nullable LocalDate since, List<String> tags,
@Nullable Address address) {}
ValueValidator<Map<String, ?>, SearchForm> searchFormValidator = Yavi.schema()
._string("q", c -> c.notBlank())
._integer("page", c -> c.greaterThanOrEqual(1)).defaultValue(1)
._boolean("includeArchived").defaultValue(false)
._localDate("since").nullable()
._list("tags", Yavi._string(c -> c.notBlank())).defaultValue(List.of())
._object("address", addressValidator).nullable()
.fromMap(SearchForm::new)
.readingParameters();
// ?q=yavi&page=2&since=&tags=a&tags=b&address.city=Tokyo
Validated<SearchForm> validated = searchFormValidator.validate(params);
このような Map のすべての形式を受け付けます。Map<String, String>、Spring の MultiValueMap のような Map<String, List<String>>、Servlet API の Map<String, String[]> です。代入先に関係なく型は ValueValidator<Map<String, ?>, X> です。
キーとパス
address.cityとaddress[city]はオブジェクトaddressのプロパティcityです。tags[]はtagsです。- 複数の値を持つキーはリストです(
tags=a&tags=b)。スカラーのプロパティに複数の値があるとobject.typeで報告され、どれも選ばれません。 - インデックス付きのキーはインデックスの順のリストです(
items[0].name=pen&items[1].name=ink)。 - 飛ばされたインデックスは
nullの要素になるため、違反は送られたインデックスを保ちます(items[2].name)。 - ドットを含む名前はブラケットで書きます(
scores[a.b])。 - 値とネストしたキーの両方を持つキー(
a=1&a.b=2)はobject.typeで報告され、パスとして書かれていないキー(a..b、a[0)はどのプロパティにも一致しません。 rejectingUnknownProperties()を指定すると、未知のキーはそれを持つオブジェクトのバリデータが報告します(address.zip)。
変換と StringCoercion
デフォルトのルールは厳格です。
- 数値は
new BigDecimal(String)の文法の十進数です。任意の符号、数字、任意の小数部、任意の指数を含み、前後の空白や桁区切りはありません。"30"と"30.0"はIntegerで、"30.5"、" 30"、"1,000"はそうではありません。 - 真偽値は
"true"または"false"です。 - 型を表さない文字列は例外ではなく
object.type("page" must be of type integer)で報告されます。文字列への変換は行われません。
StringCoercion は、フォームのフィールドなど人が書いたテキストのためにルールを緩めます。
StringCoercion form = StringCoercion.strict().trimming().booleanWords();
ValueValidator<Map<String, ?>, Signup> signupValidator = Yavi.schema()
._integer("age")
._boolean("subscribed").defaultValue(false) // an unchecked checkbox sends nothing
.fromMap(Signup::new)
.readingParameters(form);
signupValidator.validate(Map.of("age", " 30 ", "subscribed", "on")); // Signup[age=30, subscribed=true]
trimming()はプロパティの型に関係なくすべてのテキストを前後の空白なしで読み取り、空白だけの文字列をnullとして検証します。制約はトリムされたテキストを見ます。booleanWords()はtrue、1、yes、onとfalse、0、no、offを大文字小文字を問わず受け付けます。booleanWords(trueWords, falseWords)はアプリケーションの語を取ります。- パスワードのように空白が値の一部である
Stringは、そのバリデータのuntrimmed()でそう示します(._string(Yavi._string("password", c -> c.greaterThanOrEqual(8)).untrimmed()))。 - 各ルールは一度だけ与えます。
reader.coercingStrings(rules).coercingStrings()とbooleanWords(...).booleanWords()はコンパイルできません。 - バリデータは最後に与えられたリーダーで読み取ります。
readingParameters()の後のreadingWith(reader)は文字列を変換しません。
空の値と既定値
- 空文字列はプロパティの型に関係なく
nullとして検証されます。optional()、nullable()、defaultValue(...)が適用されます。""を受け取る必要がある文字列プロパティにはdefaultValue("")を与えます。 - テキストに
nullはないため、空文字列をobject.notNullで拒否するプロパティは、存在しないキーと同様にobject.required("page" is required)を報告します。notBlank()のようにnullを拒否する制約の違反はそのまま報告されます。 - 空のリストやオブジェクトは送信できません。キーが存在しない状態になり、
nullとして検証されます。チェックボックスのよう空でありうるリストにはdefaultValue(List.of())を与えます。 recoverはリクエストを失敗させてはならないパラメータに適しています(._integer("size", c -> c.greaterThanOrEqual(1).lessThanOrEqual(100)).recover(20))。
ラベルとメッセージ
フォームはフィールドをラベルで呼びます。label はプロパティとその要素のすべてのメッセージの {0} を変更します。違反の名前、パス、ポインタは変わりません。typeMessage は object.type のメッセージを、required は object.required のメッセージを置き換えます。
record Token(String name, Integer ttl, List<String> roles) {}
ValueValidator<Map<String, ?>, Token> tokenValidator = Yavi.schema()
._string("name", c -> c.notBlank()).label("Token name")
._integer("ttl", c -> c.positive()).typeMessage("\"{0}\" must be a number of seconds")
._list("roles", Yavi._string(c -> c.notBlank())).label("Roles").required("Select at least one role")
.fromMap(Token::new)
.readingParameters()
.formattingWith(new MessageSourceMessageFormatter(messageSource::getMessage));
フォーマッターと、コードに書いたメッセージに関するルールはメッセージとローカライズを参照してください。
1 つのパラメータのリスト
_list の後の splitBy は 1 つのパラメータをリストとして読み取ります。?tags=java,yavi、?ids=1,2,3、または textarea の行ごとの URI です。
ValueValidator<Map<String, ?>, Article> articleValidator = Yavi.schema()
._string("title", c -> c.notBlank())
._list("tags", Yavi._string(c -> c.notBlank().lessThanOrEqual(10)), c -> c.unique()).splitBy(",")
._list("related", Yavi._integer(c -> c.positive())).splitBy(",").defaultValue(List.of())
._list("links", Yavi._object(URI.class)).splitBy(Pattern.compile("\\R")).defaultValue(List.of())
.fromMap(Article::new)
.readingParameters();
- 区切りはリテラルのテキストか
Patternです。要素は値を表すテキストであり、違反はそのインデックスの下(tags[1])に置かれます。 - すべてのテキストが分割されます。繰り返しキーの値も同様で、
tags=a,b&tags=cは[a, b, c]です。 - 要素は削除もトリムもされません。
a,,bは 3 つの要素を持ち、2 番目は値を持ちません。末尾の区切りは要素を開始しません。a,b,は[a, b]です。 - 空のパラメータ(
tags=)は値を持ちません。 splitByは_listの後、他の修飾子の前に書きます。その前に書けるのはlabelとtypeMessageだけです。- テキストでもリストでもない値は
object.type("tags" must be of type array or string)で報告され、1 要素のリストとはみなされません。
制限と安全性
- インデックスは最大 255(
ParameterTree.DEFAULT_MAX_INDEX)です。それより大きい数値は名前になるため、tags[999999999]はobject.typeで報告され、何も確保しません。 ParameterTree.of(map, maxIndex)は別の制限を与えます。バリデータが別の制限でツリーを読む場合は、リーダーにも同じ制限を与えます。- 飛ばされたインデックスは
nullの要素です。リストは送信された最大インデックスの長さになるため、制限は信頼できないリクエストが確保できる量を制限します。 - パスでないキーはどのプロパティにも一致せず無視されるか、
rejectingUnknownProperties()により報告されます。 readingParameters()は Map のParameterTreeを検証します。任意のバリデータはreadingWith(ParameterTree.reader())でそれを読み取れます。
パラメータの書き戻し
有効でないフォームは、フィールドを手でコピーすることなく、送信されたテキストで再表示されます。ParameterTree はスキーマの形でパラメータを返し、パラメータを欠くリクエストにも同じ呼び出しで空のフォームを返します。オブジェクトの書き戻しを参照してください。