SPR-7311 - Clarify usage of PropertyEditorRegistrars VS. plain configuration of customEditors property in CustomEditorConfigurer JavaDoc.

git-svn-id: https://src.springframework.org/svn/spring-framework/trunk@3441 50f2f4bb-b051-0410-bef5-90022cba6387

org.springframework.beans/src/main/java/org/springframework/beans/factory/config/CustomEditorConfigurer.java

@@ -35,13 +35,15 @@ import org.springframework.util.ClassUtils;
 /**
  * {@link BeanFactoryPostProcessor} implementation that allows for convenient
  * registration of custom {@link PropertyEditor property editors}.
- *
- * <p>As of Spring 2.0, the recommended usage is to use custom
- * {@link PropertyEditorRegistrar} implementations that in turn register
- * any desired editors on a given
- * {@link org.springframework.beans.PropertyEditorRegistry registry}.
- * Each PropertyEditorRegistrar can register any number of custom editors.
- *
+ * 
+ * <p>
+ * In case you want to register {@link PropertyEditor} instances, the
+ * recommended usage as of Spring 2.0 is to use custom
+ * {@link PropertyEditorRegistrar} implementations that in turn register any
+ * desired editor instances on a given
+ * {@link org.springframework.beans.PropertyEditorRegistry registry}. Each
+ * PropertyEditorRegistrar can register any number of custom editors.
+ * 
  * <pre class="code">
  * &lt;bean id="customEditorConfigurer" class="org.springframework.beans.factory.config.CustomEditorConfigurer"&gt;
  *   &lt;property name="propertyEditorRegistrars"&gt;
@@ -50,10 +52,14 @@ import org.springframework.util.ClassUtils;
  *       &lt;bean class="mypackage.MyObjectEditorRegistrar"/&gt;
  *     &lt;/list&gt;
  *   &lt;/property&gt;
- * &lt;/bean&gt;</pre>
- *
- * <p>Alternative configuration example with custom editor classes:
- *
+ * &lt;/bean&gt;
+ * </pre>
+ * 
+ * <p>
+ * It's perfectly fine to register {@link PropertyEditor} <em>classes</em> via
+ * the {@code customEditors} property. Spring will create fresh instances of
+ * them for each editing attempt then:
+ * 
  * <pre class="code">
  * &lt;bean id="customEditorConfigurer" class="org.springframework.beans.factory.config.CustomEditorConfigurer"&gt;
  *   &lt;property name="customEditors"&gt;
@@ -62,9 +68,19 @@ import org.springframework.util.ClassUtils;
  *       &lt;entry key="mypackage.MyObject" value="mypackage.MyObjectEditor"/&gt;
  *     &lt;/map&gt;
  *   &lt;/property&gt;
- * &lt;/bean&gt;</pre>
- *
- * <p>Also supports "java.lang.String[]"-style array class names and primitive
+ * &lt;/bean&gt;
+ * </pre>
+ * 
+ * <p>
+ * Note, that you shouldn't register {@link PropertyEditor} bean instances via
+ * the {@code customEditors} property as {@link PropertyEditor}s are stateful
+ * and the instances will then have to be synchronized for every editing
+ * attempt. In case you need control over the instantiation process of
+ * {@link PropertyEditor}s, use a {@link PropertyEditorRegistrar} to register
+ * them.
+ * 
+ * <p>
+ * Also supports "java.lang.String[]"-style array class names and primitive
  * class names (e.g. "boolean"). Delegates to {@link ClassUtils} for actual
  * class name resolution.
  *