Improve documentation on default PropertyEditors [SPR-8388]

Sam Brannen opened SPR-8388 and commented

Background

Using the Spring Reference Manual alone, it is currently rather challenging for developers new to Spring to determine exactly which PropertyEditors are registered by default in an ApplicationContext.

It is not obvious to newbies that:

1. PropertyEditors can be used not only for explicit bean properties but also for XML namespace attributes
2. various *ArrayEditors are registered by default, thus supporting comma-separated lists of elements in a single property/attribute
   • for example, ByteArrayPropertyEditor, CharArrayPropertyEditor, StringArrayPropertyEditor, ClassArrayEditor, ResourceArrayPropertyEditor, etc.
3. pattern matching can be used for all supported Resources

Current Default PropertyEditors

The PropertyEditors that are actually registered by default in a Spring ApplicationContext can be found in the code here:

• ResourceEditorRegistrar: registerCustomEditors(PropertyEditorRegistry)
• PropertyEditorRegistrySupport: createDefaultEditors()

Goals

The following sections of the Reference Manual need to be updated with the current set of defaults and more examples of how to actually benefit from PropertyEditors in XML-based configuration. It would be beneficial to the reader to cross reference between these sections. Furthermore, table 5.2 (Built-in PropertyEditors) could be greatly improved by adding a new "Registered by default" column.

• Built-in Resource Implementations
• Resources as Dependencies
• Built-in PropertyEditor Implementations

Concrete examples with context:property-placeholder

It would be helpful to provide examples of using PropertyEditors in conjunction with XML namespaces. I have often heard the question, "How can I supply more than one location for property placeholder replacement using the context:property-placeholder namespace element?" As of Spring 3.0.5, there are zero examples in the reference manual that use either a comma-separated list of locations or wildcards for pattern matching; all current examples supply a single property file as the location.

Affects: 3.0.5

1 votes, 3 watchers

Start by reviewing ResourceEditorRegistrar.registerCustomEditors(PropertyEditorRegistry) and PropertyEditorRegistrySupport.createDefaultEditors() to establish the current defaults. Update the three named Reference Manual sections and table 5.2 with the default registrations, cross-references, and XML examples using comma-separated locations and wildcard patterns. Done means the manual clearly explains the defaults and how to use them with context:property-placeholder.