+ + +

ConvertUtils is part of commons-beanutils -and it can be used to flexibly convert strings to objects and back again. Betwixt uses ConvertUtils to +and it can be used to flexibly convert strings to objects and back again. By default, Betwixt uses ConvertUtils to perform these conversions and so standard ConvertUtils methods can be called to customize these conversions. -

- - +

+ + +

+There are numerous situations when read beans from xml or writing beans to xml that String to Object +or Object to String conversions are required. Betwixt uses a Strategy class to allow a convenient +default which will work well for most basic users whilst allowing advanced users to fully hook in and +customize this process. +

+The default strategy uses ConvertUtils from +commons-beanutils to perform these conversions. +This is a powerful component that allows flexible customization of the conversion process. +

+There is one exception to this rule. If the class is a java.util.Date - or a subclass of java.util.Date which is not a subclass of java.sql.Date, java.sql.Time or java.sql.Timestamp - then this is converted to and from a string following this pattern: +

  +    EEE MMM dd HH:mm:ss zzz yyyy
  +

+(using the SimpleDateFormat notation). Observent readers will realise that this is the same pattern +that is returned by java.util.Date.toString - and that's why this pattern was chosen. +It provides a good default for casual users. +

+Advanced users will probably need a particular date format. The recommended way to do this is through +registering appropriate converters with ConvertUtils. The default conversion strategy must also be +replaced with an instance of + +ConvertUtilsObjectStringConverter. This is set though a BindingConfiguration property. +

+For example, to delegate to ConvertUtils for all conversions in a read: +

  +    BeanReader reader = new BeanReader();
  +    reader.getBindingConfiguration(new ConvertUtilsObjectStringConverter());
  +    reader.parse...
  +

+and in a write: +

  +    BeanWriter writer = new BeanWriter();
  +    writer.getBindingConfiguration(new ConvertUtilsObjectStringConverter());
  +    writer.write...
  +

+ + +

+ConvertUtils is flexible and powerful. It comes with a range of Converter +implementations which allow quick and easy customization. But, there are occasions where this will +not suit all the requirements of the user. Betwixt supports this need by allowing a custom +ObjectStringConverter to be plugged in. +

+The strategy class +ObjectStringConverter +is simple: containing only two simple methods. For more information about creating subclasses, see the javadocs. +The implementation to be used is set through the BindingConfiguration +ObjectStringConverter property. +

+For example, to set a custom ObjectStringConverter for all conversions in a read: +

  +    ObjectStringConverter converter = new MyObjectStringConverter();
  +    BeanReader reader = new BeanReader();
  +    reader.getBindingConfiguration(converter);
  +    reader.parse...
  +

+and in a write: +

  +    ObjectStringConverter converter = new MyObjectStringConverter();
  +    BeanWriter writer = new BeanWriter();
  +    writer.getBindingConfiguration(converter);
  +    writer.write...
  +

+Betwixt is distributed with a range of ObjectStringConverter's in the +org.apache.commons.betwixt.strategy package. Examining the source code for these classes +is a good please to start when creating your own implementation. +