パッケージ org.iplass.mtp.command.beanmapper

クラス BeanParamMapper

java.lang.Object
org.iplass.mtp.command.beanmapper.BeanParamMapper
public class BeanParamMapper
extends java.lang.Object

パラメータをBean、Entityにセットするためのユーティリティです。

Commandのインスタンスとして当BeanParamMapperのインスタンスを保持し、 Command.execute(RequestContext)にて、#populate(Object, Map)呼び出すことにより、 パラメータの値を格納可能です。
パラメータ名（formのinputタグのnameなど）にて、beaｎのどのプロパティに値をセットするかを指定します。デフォルトの設定では、以下のような命名規則が適用されます。

  • パラメータ名と名前が一致するプロパティに値をセットします
  • "."により、ネストされたプロパティを表現します。
  • "[x]"(xは数値)により、List/配列のインデックス指定可能です。
  • "['key']"(keyは任意の文字列)により、Mapのキー指定可能です。
  • Mapのキー表現"propA['key']"は、propA.keyと表現も可能です。
パラメータの値は可能な限りbeanの各プロパティの型に自動変換を試みます。 変換出来なかった場合は、最終的にMappingExceptionがスローされます。MappingExceptionには、変換できなかった対象のプロパティと値が保持されます。

以下に、HTML上のFormのname定義と、その際呼び出されるメソッドのイメージの例を示します。

HTML上のFormでの定義呼び出されるメソッドのイメージ
<input type="text" name="age" value="25">formBean.setAge(25)
<input type="text" name="accout.mail" value="test@test.isid.co.jp">formBean.getAccount().setMail("test@test.isid.co.jp")
<input type="text" name="details[0].id" value="123">formBean.getDetails()[0].setId("123")
<input type="text" name="map['key1'].id" value="123">formBean.getMap().get('key1').setId("123")
<input type="text" name="map.key1.id" value="123">formBean.getMap().get('key1').setId("123")

また、name表現時のデリミタをdelimiters(char, char, char)にて設定することが可能です。それぞれのデリミタ文字はそれぞれ異なる必要があります。
ある特定のパラメータのみ自動マッピングしたい場合は、paramPrefixを指定可能です。指定した場合、paramPrefixに前方一致するパラメータのみマッピングされます。
whitelistPropertyNameRegexを指定することにより、明示的にセット可能なプロパティを正規表現にて制限することが可能です。

注意

当ユーティリティクラスを利用しパラメータを自動的にBeanに格納する際、パラメータ名、値は改竄の恐れがあることを十分注意してください。 入力値のチェックはもちろんのこと、特にパラメータ名も改竄されうることを認識し、その対策を行ってください。 各Formに対して、それぞれ個別のFormBeanを作成しない場合（Entityなどにダイレクトにマッピングする場合、複数のFormで共通のBeanを利用する場合など）は、 対策としてwhitelistPropertyNameRegexを指定し、設定可能なプロパティの範囲を制限してください。

autoGrowをtrueに設定した場合、ネストされたBeanがnullの場合、配列、List、Mapのサイズが足りない、またインスタンスがnullの場合、自動的に拡張させることが可能です。 インスタンスはプロパティとして定義される型のインスタンスが生成されます。List、Mapの場合はparameterized typeのインスタンスが生成されます。 配列、List、Mapのサイズの最大サイズは、indexedPropertySizeLimitで定義されます。この値以上のindex値を指定されたとしても自動拡張は行われません。 デフォルト値は128です。

また、withValidationをtrueに設定すると、マッピング処理の際にBeanValidtionに基づくバリデーションを実施することが可能です。 バリデーションにてエラーがある場合、最終的にMappingExceptionがスローされます。MappingExceptionには、バリデーションエラーとなったプロパティと値、エラーメッセージが保持されます。

以下にCommandでの利用例を示します。 

   public class SampleCommand implements Command {
     //BeanParamMapperのインスタンスをコンストラクト時に初期化
     private BeanParamMapper mapper = new BeanParamMapper().paramPrefix("_").whitelistPropertyNameRegex("^(age|name|details\..*)\\$");
 
     @Override
     public String execute(RequestContext request) {
       FormBean bean = new FormBean();
       
       //beanに値を格納。_age, _name, _details.id などparamPrefix、whitelistPropertyNameRegexにマッチするパラメータがプロパティにセットされる。
       mapper.populate(bean, request.getParamMap());
 
       //業務ロジックなど
       :
       :
       
       return "OK";
     }
 }
populate(Object, Map, Class...)メソッドはスレッドセーフですが、それ以外の delimiters(char, char, char)等の設定用メソッドがスレッドセーフではありません。 BeanParamMapperの初期化はCommandのコンストラクタ内で行い、executeメソッド内では設定変更は行わないでください。

  • フィールド詳細

  • コンストラクタの詳細

  • メソッドの詳細

    • withValidation

      public BeanParamMapper withValidation()
      パラメータをBeanにセットする際に、BeanValidationによるバリデーションを行うように設定します。
      戻り値:
      BeanParamMapper自身のインスタンス

    • enableAutoGrow

      public BeanParamMapper enableAutoGrow()
      ネストされたBean、List, 配列、Mapにおいて、パラメータ名で指定されるパスに値が存在しない場合、 自動的に拡張するように設定します。
      戻り値:
      BeanParamMapper自身のインスタンス

    • enableTrim

      public BeanParamMapper enableTrim()
      パラメータの値がStringの場合、trimを行うように設定します。
      戻り値:
      BeanParamMapper自身のインスタンス

    • enableEmptyToNull

      public BeanParamMapper enableEmptyToNull()
      パラメータの値が空文字の場合、nullに変換するように設定します。
      戻り値:
      BeanParamMapper自身のインスタンス

    • delimiters

      public BeanParamMapper delimiters​(char propertyDelimiter, char indexPrefix, char indexPostfix)
      パラメータ名のデリミタ表現を設定します。 各デリミタに指定する文字はそれぞれ異なる必要があります。
      パラメータ:
      propertyDelimiter - ネストされたプロパティを指定する際の文字
      indexPrefix - インデックス値を囲む先頭文字
      indexPostfix - インデックス値を囲む接尾文字
      戻り値:
      　BeanParamMapper自身のインスタンス

    • paramPrefix

      public BeanParamMapper paramPrefix​(java.lang.String paramPrefix)
      BeanMapperでbeanにマップするパラメータを限定するためのPrefixを設定します。 当該のparamPrefixと前方一致するパラメータのみbeanにマップされます。
      パラメータ:
      paramPrefix -
      戻り値:
      　BeanParamMapper自身のインスタンス

    • whitelistPropertyNameRegex

      public BeanParamMapper whitelistPropertyNameRegex​(java.lang.String whitelistPropertyNameRegex)
      設定可能なプロパティ名表現の正規表現を設定します。 正規表現によるチェックは、paramPrefixを取り除いた後に実施されるため、 正規表現には、paramPrefixは省いた形で指定します。
      パラメータ:
      whitelistPropertyNameRegex -
      戻り値:
      　BeanParamMapper自身のインスタンス

    • indexedPropertySizeLimit

      public BeanParamMapper indexedPropertySizeLimit​(int indexedPropertySizeLimit)
      autoGrowが有効化されている場合、List、配列、Mapにおいて自動拡張する最大サイズを設定します。
      パラメータ:
      indexedPropertySizeLimit -
      戻り値:
      　BeanParamMapper自身のインスタンス

    • typeConversionError

      public BeanParamMapper typeConversionError​(java.util.function.Consumer<MappingError> typeConversionErrorHandler)
      型変換に失敗した場合のエラーメッセージをカスタマイズするなどの処理を行う場合、セットします。 例） 
       BeanParamMapper mapper = new BeanParamMapper().typeConversionError(e -> e.addMessage("データの変換に失敗しました"))
      パラメータ:
      typeConversionErrorHandler - 引数のMappingErrorに対して、メッセージ等をセットするロジックを記述する
      戻り値:
      　BeanParamMapper自身のインスタンス

    • isTrim

      public boolean isTrim()

    • setTrim

      public void setTrim​(boolean trim)

    • isEmptyToNull

      public boolean isEmptyToNull()

    • setEmptyToNull

      public void setEmptyToNull​(boolean emptyToNull)

    • isAutoGrow

      public boolean isAutoGrow()

    • setAutoGrow

      public void setAutoGrow​(boolean autoGrow)

    • getWithValidation

      public boolean getWithValidation()

    • setWithValidation

      public void setWithValidation​(boolean withValidation)

    • getPropertyDelimiter

      public char getPropertyDelimiter()

    • setPropertyDelimiter

      public void setPropertyDelimiter​(char propertyDelimiter)

    • getIndexPrefix

      public char getIndexPrefix()

    • setIndexPrefix

      public void setIndexPrefix​(char indexPrefix)

    • getIndexPostfix

      public char getIndexPostfix()

    • setIndexPostfix

      public void setIndexPostfix​(char indexPostfix)

    • getIndexedPropertySizeLimit

      public int getIndexedPropertySizeLimit()

    • setIndexedPropertySizeLimit

      public void setIndexedPropertySizeLimit​(int indexedPropertySizeLimit)

    • getParamPrefix

      public java.lang.String getParamPrefix()

    • setParamPrefix

      public void setParamPrefix​(java.lang.String paramPrefix)

    • getWhitelistPropertyNameRegex

      public java.lang.String getWhitelistPropertyNameRegex()

    • setWhitelistPropertyNameRegex

      public void setWhitelistPropertyNameRegex​(java.lang.String whitelistPropertyNameRegex)

    • getTypeConversionErrorHandler

      public java.util.function.Consumer<MappingError> getTypeConversionErrorHandler()

    • setTypeConversionErrorHandler

      public void setTypeConversionErrorHandler​(java.util.function.Consumer<MappingError> typeConversionErrorHandler)

    • populate

      public void populate​(java.lang.Object bean, java.util.Map<java.lang.String,​java.lang.Object> params, java.lang.Class<?>... validationGroups) throws MappingException
      指定のbeanに、paramsで指定されるパラメータをセットします。
      パラメータ:
      bean -
      params -
      validationGroups - validationを行う場合（withValidation=true）、BeanValidaitonのvalidationGroupsを指定可能
      例外:
      MappingException - マッピング処理時に型変換エラー、Validationエラーが発生した場合スロー

    • validate

      public void validate​(java.lang.Object bean, java.lang.Class<?>... validationGroups) throws MappingException
      明示的に指定のbeanに対してValidationを実行します。
      パラメータ:
      bean -
      validationGroups - BeanValidaitonのvalidationGroupsを指定可能
      例外:
      MappingException - Validationエラーが発生した場合スロー