組み込みの制約

YAVI は対応する型ごとに組み込みの制約を提供します。スキーマスタイルとクラシックスタイルは同じ制約オブジェクトを使うため、各制約はこのページで一度だけ説明します。

次のプログラムは無効な値に email()、ip()、multipleOf(3) を適用し、各違反を出力します。

import am.ik.yavi.builder.ValidatorBuilder;
import am.ik.yavi.core.Validator;
import am.ik.yavi.validator.Yavi;

// Schema style: the validator of a single value
var emailValidator = Yavi._string("email", c -> c.notBlank().email());

// Classic style: a property of an object
record Signup(String email) {}

Validator<Signup> signupValidator = ValidatorBuilder.<Signup>of()
        ._string(Signup::email, "email", c -> c.notBlank().email())
        .build();

ラムダはどちらのスタイルでも同じです。スキーマスタイルでは Yavi.schema()._string("email", c -> ...) とプロパティとして書くこともできます。クラシックスタイルでは、型付きの _string がプロパティの型を選び、型推論の曖昧さを避けます。型を指定しない場合は constraint を使います。

null 値と必須の値

スキーマスタイルとクラシックスタイルでは、null の意味が異なります。

  • Yavi.schema() のプロパティと、Yavi._string(...) で作った単一の値のバリデータは、既定で null を object.notNull で拒否します。null になりうる値は nullable()(または optional()、defaultValue(...)、recover(...))でそれを宣言します。省略と既定値を参照してください。isNull() は nullable() を付けた場合にだけ使えます。
  • ValidatorBuilder のバリデータのプロパティは、null を拒否する制約がなければ null のとき有効で、すべてのチェックがスキップされます。notNull()、notBlank()、notEmpty() は null を拒否します。このページの他の制約は拒否しません。
  • 文字列のすべての形式は、どちらのスタイルでも空文字列を有効とします。形式は与えられたテキストの見た目を表すもので、テキストが与えられたことではありません。必須にするには notEmpty() または notBlank() を追加します。

各制約のメッセージキーと params の名前を併記します。違反の params は引数を名前で保持し、値の名前と違反した値を含みません。位置引数は引き続き ConstraintViolation#args() から取得できます。違反を参照してください。

文字列と CharSequence

String には _string を使います。クラシックスタイルには CharSequence 用の _charSequence もあります。制約は am.ik.yavi.constraint.CharSequenceConstraint にあります。

制約メソッド受け付ける値メッセージキーparams
null でないnotNull()null でない任意の値object.notNull-
nullisNull()null のみobject.isNull-
空でないnotEmpty()null でなく、空でないcontainer.notEmpty-
空白でないnotBlank()null でなく、空白のみでないcharSequence.notBlank-
固定長fixedSize(int)指定した文字数container.fixedSizesize, actualSize
文字数がより大きいgreaterThan(int)指定した数より多いcontainer.greaterThanmin, actualSize
文字数が以上greaterThanOrEqual(int)指定した数以上container.greaterThanOrEqualmin, actualSize
文字数がより小さいlessThan(int)指定した数より少ないcontainer.lessThanmax, actualSize
文字数が以下lessThanOrEqual(int)指定した数以下container.lessThanOrEqualmax, actualSize
含むcontains(CharSequence)指定した文字列を含むテキストcharSequence.containssubstring
前置startsWith(CharSequence)指定した接頭辞で始まるテキストcharSequence.startsWithprefix
後置endsWith(CharSequence)指定した接尾辞で終わるテキストcharSequence.endsWithsuffix
パターンpattern(String), pattern(Pattern), pattern(Supplier<Pattern>)正規表現に一致するテキストcharSequence.patternpattern
メールアドレスemail()メールアドレスcharSequence.email-
UUIDuuid()8-4-4-4-12 の16進数。バージョンとバリアントは検査しないcharSequence.uuid-
ULIDulid()Crockford Base32 の26文字、先頭は 0-7、大文字小文字のどちらでもよいcharSequence.ulid-
IP アドレスip()IPv4 または IPv6 アドレスcharSequence.ip-
IPv4ipv4()IPv4 アドレスcharSequence.ipv4-
IPv6ipv6()IPv6 アドレス。ゾーン ID とプレフィックス長を含むcharSequence.ipv6-
URIuri()任意のスキームを持つ絶対 URI(mailto:、urn:、s3://)。US-ASCII 以外の文字は拒否するcharSequence.uri-
URLurl()java.net.URI が解析できる URLcharSequence.url-
制限付き URLurl(url -> url.protocol(...).host(...).port(...).build())プロトコル、ホスト、ポートが指定した集合に含まれる有効な URLcharSequence.url, charSequence.url.protocol, charSequence.url.host, charSequence.url.portvalues
Luhnluhn()Luhn チェックサムを満たす10進数字charSequence.luhn-
パスワードポリシーpassword(policy -> ...)ポリシーを満たすテキストpassword.required, password.optionalpolicy / min, policies
byte 表現isByte()Byte として解析できるテキストcharSequence.byte-
short 表現isShort()Short として解析できるテキストcharSequence.short-
integer 表現isInteger()Integer として解析できるテキストcharSequence.integer-
long 表現isLong()Long として解析できるテキストcharSequence.long-
float 表現isFloat()Float として解析できるテキストcharSequence.float-
double 表現isDouble()Double として解析できるテキストcharSequence.double-
BigInteger 表現isBigInteger()BigInteger として解析できるテキストcharSequence.biginteger-
BigDecimal 表現isBigDecimal()BigDecimal として解析できるテキストcharSequence.bigdecimal-
ローカル日付isoLocalDate(), localDate(String pattern)パターンに合い、ResolverStyle.STRICT で解決できる日付charSequence.localdatepattern

ip()、uri()、ulid() は 0.18 で追加されました。url(builder) は解析した URL を制限します。protocol はプロトコル名、host は書かれたとおりに大文字小文字を区別せず比較するホスト名、port はポート番号を受け付けます。明示的なポートがない URL は、そのプロトコルの既定ポートと比較されます。

var proxyValidator = Yavi._string("proxy", c -> c.notBlank().ip());
proxyValidator.validate("");                 // "proxy" must not be blank
proxyValidator.validate("192.0.2.1");        // Valid
proxyValidator.validate("2001:db8::1");      // Valid
proxyValidator.validate("example.com");      // Invalid (charSequence.ip)

var homepageValidator = Yavi._string("homepage", c -> c.uri());
homepageValidator.validate("mailto:a@example.com"); // Valid
homepageValidator.validate("/relative/path");       // Invalid

pattern(Supplier<Pattern>) は検証のたびにサプライヤを呼びます。検証時に組み立てる正規表現に使います。

組み込みのパスワードポリシーは am.ik.yavi.constraint.password.PasswordPolicy の UPPERCASE、LOWERCASE、ALPHABETS、NUMBERS、SYMBOLS です。ポリシーは required(...) で必須にするか、optional(int, ...) で最低数のうちの1つにします。uppercase(2) は大文字2文字を要求します。独自の PasswordPolicy も同じように渡せます。

文字数のカウントとバイト長

文字列の文字数制約は、正規化と、無視するように指定した異体字セレクタの除去の後に、Unicode コードポイントを数えます。既定の正規化は Normalizer.Form.NFC なので、モシ と濁点で書いた モジ は3文字ではなく2文字として数えられます。テキスト自体を検査する制約(contains、startsWith、endsWith、pattern、形式、codePoints)は値を正規化しません。

制約メソッド効果メッセージキーparams
正規化normalizer(Normalizer.Form), normalizer(null)文字数の測定前に行う正規化を設定または無効化する--
絵文字emoji()絵文字の並びを拡張書記素クラスタとして1文字に数える。既定では無効--
異体字セレクタvariant(opts -> opts.ivs(...).svs(...).fvs(...))文字数の測定前に指定した異体字セレクタを除去する--
コードポイントcodePoints(...).asWhiteList(), .asBlackList()指定したコードポイントを許可または禁止するcodePoints.asWhiteList, codePoints.asBlackListnotAllowed
バイト長asByteArray(), asByteArray(Charset) の後に fixedSize、greaterThan、greaterThanOrEqual、lessThan、lessThanOrEqualエンコード後のバイト長を測定するbyteSize.fixedSize, byteSize.greaterThan, byteSize.greaterThanOrEqual, byteSize.lessThan, byteSize.lessThanOrEqualsize, actualSize / min, actualSize / max, actualSize

emoji() は負荷が高いため既定では無効です。0.18 では拡張書記素クラスタを数えるため、"\r\n" や、濁点付きの半角カタカナは1文字として数えられます。Emoji クラスは削除されました。

normalizer、emoji()、variant(...) はそれ自体が制約ではありません。その結果に適用した文字数制約のメッセージが報告されます。コードポイントの集合は am.ik.yavi.constraint.charsequence.CodePoints で表し、組み込みの集合は AsciiCodePoints と UnicodeCodePoints から利用できます。

絵文字の並びが1文字になるのは emoji() を追加した場合だけです。追加しなければコードポイントごとに数えます。asByteArray() は文字セットを指定しなければ UTF-8 のバイト長を測定します。バイト長に上限がある列に使います。

var messageValidator = Yavi._string("text", c -> c.emoji().lessThanOrEqual(3)
        .asByteArray().lessThanOrEqual(16));
messageValidator.validate("I❤️☕️️");        // Valid
messageValidator.validate("❤️❤️❤️️️");     // Invalid (byteSize.lessThanOrEqual)

整数

クラシックスタイルでは _byte、_short、_integer、_long、_character、_bigInteger を対応する型に使います。スキーマスタイルには _short、_integer、_long、_bigInteger があります。Character の制約は文字の数値を比較します。positive などの符号の制約が使うゼロは Character.MIN_VALUE です。

制約メソッド受け付ける値メッセージキーparams
null でないnotNull()null でない任意の値object.notNull-
nullisNull()null のみobject.isNull-
より大きいgreaterThan(V)境界より大きいnumeric.greaterThanmin
以上greaterThanOrEqual(V)境界以上numeric.greaterThanOrEqualmin
より小さいlessThan(V)境界より小さいnumeric.lessThanmax
以下lessThanOrEqual(V)境界以下numeric.lessThanOrEqualmax
正positive()ゼロより大きいnumeric.positive-
正またはゼロpositiveOrZero()ゼロ以上numeric.positiveOrZero-
負negative()ゼロより小さいnumeric.negative-
負またはゼロnegativeOrZero()ゼロ以下numeric.negativeOrZero-
倍数multipleOf(V)除数で割り切れる値numeric.multipleOfdivisor

multipleOf は Byte、Short、Integer、Long、BigInteger、BigDecimal で利用できます。Character、Double、Float にはありません。

var quantityValidator = Yavi._integer("quantity", c -> c.multipleOf(12));
quantityValidator.validate(24);  // Valid
quantityValidator.validate(30);  // Invalid ("quantity" must be a multiple of 12)

BigInteger と BigDecimal

BigInteger と BigDecimal は、multipleOf を含む整数の制約を持ちます。BigDecimal にはさらに桁数に関する制約があります。

制約メソッド受け付ける値メッセージキーparams
小数部の桁数fractionDigits(int)小数点以下の桁数が指定値以下。末尾のゼロは数えないnumeric.fractionDigitsmax
整数部の桁数integerDigits(int)小数点以上の桁数が指定値以下。0.5 のゼロは数えないnumeric.integerDigitsmax

比較は BigDecimal#compareTo を使い、スケールを無視します。1.0 と 1.00 は同じ値で、どちらも小数部の桁数はゼロです。制約はスケールを変えません。生成する値のスケールを固定するには preprocess または map を使います。

var priceValidator = Yavi._bigDecimal("price", c -> c.fractionDigits(2).integerDigits(6));
priceValidator.validate(new BigDecimal("1.50"));  // Valid (1.5 has one fraction digit)
priceValidator.validate(new BigDecimal("1.505")); // Invalid (numeric.fractionDigits)

Double と Float

_double と _float は、notNull、isNull、greaterThan、greaterThanOrEqual、lessThan、lessThanOrEqual、positive、positiveOrZero、negative、negativeOrZero を持ち、メッセージキーは整数と同じです。2進小数の剰余は正確でないため、multipleOf はありません。NaN はどの境界も満たさず、すべての比較で拒否されます。

日時

日時の制約は次の型で利用でき、クラシックスタイルのビルダーショートカットがあります。スキーマスタイルでは同じ名前のプロパティメソッドを使います。たとえば Yavi.schema()._localDate("date", c -> c.past()) です。

型制約クラスクラシックのショートカット
LocalDateLocalDateConstraint_localDate
LocalTimeLocalTimeConstraint_localTime
LocalDateTimeLocalDateTimeConstraint_localDateTime
OffsetDateTimeOffsetDateTimeConstraint_offsetDateTime
InstantInstantConstraint_instant
YearYearConstraint_year
YearMonthYearMonthConstraint_yearMonth
ZonedDateTimeZonedDateTimeConstraint_zonedDateTime
制約メソッド受け付ける値メッセージキーparams
過去past(), past(Clock)現在より前temporal.past-
過去または現在pastOrPresent(), pastOrPresent(Clock)現在以前temporal.pastOrPresent-
未来future(), future(Clock)現在より後temporal.future-
未来または現在futureOrPresent(), futureOrPresent(Clock)現在以降temporal.futureOrPresent-
より前before(Supplier<T>)指定した境界より前temporal.beforeother
以前beforeOrEqual(Supplier<T>)指定した境界以前temporal.beforeOrEqualother
より後after(Supplier<T>)指定した境界より後temporal.afterother
以後afterOrEqual(Supplier<T>)指定した境界以後temporal.afterOrEqualother
間between(Supplier<T>, Supplier<T>)指定した2つの境界の間(両端を含まない)temporal.betweenrangeFrom, rangeTo
フィールドfieldPredicate(TemporalField, LongPredicate)述語が受け付けるフィールドの値temporal.fieldfield

before、beforeOrEqual、after、afterOrEqual、between には boolean memoize 引数を持つオーバーロードがあります。既定は true で、サプライヤは最大1回だけ呼ばれ、同じ値が比較とメッセージに使われます。rangeFrom が rangeTo より後の場合、between は IllegalArgumentException を投げます。Clock のオーバーロードは、決定的なテストと、システム既定のゾーン以外の時刻源のためにあります。

null 値は有効で、日時のチェックはすべてスキップされます。

Boolean

制約メソッド受け付ける値メッセージキーparams
null でないnotNull()null でない任意の値object.notNull-
nullisNull()null のみobject.isNull-
trueisTrue()trueboolean.isTrue-
falseisFalse()falseboolean.isFalse-

コレクションと配列

Collection には _collection、配列には _objectArray、_booleanArray、_byteArray、_charArray、_shortArray、_intArray、_longArray、_floatArray、_doubleArray を使います。_list、_map、forEach を含む、リスト、マップ、配列の要素や値の検証は オブジェクトとコレクションで説明しています。

制約メソッド受け付ける値メッセージキーparams
null でないnotNull()null でない任意の値object.notNull-
nullisNull()null のみobject.isNull-
空でないnotEmpty()空でないコレクションまたは配列container.notEmpty-
固定サイズfixedSize(int)指定した要素数container.fixedSizesize, actualSize
サイズがより大きいgreaterThan(int)指定した数より多いcontainer.greaterThanmin, actualSize
サイズが以上greaterThanOrEqual(int)指定した数以上container.greaterThanOrEqualmin, actualSize
サイズがより小さいlessThan(int)指定した数より少ないcontainer.lessThanmax, actualSize
サイズが以下lessThanOrEqual(int)指定した数以下container.lessThanOrEqualmax, actualSize
含むcontains(E)指定した要素を含むコレクションまたは配列collection.contains, array.containselement
一意unique()重複のない要素collection.uniqueduplicates
キーで一意unique(Function<? super E, ?>)キーが一意な要素collection.uniqueByduplicates
すべて含むcontainsAll(Collection<? extends E>)指定したすべての要素collection.containsAllvalues, missing

unique(key) は重複したキーを報告します。containsAll は Set とそれ以外のコレクションで同じ意味になります。null の配列は有効で、notEmpty() を除いてチェックはスキップされます。

var productsValidator = Yavi.schema()._list("products", productValidator, c -> c.unique(Product::id));
// "products" must be unique. [APPLE] is/are duplicated.

Map

Map には _map を使います。

制約メソッド受け付ける値メッセージキーparams
null でないnotNull()null でない任意の値object.notNull-
nullisNull()null のみobject.isNull-
空でないnotEmpty()空でないマップcontainer.notEmpty-
固定サイズfixedSize(int)指定したエントリ数container.fixedSizesize, actualSize
サイズがより大きいgreaterThan(int)指定した数より多いcontainer.greaterThanmin, actualSize
サイズが以上greaterThanOrEqual(int)指定した数以上container.greaterThanOrEqualmin, actualSize
サイズがより小さいlessThan(int)指定した数より少ないcontainer.lessThanmax, actualSize
サイズが以下lessThanOrEqual(int)指定した数以下container.lessThanOrEqualmax, actualSize
キーを含むcontainsKey(K)指定したキーを含むマップmap.containsKeykey
値を含むcontainsValue(V)指定した値を含むマップmap.containsValuevalue

Object

その他のオブジェクトには _object を使います。クラシックスタイルでは、constraintOnTarget が検証対象のオブジェクト自体に制約を適用します。

制約メソッド受け付ける値メッセージキーparams
null でないnotNull()null でない任意の値object.notNull-
nullisNull()null のみobject.isNull-
等しいequalTo(Object)指定した値と等しい値object.equalTovalue
いずれかoneOf(Collection)指定した値のいずれかobject.oneOfvalues
いずれでもないnotOneOf(Collection)指定した値のいずれでもないobject.notOneOfvalues
パスワードポリシーpassword(policy -> ...)ポリシーを満たす値。ポリシーはオブジェクト全体を検査できるpassword.required, password.optionalpolicy / min, policies

Enum

Enum には _enum を使います。スキーマスタイルとクラシックスタイルのどちらも Enum の型を渡します。

var statusValidator = Yavi._enum("status", Status.class, c -> c.oneOf(Status.ACTIVE));
statusValidator.validate(Status.ACTIVE);   // Valid
statusValidator.validate(Status.INACTIVE); // Invalid ("status" must be one of the following values: [ACTIVE])
制約メソッド受け付ける値メッセージキーparams
null でないnotNull()null でない任意の値object.notNull-
nullisNull()null のみobject.isNull-
いずれかoneOf(E...)指定した定数のいずれか。リストは空にできないobject.oneOfvalues

クラシックスタイルでは、notNull() を追加しなければ null の Enum 値は有効です。EnumValidatorBuilder と EnumValidator は単一の Enum 値を検証します。