Properties Module

Contents

Properties Module

The Properties module (located in the xwiki-properties directory) provides an easy way to handle Java Beans properties and conversion between Java type and strings.

We previously used BeanUtils, for macros for example, but several needs were not covered by BeanUtils, so we started our own populate methods and the needed api around it. Basically the differences with BeanUtils are:

  • We needed to support any case for the properties names for macros
  • We needed to be able to inject custom fields in a bean for Wiki macros
  • We needed to support some annotation tweak in the bean description to make it easier to provide useful information, to the WYSIWYG for example, or to modify the behavior of the populate process, like making a property mandatory or hidden
  • BeanUtils does not support public fields (the Groovy way)
  • It's possible to implement a Converter component which can access anything an XWiki component can access so that you would be able to convert types like String into Document, etc.
  • Users are using only api/interface and any implementation component can be done for it.

Note that it's not a complete rewrite of BeanUtils. Xwiki-properties still use useful tools of javax.beans and ConvertUtils. The only things that have been completely rewritten are the populate method and the BeanInfo, that has been extended as a BeanDescriptor (to contain public fields, text description, etc.).

BeanManager

Populate a Java Bean

To populate a Map into a java bean use #populate(Object, Map<String, ? >).

By default a bean is parsed as follows:

  • java.beansIntrospector#getBeanInfo(Class<?>) is used to get standard BeanInfo properties which are based on getters and setters names. See BeanInfo javadoc.
  • Public fields produce also properties
  • Any case is supported for properties names when populating
  • Each property is converted on the fly from the provided value to the property JAVA type using ConverterManager.

Then it's possible to tweak this behavior with annotation:

  • org.xwiki.properties.annotation.PropertyDescription: a text describing the property
  • org.xwiki.properties.annotation.PropertyHidden: indicate that the property should not be taken into account by BeanManager
  • org.xwiki.properties.annotation.PropertyMandatory: indicate that an error should be generated when no value is provided in the Map for this property when populating.

Finally default implementation of BeanManager support JSR 303 (Bean Validation).

Failed to execute macro: code
Failed to execute macro: code

Get bean descriptor

It's possible to ask BeanManager descriptor generated from a Java Bean for easy listing of properties, values, etc. For example this is used to fill ParameterDescriptors of most of the Java-based macros.

ConverterManager

The default implementation of ConverterManager supports:

  • Any Apache ConvertUtils conversion
  • Any Enum child type
  • java.awt.Color

Convert a value in a target Java type

To convert a value you can use the default implementation of org.xwiki.properties.ConverterManager component interface and its convert method.

ConverterManager converterManager = componentManager.lookup(ConverterManager.class);
Integer intValue = converterManager.convert(Integer.class, "42");
ConverterManager converterManager = componentManager.lookup(ConverterManager.class);
Integer intValue = converterManager.convert(Integer.class, "42");

Add a new Converter

There are two ways to add support for new types.

Converter component (Recommended)

You can add a new converter by implementing org.xwiki.properties.converter.Converter component interface. It's recommended to extend org.xwiki.properties.converter.AbstractConverter, which provides some helper to create a new Converter.

The minimum for an AbstractConverter child is:

  • Implements #convertToType(java.lang.Class, java.lang.Object)
  • Set the type name as component role hint
Failed to execute macro: code

Apache ConvertUtils Converter


When convert manager can't find a specific converter for a type it uses Apache ConvertUtils. You can look at http://commons.apache.org/beanutils/ to find out how to add new converters.

Tags:
Created by Thomas Mortagne on 2009/07/26 15:00
Last modified by Silvia Rusu on 2009/10/29 10:44
This wiki is licensed under a Creative Commons license
2.2.1.27354