m4hv-extensions Document

Note:

m4hv-extensionsを利用するにはHibernateValidator-4.2.0.Final(Bean Validationの実装)を別途ダウンロードしてください。

m4hv-extensions-1.4.1以降のドキュメントです。

1.Quick Overview

m4hv-extensionsには通常のHibernateValidator(Bean Validation)にはない、しかしながら比較的よく使うであろうバリデーションをHibernateValidator(Bean Validation)の インターフェースを実装することで提供します。m4hv-extensionsが提供するバリデーションの種類と概要をを以下の表に示します。

m4hv-extensionが提供するバリデーション説明
@ActualDate文字列が実際に存在する日付かどうかチェックする。 
入力可能な日付の範囲を任意に設定することで範囲チェックと併用することも可能。 
@AlphabetNumber文字列が数字、もしくはアルファベットで構成されているか否かのチェックを行う。 
アルファベットについては大文字、小文字での判別を行うことも可能。 
@CharLength文字列の長さの範囲チェックを行う。 
日本語ではサロゲートペアで表される文字や、合成文字なども利用される可能性を考慮し それぞれ自然な区切り(サロゲートペア、合成文字も1文字として認識)で文字列長の チェックを行います。 
@Hiragana文字列が平仮名のみで構成されているかどうかチェックします。 
@Hoursチェックするデータが正しい時間(00~23)かどうかのチェックを行います。 
@Katakana文字列が片仮名のみで構成されているかどうかチェックします。 
@Minutesチェックするデータが正しい分(00~59)かどうかのチェックを行います。 
@Secondsチェックするデータが正しい秒(00~59)かどうかのチェックを行います。 
@Time文字列が実際に存在する時間かどうかチェックする。 
入力可能な時間の範囲を任意に設定することで範囲チェックと併用することも可能。 
@ZipCode文字列が正しい郵便番号のフォーマットに従っているか否かのチェックを行います。 
@NumberString文字列が指定された桁数内の数字文字列で構成されているかどうかチェックします。 
(m4hv-extensions-1.1.1以降)
@HalfwithKatakana文字列が半角カタカナで構成されているかどうかチェックします。 
(m4hv-extensions-1.2.1以降)
@NotHaveInValidCharacter文字列内に許可されていない文字が含まれているかどうか検証します。 
禁止文字はクラスパスルートにInValidCharacters.propertiesファイルを作成し、 そのファイル内で"key=value"形式で記述する必要があります。 (m4hv-extensions-1.3.1以降)
@OnlyHaveValidCharacter文字列を構成するすべての文字が有効な文字によって構成されているどうか検証します。 
有効文字はクラスパスルートにValidCharacters.propertiesファイルを作成し、 そのファイル内で"key=value"形式で記述する必要があります。 (m4hv-extensions-1.3.1以降)

m4hv-extensionsを利用するには、まずHibernateValidatorにクラスパスを通してください。次に、HibernateValidatorで利用するためのメッセージプロパティファイル (ValidationMessages.properties)クラスパスルートに配置する必要があります。このプロパティファイルの日本語版が配布されているのを見たことがないので HibernateValidator及びm4hv-extensionsで利用するバリデーションメッセージも含めて日本語化したメッセージサンプルを示します。

ValidationMessages.properties日本語メッセージサンプル

#Japanese messages
javax.validation.constraints.AssertFalse.message=Falseでなければなりません。
javax.validation.constraints.AssertTrue.message=Trueでなければなりません。
javax.validation.constraints.DecimalMax.message={value}以下でなければなりません。
javax.validation.constraints.DecimalMin.message={value}以上でなければなりません。
javax.validation.constraints.Digits.message=境界以外の数値(予測:<{integer} digits>.<{fraction} digits>)
javax.validation.constraints.Future.message=未来日付でなければなりません。
javax.validation.constraints.Max.message={value}以下でなければなりません。
javax.validation.constraints.Min.message={value}以上でなければなりません。
javax.validation.constraints.NotNull.message=Nullは許可されていません。
javax.validation.constraints.Null.message=Nullでなければなりません。
javax.validation.constraints.Past.message=過去日付でなければなりません。
javax.validation.constraints.Pattern.message=パターン({regexp})に一致しなければなりません。
javax.validation.constraints.Size.message=サイズは{min}以上{max}以下でなければなりません。

org.hibernate.validator.constraints.CreditCardNumber.message=正しいクレジットカード番号ではありません。
org.hibernate.validator.constraints.Email.message=正しいE-Mailの形式ではありません。
org.hibernate.validator.constraints.Length.message=長さは{min}以上{max}以下でなければなりません。
org.hibernate.validator.constraints.NotBlank.message=ブランクは許可されていません。
org.hibernate.validator.constraints.NotEmpty.message=何らかのデータが必要です。
org.hibernate.validator.constraints.Range.message={min}から{max}の範囲内でなければなりません。
org.hibernate.validator.constraints.SafeHtml.message=安全ではないHTMLが含まれています。
org.hibernate.validator.constraints.ScriptAssert.message={script}による評価が不正です。
org.hibernate.validator.constraints.URL.message=正しいURLではありません。

## extensions messages.
org.maru.m4hv.extensions.AlphabetNumber.message=アルファベット、数字以外の文字が含まれています。
org.maru.m4hv.extensions.ActualDate.message=不正な日付です(有効な日付:{from}-{until})。
org.maru.m4hv.extensions.Hours.message=不正な時間です(有効な時間:{from}-{until})。
org.maru.m4hv.extensions.Minutes.message=不正な分です(有効な分:{from}-{until})。
org.maru.m4hv.extensions.Seconds.message=不正な秒です(有効な秒:{from}-{until})。
org.maru.m4hv.extensions.Time.message=不正な時刻です(有効な時刻:{from}-{until})。
org.maru.m4hv.extensions.ZipCode.message=郵便番号の形式が不正です。
org.maru.m4hv.extensions.Hiragana.message=平仮名ではありません。
org.maru.m4hv.extensions.Katakana.message=片仮名ではありません。
org.maru.m4hv.extensions.CharLength.message={min}文字以上{max}文字以下でなければなりません。
## NumberString validation is new validation from version 1.1.1
org.maru.m4hv.extensions.NumberString.message={min}桁以上{max}桁以下の数字文字列でなければなりません。
## HalfwidthKatakana is new validation from version 1.2.1
org.maru.m4hv.extensions.HalfwidthKatakana.message=半角片仮名ではありません。
## NotHaveInValidCharacter and OnlyHaveValidCharacter are new validation from version 1.3.1
org.maru.m4hv.extensions.NotHaveInValidCharacter.message=許可されていない文字を含んでいます。
org.maru.m4hv.extensions.OnlyHaveValidCharacter.message=有効な文字以外の文字を含んでいます。

extensions messagesコメント以下のorg.maru.m4hv.extensions.XXX.messageキーで定義されているメッセージがm4hv-extensionsで利用されるメッセージです。 それ以前のメッセージがBean Validation及びHibernateValidatorで追加で組み込まれているバリデーションで利用されるメッセージです。 m4hv-extensionsで利用するメッセージはorg.maru.m4hv.extensionsパッケージ内にあるExtensionsValidationMessages_ja_JP.propertiesファイルにも収録しているのでそちらを参考してくださっても結構です。 なお、上記はあくまでもメッセージのサンプルなのでプロジェクトに応じて適切に設定する必要があります。

※org.maru.m4hv.extensions.NumberString.messageメッセージはVersion1.1.1で追加されたバリデーション用のメッセージです。

※org.maru.m4hv.extensions.HalfwidthKatakana.messageメッセージはVersion1.2.1で追加されたバリデーション用のメッセージです。

※org.maru.m4hv.extensions.NotHaveInValidCharacter.message、org.maru.m4hv.extensions.NotHaveInValidCharacter.messageメッセージはVersion1.3.1で追加されたバリデーション用のメッセージです。

※version1.4.1より、Hour、Minute、SecondアノテーションがそれぞれHours、Minutes、Secondsと変更になったことに伴い上記メッセージキーも変更されています。

それでは、簡単にm4hv-extensionsの利用例を示します。といっても基本はバリデーションを行いたい項目にアノテーションを付与するだけで、それ以外は 通常のHibernateValidatorの利用方法と何ら変わりません。

利用例

  public class DateEntity {
      public DateEntity(String date) {
          this.date = date;
      }

      @ActualDate
      private String date;

      public void setDate(String date) {
          this.date = date;
      }

      public String getDate() {
          return this.date;
      }
  }

  public class Main {
      public static void main(String[] args) {
          DateEntity dateEntity = new DateEntity("2011/02/31");
          ValidatorFactory factory = Validation.buildDefaultValidatorFactory();
          Validator validator = factory.getValidator();
          Set<ConstraintViolation<DateEntity>> constraintViolations = validator.validate(dateEntity);
          if (constraintViolations.size() == 1) {
              System.out.println(constraintViolations.iterator().next().getMessage());
          }
      }
  }

上記の例ではDateEntityクラスを2011/02/31という日付文字列でインスタンス化しています。次にValidatorFactoryを生成し、ValidatorFactoryからValidatorインスタンスを取得します。 ValidatorクラスのvalidateメソッドにDateEntityインスタンスのチェックを行います。チェック結果はSetオブジェクトで返され、Setのサイズが0より大きければ何らかのバリデーションエラーが発生したことになります。 この例ではバリデーションを行う項目は1項目であり、2011/02/31という実際には存在しない日付が設定されているためバリデーションエラーが発生します。最後にバリデーションメッセージを出力しています。

先にも述べましたが、ここでm4hv-extensions独自のものは@ActualDateというバリデーションを行うためのアノテーションのみです。それ以外はすべてHibernateValidatorを利用する際の一般的な記述です。 m4hv-extensionsが提供するものはあくまでもシンプルなバリデーションであり、HibernateValidator自体を独自に拡張したようなものではありません。

2.ActualDateバリデータ

ActualDateバリデータはString型の日付文字列を任意のパターンでパースし、日付の妥当性検証を行います。デフォルトでサポートしている日付のパターンは"yyyy/MM/dd"、"yyyy-MM-dd"、 "yyyy.MM.dd"、 "yyyyMMdd" の4パターンです。最もシンプルな利用方法は「1.Quick Overview」の利用例の通りです。この場合厳密には日付の妥当性と、その日付が1970/01/01以降であるこのとチェックを行っています。 日付の範囲を例えば2000/10/10~2020/10/10とし、その範囲以外の日付の場合はエラーとしたい場合は次のように指定します。

日付の範囲を指定する例

  public class DateEntity {
      public DateEntity(String date) {
          this.date = date;
      }

      @ActualDate(from = "2000/10/10", until = "2020/10/10")
      private String date;

      public void setDate(String date) {
          this.date = date;
      }

      public String getDate() {
          return this.date;
      }
  }

  public class Main {
      public static void main(String[] args) {
          DateEntity dateEntity = new DateEntity("2020/10/11");
          ValidatorFactory factory = Validation.buildDefaultValidatorFactory();
          Validator validator = validator = factory.getValidator();
          Set<ConstraintViolation<DateEntity>> constraintViolations = validator.validate(dateEntity);
          if (constraintViolations.size() == 1) {
              System.out.println(constraintViolations.iterator().next().getMessage());
          }
      }
  }

上記例ではActualDateアノテーションのfromとuntilにそれぞれ開始終了の年月日を設定しています。この場合DateEntityインスタンスのdataフィールドに2011/10/11という日付文字列が入力された場合はバリデーションエラーとなります。

また、サポートする日付パターンを変更したい場合は次のように記述することで実現可能です。

日付のパターンを指定する例

  public class DateEntity {
      public DateEntity(String date) {
          this.date = date;
      }

      @ActualDate(from = "2000/10/10", until = "2020/10/10", patterns = {"yyyy/MM/dd", "yyyy_MM_dd"})
      private String date;

      public void setDate(String date) {
          this.date = date;
      }

      public String getDate() {
          return this.date;
      }
  }

日付のパターンを変更する場合はActualDateアノテーションのpatternsを用いて行います。上記例では"yyyy/MM/dd"、 "yyyy_MM_dd"の2パターンが許可されることになります。 基本的にこの項目を独自に設定することはあまりないと思います。(デフォルトのパターンで十分だと思うので。)

3.AlphabetNumberバリデータ

String型の文字列が数字、もしくはアルファベットで構成されているかどうかのチェックを行います。アルファベットについてはデフォルトでは大文字小文字のどちらとも許可します。

  public class AlphabetNumberEntity {
      public AlphabetNumberEntity(String value) {
          this.value = value;
      }

      @AlphabetNumber
      private String value;

      ...
  }

  public class Main {
      public static void main(String[] args) {
          AlphabetNumberEntity entity = new AlphabetNumberEntity("ABcd123!");
          ValidatorFactory factory = Validation.buildDefaultValidatorFactory();
          Validator validator = validator = factory.getValidator();
          Set<ConstraintViolation<AlphabetNumberEntity>> constraintViolations = validator.validate(entity);
          if (constraintViolations.size() == 1) {
              System.out.println(constraintViolations.iterator().next().getMessage());
          }
      }
  }

上記例では、AlphabetNumberEntityクラスのvalueフィールドに"ABcd123!"という文字列を設定しており、当該文字列には"!"という記号を含んでいるためバリデーションはエラーとなります。 大文字小文字の区別を行いたい場合は次のように設定してください。

大文字アルファベットと数字のみ許可する場合

  public class AlphabetNumberEntity {
      public AlphabetNumberEntity(String value) {
          this.value = value;
      }

      @AlphabetNumber(CasePattern.UPPER)
      private String value;

      ...
  }

小文字アルファベットと数字のみ許可する場合

  public class AlphabetNumberEntity {
      public AlphabetNumberEntity(String value) {
          this.value = value;
      }

      @AlphabetNumber(CasePattern.LOWER)
      private String value;

      ...
  }

明示的に大文字小文字アルファベットと数字のみ許可することを示す場合(デフォルトと同じ)

  public class AlphabetNumberEntity {
      public AlphabetNumberEntity(String value) {
          this.value = value;
      }

      @AlphabetNumber(CasePattern.BOTH)
      private String value;

      ...
  }

4.CharLengthバリデータ

CharLengthバリデータは文字列の長さをチェックします。一般的にString#length等では文字コードの数で文字列の長さを表しているため、サロゲートペアや合成文字を1文字として認識しません。 例えばサロゲートペアで構成される文字を含んだ3文字があった場合String#lengthでは4となります。CharLengthバリデータは自然な区切りで文字を認識し、その長さに対してバリデーションを 行います。

CharLengthアノテーションはmin、max属性を持っており、それぞれ適切に設定することで最小、最大文字列長を調整可能です。デフォルトでminは0、maxは2147483647です。

利用例

  public class CharLengthEntity {
      public CharLengthEntity(String value) {
          this.value = value;
      }

      @CharLength(min = 3, max = 6)
      private String value;

      ...
  }

  public class Main {
      public static void main(String[] args) {
          AlphabetNumberEntity entity = new AlphabetNumberEntity("𩸽はおいしい");
          ValidatorFactory factory = Validation.buildDefaultValidatorFactory();
          Validator validator = validator = factory.getValidator();
          Set<ConstraintViolation<AlphabetNumberEntity>> constraintViolations = validator.validate(entity);
          if (constraintViolations.size() == 0) {
              System.out.println("Validation OK");
          }
      }
  }

上記利用例では3文字以上、6文字以内の文字列まで許容することを明示し、valueに「𩸽はおいしい」という文字列を設定してバリデーションを行っています。この「𩸽」という文字はユニコードでは サロゲートペアとして構成される文字です。String#lengthベースのバリデーションでこの文字列の評価を行った場合はバリデーションエラーとなりますが。CharLengthはあくまでも"文字"、つまり 人が見たときに1文字として認識できる自然な文字を1文字として認識し文字列長のバリデーションを行います。 よって、上記例の場合バリデーション結果は正常終了ということになります。

5.平仮名(Hiragana)バリデータ

文字列が平仮名か否かをチェックします。デフォルトでは"ぁ"~"ゖ"までの文字コード内にある平仮名であればバリデーションは成功します。 濁音、半濁音、繰り返し記号、縦書き合字及び空白(スペース)はデフォルトではエラーとなりますがオプションを有効にすることでバリデーションの結果を成功にすることが可能です。

Hiraganaアノテーションのオプション一覧

オプションデフォルト説明
enableVoicingMarksFALSETRUEにすることで濁音、半濁音を有効にします。 
Unicode表で0x3099~0x309Cまでの文字
enableIterationMarksFALSETRUEにすることで平仮名繰り返し記号を有効にします。 
Unicode表で0x309D、0x309Eの文字
enableHiraganaDigraphFALSETRUEにすることで平仮名縦書き合字を有効にします。 
Unicode表で0x309Fの文字
enableSpaceFALSETRUEにすることでスペースを有効にします。 
スペースは全角・半角のいずれか、もしくは両方を選択することができます。(spaceType参照)
spaceTypeSpaceType.BOTHenableSpaceがTRUEのとき有効にするスペースのタイプを設定します。 
SpaceType.BOTH・・・半角・全角スペース 
SpaceType.FULLWIDTH_SPACE・・・全角スペース 
SpaceType.HALFWIDTH_SPACE・・・半角スペース

利用例

  public class HiraganaEntity {
      public HiraganaEntity(String value) {
          this.value = value;
      }

      @Hiragana(enableVoicingMarks = true,
                enableIterationMarks = true,
                enableHiraganaDigraph = true,
                enableSpace = true,
                spaceType = SpaceType.FULLWIDTH_SPACE)
      private String value;

      ...
  }

上記例では、通常の平仮名に加え、濁音、半濁音、繰り返し記号、縦書き合字及び全角スペースが有効になります。

6.Hours(時間)バリデータ

バリデーション対象データが有効な時間であるかどうかの検証を行います。時間はデフォルトでは0時~23時です。当該時間内であればバリデーション は成功し、それ以外であればバリデーションエラーとなります。時間の範囲はfrom、untilを設定することで任意に変更可能です。

利用例

  public class HoursEntity {
      public HoursEntity(int value) {
          this.value = value;
      }

      @Hours(from = 9, until = 17)
      private int value;

      ...
  }

上記利用例では時間は9時~17時の範囲であればバリデーションは成功し、それ以外の時間であればバリデーションエラーとなります。

※バージョン1.0.1よりint、String型に加えbyte型の項目に対してもバリデーションが実行可能となりました。

※バージョン1.1.1よりbyte、int、String型に加えshort型の項目に対してもバリデーションが実行可能となりました。

※バージョン1.4.1より名称がHourからHoursに変更になりました。

7.片仮名(Katakana)バリデータ

文字列が片仮名か否かを検証します。デフォルトでは"ァ"~"ー"までの文字コード内にある片仮名であればバリデーションは成功します。 片仮名句読点、繰り返し記号、縦書き合字、小書き片仮名及び空白(スペース)はデフォルトではエラーとなりますがオプションを有効にすることでバリデーションの結果を成功にすることが可能です。

Katakanaアノテーションのオプション一覧

オプションデフォルト説明
enablePunctuationFALSETRUEにすることで片仮名句読点を有効にします。 
Unicode表で0x30A0の文字
enableIterationMarksFALSETRUEにすることで片仮名繰り返し記号を有効にします。 
Unicode表で0x30FD、0x30FEの文字
enableKatakanaDigraphFALSETRUEにすることで片仮名縦書き合字を有効にします。 
Unicode表で0x30FFの文字
enablePhoneticExtensionsFALSETRUEにすることで小書き片仮名を有効にします。(Version1.4.1以降) 
Unicode表で0x31F0~31FFの文字
enableSpaceFALSETRUEにすることでスペースを有効にします。 
スペースは全角・半角のいずれか、もしくは両方を選択することができます。(spaceType参照)
spaceTypeSpaceType.BOTHenableSpaceがTRUEのとき有効にするスペースのタイプを設定します。 
SpaceType.BOTH・・・半角・全角スペース 
SpaceType.FULLWIDTH_SPACE・・・全角スペース 
SpaceType.HALFWIDTH_SPACE・・・半角スペース

利用例

  public class KatakanaEntity {
      public KatakanaEntity(String value) {
          this.value = value;
      }

      @Hiragana(enablePunctuation = true,
                enableIterationMarks = true,
                enableKatakanaDigraph = true,
                enablePhoneticExtensions = true
                enableSpace = true,
                spaceType = SpaceType.FULLWIDTH_SPACE)
      private String value;

      ...
  }

上記例では、通常の片仮名に加え、片仮名句読点、繰り返し記号、縦書き合字、小書き片仮名及び全角スペースが有効になります。

8.Minutes(分)バリデータ

バリデーション対象データが有効なMinutes(分)であるかどうかの検証を行います。Minutesはデフォルトでは0分~59分です。指定された範囲内であればバリデーション は成功し、それ以外であればバリデーションエラーとなります。分の範囲はfrom、untilを設定することで任意に変更可能です。

利用例

  public class MinutesEntity {
      public MinutesEntity(int value) {
          this.value = value;
      }

      @Minutes(from = 30, until = 45)
      private int value;

      ...
  }

上記利用例では30分~45分の範囲であればバリデーションは成功し、それ以外であればバリデーションエラーとなります。

※バージョン1.0.1よりint、String型に加えbyte型の項目に対してもバリデーションが実行可能となりました。

※バージョン1.1.1よりbyte、int、String型に加えshort型の項目に対してもバリデーションが実行可能となりました。

※バージョン1.4.1より名称がMinuteからMinutesに変更になりました。

9.Seconds(秒)バリデータ

バリデーション対象データが有効なSeconds(秒)であるかどうかの検証を行います。Secondsはデフォルトでは0秒~59秒です。指定された範囲内であればバリデーション は成功し、それ以外であればバリデーションエラーとなります。秒の範囲はfrom、untilを設定することで任意に変更可能です。

利用例

  public class SecondsEntity {
      public SecondsEntity(int value) {
          this.value = value;
      }

      @Seconds(from = 30, until = 45)
      private int value;

      ...
  }

上記利用例では30秒~45秒の範囲であればバリデーションは成功し、それ以外であればバリデーションエラーとなります。

※バージョン1.0.1よりint、String型に加えbyte型の項目に対してもバリデーションが実行可能となりました。

※バージョン1.1.1よりbyte、int、String型に加えshort型の項目に対してもバリデーションが実行可能となりました。

※バージョン1.4.1より名称がSecondからSecondsに変更になりました。

9.Timeバリデータ

TimeバリデータはString型の時刻文字列を任意のパターンでパースし、時刻の妥当性検証を行います。デフォルトでサポートしている時刻のパターンは"HH:mm:ss"、 "HH:mm"、 "HH" の3パターンです。デフォルトでTimeバリデータは時刻の妥当性チェックを行った後、その時刻が00:00:00~23:59:59の範囲内かどうかの範囲チェックを行います。 許可する時刻の範囲を例えば10:00:00~18:00:00とし、その範囲以外の時刻の場合はバリデーションエラーとしたい場合は次のように指定します。

時刻の範囲を指定する例

  public class TimeEntity {
      public TimeEntity(String time) {
          this.time = time;
      }

      @Time(from = "10:00:00", until = "18:00:00")
      private String time;

      public void setTime(String time) {
          this.time = time;
      }

      public String getTime() {
          return this.time;
      }
  }

  public class Main {
      public static void main(String[] args) {
          TimeEntity time = new TimeEntity("19:30:00");
          ValidatorFactory factory = Validation.buildDefaultValidatorFactory();
          Validator validator = validator = factory.getValidator();
          Set<ConstraintViolation<TimeEntity>> constraintViolations = validator.validate(time);
          if (constraintViolations.size() == 1) {
              System.out.println(constraintViolations.iterator().next().getMessage());
          }
      }
  }

上記例ではTimeアノテーションのfromとuntilにそれぞれ開始終了時刻を設定しています。この場合TimeEntityインスタンスのtimeフィールドに"19:30:00"という時刻文字列が入力された場合はバリデーションエラーとなります。

また、サポートする時刻パターンを変更したい場合はActualDateバリデータ同じようにpatternsに適切にパターンを記述することで実現可能です。 基本的にこの項目を独自に設定することはあまりないと思います。(デフォルトのパターンで十分だと思うので。)

10.ZipCode(郵便番号)バリデータ

ZipCodeバリデータはString型の検証対象データが指定されたパターンの郵便番号フォーマットと合致しているか否か検証します。デフォルトの郵便番号フォーマットは日本の一般的な郵便番号である"123-4567"の形式です。 郵便番号のパターンを変更したい場合は以下のように正規表現を用いて適切に設定することで可能です。

  public class ZipCodeEntity {
      public ZipCodeEntity(String zipCode) {
          this.zipCode = zipCode;
      }

      @ZipCode("[0-9]{7}+") // 単純な数字7桁
      private String zipCode;

      public void setZipCode(String zipCode) {
          this.zipCode = zipCode;
      }

      public String getZipCode() {
          return this.zipCode;
      }
  }

11.NumberStringバリデータ(Version1.1.1以降)

m4hv-extensions-1.1.1よりNumberStrnigバリデーションが追加になりました。NumberStringバリデーションはString型の検証対象データが@NumberStringアノテーションで指定された 最小桁(min)以上、最大桁(max)以下の数字文字列で構成されているかどうかを検証します。min、maxはデフォルトではそれぞれ1、10と設定されています。要件に応じて適切に設定してください。

利用例

  public class NumberStringEntity {
      public NumberStringEntity(String value) {
          this.value = value;
      }

      @NumberString(min = 3, max = 7) // 3桁以上7桁以下の数字文字列でなければならない
      private String value;

      public void setValue(String value) {
          this.value = value;
      }

      public String getValue() {
          return this.value;
      }
  }

上記利用例ではString型のvalueプロパティの値が例えば"123"(3桁数字)や"1234567"(7桁数字)であればバリデーション結果は正常終了となりますが、"10"(2桁数字)や"000000123"(8桁数字)の場合は検証エラーとなります。

12.半角片仮名(HalfwidthKatakana)バリデータ(Version1.2.1以降)

m4hv-extensions-1.2.1よりHalfwidthKatakanaバリデーションが追加になりました。HalfwidthKatakanaバリデーションはString型の検証対象文字列が半角カタカナで構成されているか否かの検証を行います。 通常の半角カタカナに加えて半角スペースを許可する場合はenableSpaceをTRUEに設定してください。(デフォルトはFALSE)

当該バリデーションで許可される半角カタカナはUnicodeの0xFF65~0xFF9Fまでの文字です。

利用例

  public class HalfwidthKatakanaEntity {
      public HalfwidthKatakanaEntity(String value) {
          this.value = value;
      }

      @HalfwidthKatakana(enableSpace = true) // 半角カタカナ+半角スペースを許可
      private String value;

      public void setValue(String value) {
          this.value = value;
      }

      public String getValue() {
          return this.value;
      }
  }

※enableHalfwidthCjkPunctuationフラグをTrueに設定することで半角句読点(。「」、)が入力された際に検証結果を正常終了と判断することが可能となります。 デフォルトではFalseと設定されているので半角句読点が含まれていればバリデーションエラーとなります。

13.NotHaveInValidCharacter(不正文字チェック)バリデータ(Version1.3.1以降)

NotHaveInValidCharacterバリデータはString型の検証対象文字列内に不正文字が含まれているかどうかの検証を行います。もし、不正文字が含まれていた場合はバリデーションエラーとなります。不正文字は クラスパスルートにInValidCharactersプロパティファイルを作成し、key=value形式で記述することが可能です。キー名称については特に縛りはないので任意の名前で設定することが可能です。 値の定義については2種類の方法があります。

以下にInValidCharacterプロパティファイルの定義例を示します。

  org.example.invalid.number=0,1,2,3,4,5,6,7,8,9
  org.example.invalid.comma=,
  org.example.invalid.fullwidth.wave.dash=~

キー名=値という定義方法は変わらないのですが、値をカンマ区切りで1つのキーに対して複数設定することが可能です。またキーと値を1:1で定義することもできます。 カンマを複数文字を定義した際のセパレータとして扱っているため、カンマそのものを不正文字とする場合はキーと値が1:1となる定義方法で別途記載する必要があります。(上記2行目の定義)

1つのキーにカンマ区切りで複数の値(文字)を定義する場合も、1つの値を定義する場合も必ず1文字を定義するようにしてください。例えば以下のように定義した場合、カンマ区切りの値に 単一文字以外の文字列(「今日」という文字列)が定義されているため検証がうまくいきません。

正しくない定義例

  org.example.invalid.definition=今日

それでは最も基本的なNotHaveInValidCharacterバリデータの利用例を以下に示します。

  public class NotHaveInValidCharacterEntity {
      public NotHaveInValidCharacterEntity(String value) {
          this.value = value;
      }

      @NotHaveInValidCharacter
      private String value;

      public void setValue(String value) {
          this.value = value;
      }

      public String getValue() {
          return this.value;
      }
  }

上記利用例では@NotHaveInValidCharacterバリデータアノテーションが付与されたvalueフィールドに対してクラスパスルートにあるInValidCharactersプロパティファイルに定義されているすべての キーで定義された値(不正文字)を読み取り、String型のvalueフィールドの文字列に不正文字が1文字でも含まれていればバリデーションエラーとなります。

不正文字を定義するプロパティファイルはデフォルトではInValidCharactersプロパティファイルですが、デフォルトのプロパティファイル名以外でリソースファイルを作成した場合は@NotHaveInValidCharacter アノテーションのresourceでプロパティファイル名を設定してください。また、プロパティファイル内の特定のキーで定義されている不正文字だけを検証対象としたい場合はkeysで検証に利用する不正文字を 定義したキーをString型の配列で記述してください。

  public class NotHaveInValidCharacterEntity {
      public NotHaveInValidCharacterEntity(String value) {
          this.value = value;
      }

      @NotHaveInValidCharacter(resource = "MyInValidResources",
          keys = {"org.example.invalid.character.1",
                  "org.example.invalid.character.2",
                  "org.example.invalid.character.3"})
      private String value;

      public void setValue(String value) {
          this.value = value;
      }

      public String getValue() {
          return this.value;
      }
  }

上記例は、"MyInValidResources"プロパティファイル内の3つのキーでに定義されている不正文字が1文字でも含まれていれば検証結果エラーとなります。

※プロパティファイル内に定義が1つもない場合は、どのような文字を含んでいようとエラーとなることはありません。

※プロパティファイルはクラスパスルートに必ず1つ作成しなければなりません。ない場合は実行時エラーがスローされます。

14.OnlyHaveValidCharacter(有効文字チェック)バリデータ(Version1.3.1以降)

OnlyHaveValidCharacterバリデータはString型の検証対象文字列が全て有効文字のみで構成されているかどうかの検証を行います。もし、有効文字以外の文字が含まれていた場合はバリデーションエラーとなります。有効文字は クラスパスルートにValidCharactersプロパティファイルを作成し、key=value形式で記述してください。 プロパティファイルの有効文字の定義ルールは上記「13.NotHaveInValidCharacterバリデータ」のInValidCharactersプロパティファイルと同一です。

それでは最も基本的なOnlyHaveValidCharacterバリデータの利用例を以下に示します。

  public class OnlyHaveValidCharacterEntity {
      public OnlyHaveValidCharacterEntity(String value) {
          this.value = value;
      }

      @OnlyHaveValidCharacter
      private String value;

      public void setValue(String value) {
          this.value = value;
      }

      public String getValue() {
          return this.value;
      }
  }

上記利用例では@OnlyHaveValidCharacterバリデータアノテーションが付与されたvalueフィールドに対してクラスパスルートにあるValidCharactersプロパティファイルに定義されているすべての キーで定義された値(有効文字)を読み取り、String型のvalueフィールドの文字列に有効文字以外の文字が1文字でも含まれていればバリデーションエラーとなります。

有効文字を定義するプロパティファイルはデフォルトではValidCharactersプロパティファイルですが、デフォルトのプロパティファイル名以外でリソースファイルを作成した場合は@OnlyHaveValidCharacter アノテーションのresourceでプロパティファイル名を設定してください。また、プロパティファイル内の特定のキーで定義されている有効文字だけを検証対象としたい場合はkeysで検証に利用する不正文字を 定義したキーをString型の配列で記述してください。この辺のルールは上記@NotHaveInValidCharacterバリデータと同一です。

  public class OnlyHaveValidCharacterEntity {
      public OnlyHaveValidCharacterEntity(String value) {
          this.value = value;
      }

      @OnlyHaveValidCharacter(resource = "MyValidResources",
          keys = {"org.example.invalid.character.1",
                  "org.example.invalid.character.2",
                  "org.example.invalid.character.3"})
      private String value;

      public void setValue(String value) {
          this.value = value;
      }

      public String getValue() {
          return this.value;
      }
  }

上記例は、"MyValidResources"プロパティファイル内の3つのキーでに定義されている有効文字以外の文字が1文字でも含まれていれば検証結果エラーとなります。

※プロパティファイル内に定義が1つもない場合は、全ての文字を有効文字とみなします。

※プロパティファイルはクラスパスルートに必ず1つ作成しなければなりません。ない場合は実行時エラーがスローされます。

OnlyHaveValidCharacterバリデータとNotHaveInValidCharacterバリデータの違いはプロパティファイルに有効な文字を定義するか、不正な文字を定義するかという点のみです。

15.m4hv-extensions with maven

Mavenリポジトリより利用する場合は以下の設定をpom.xmlに記述してください。

  <repositories>
    <repository>
      <id>maru</id>
      <name>Maru Project Maven Repository</name>
      <url>http://maru.sourceforge.jp/mvn/</url>
    </repository>
  </repositories>

  <dependencies>
    <dependency>
      <groupId>org.maru.m4hv.extensions</groupId>
      <artifactId>m4hv-extensions</artifactId>
      <version>X.X.X</version>
    </dependency>
    ...
  </dependencies>