Chapter 5. PropertyEditors, data binding, validation and the BeanWrapper

5.1. Introduction

The big question is whether or not validation should be considered business logic. There are pros and cons for both answers, and Spring offers a design for validation (and data binding) that does not exclude either one of them. Validation should specifically not be tied to the web tier, should be easy to localize and it should be possible to plug in any validator available. Considering the above, Spring has come up with a Validator interface that's both basic and usable in every layer of an application.

Data binding is useful for allowing user input to be dynamically bound to the domain model of an application (or whatever objects you use to process user input). Spring provides the so-called DataBinder to do exactly that. The Validator and the DataBinder make up the validation package, which is primarily used in but not limited to the MVC framework.

The BeanWrapper is a fundamental concept in the Spring Framework and is used in a lot of places. However, you probably will not ever have the need to use the BeanWrapper directly. Because this is reference documentation however, we felt that some explanation might be right. We're explaining the BeanWrapper in this chapter since if you were going to use it at all, you would probably do that when trying to bind data to objects, which is strongly related to the BeanWrapper.

Spring uses PropertyEditors all over the place. The concept of a PropertyEditor is part of the JavaBeans specification. Just as the BeanWrapper, it's best to explain the use of PropertyEditors in this chapter as well, since it's closely related to the BeanWrapper and the DataBinder.

5.2. Binding data using the DataBinder

The DataBinder builds on top of the BeanWrapper[2].

5.3. Bean manipulation and the BeanWrapper

The org.springframework.beans package adheres to the JavaBeans standard provided by Sun. A JavaBean is simply a class with a default no-argument constructor, which follows a naming conventions where a property named prop has a setter setProp(...) and a getter getProp(). For more information about JavaBeans and the specification, please refer to Sun's website (java.sun.com/products/javabeans).

One quite important concept of the beans package is the BeanWrapper interface and its corresponding implementation (BeanWrapperImpl). As quoted from the JavaDoc, the BeanWrapper offers functionality to set and get property values (individually or in bulk), get property descriptors, and to query properties to determine if they are readable or writable. Also, the BeanWrapper offers support for nested properties, enabling the setting of properties on sub-properties to an unlimited depth. Then, the BeanWrapper supports the ability to add standard JavaBeans PropertyChangeListeners and VetoableChangeListeners, without the need for supporting code in the target class. Last but not least, the BeanWrapper provides support for the setting of indexed properties. The BeanWrapper usually isn't used by application code directly, but by the DataBinder and the BeanFactory.

The way the BeanWrapper works is partly indicated by its name: it wraps a bean to perform actions on that bean, like setting and retrieving properties.

5.3.1. Setting and getting basic and nested properties

Setting and getting properties is done using the setPropertyValue(s) and getPropertyValue(s) methods that both come with a couple of overloaded variants. They're all described in more detail in the JavaDoc Spring comes with. What's important to know is that there are a couple of conventions for indicating properties of an object. A couple of examples:

Table 5.1. Examples of properties

ExpressionExplanation
nameIndicates the property name corresponding to the methods getName() or isName() and setName()
account.nameIndicates the nested property name of the property account corresponding e.g. to the methods getAccount().setName() or getAccount().getName()
account[2]Indicates the third element of the indexed property account. Indexed properties can be of type array, list or other naturally ordered collection
account[COMPANYNAME]Indicates the value of the map entry indexed by the key COMPANYNAME of the Map property account

Below you'll find some examples of working with the BeanWrapper to get and set properties.

Note: this part is not important to you if you're not planning to work with the BeanWrapper directly. If you're just using the DataBinder and the BeanFactory and their out-of-the-box implementation, you should skip ahead to the section about PropertyEditors.

Consider the following two classes:

public class Company {
    private String name;
    private Employee managingDirector;

    public String getName()	{ 
        return this.name; 
    }
    public void setName(String name) { 
        this.name = name; 
    } 
    public Employee getManagingDirector() { 
        return this.managingDirector; 
    }
    public void setManagingDirector(Employee managingDirector) {
        this.managingDirector = managingDirector;
    }
}

public class Employee {
    private float salary;

    public float getSalary() {
        return salary;
    }
    public void setSalary(float salary) {
        this.salary = salary;
    }
}

The following code snippets show some examples of how to retrieve and manipulate some of the properties of instantiated Companies and Employees:

Company c = new Company();
BeanWrapper bwComp = BeanWrapperImpl(c);
// setting the company name...
bwComp.setPropertyValue("name", "Some Company Inc.");
// ... can also be done like this:
PropertyValue v = new PropertyValue("name", "Some Company Inc.");
bwComp.setPropertyValue(v);

// ok, let's create the director and tie it to the company:
Employee jim = new Employee();
BeanWrapper bwJim = BeanWrapperImpl(jim);
bwJim.setPropertyValue("name", "Jim Stravinsky");
bwComp.setPropertyValue("managingDirector", jim);

// retrieving the salary of the managingDirector through the company
Float salary = (Float)bwComp.getPropertyValue("managingDirector.salary");

5.3.2. Built-in PropertyEditors, converting types

Spring heavily uses the concept of PropertyEditors. Sometimes it might be handy to be able to represent properties in a different way than the object itself. For example, a date can be represented in a human readable way, while we're still able to convert the human readable form back to the original date (or even better: convert any date entered in a human readable form, back to Date objects). This behavior can be achieved by registering custom editors, of type java.beans.PropertyEditor. Registering custom editors on a BeanWrapper or alternately in a specific Application Context as mentioned in the previous chapter, gives it the knowledge of how to convert properties to the desired type. Read more about PropertyEditors in the JavaDoc of the java.beans package provided by Sun.

A couple of examples where property editing is used in Spring

  • setting properties on beans is done using PropertyEditors. When mentioning java.lang.String as the value of a property of some bean you're declaring in XML file, Spring will (if the setter of the corresponding property has a Class-parameter) use the ClassEditor to try to resolve the parameter to a Class object

  • parsing HTTP request parameters in Spring's MVC framework is done using all kinds of PropertyEditors that you can manually bind in all subclasses of the CommandController

Spring has a number of built-in PropertyEditors to make life easy. Each of those is listed below and they are all located in the org.springframework.beans.propertyeditors package. Most, but not all (as indicated below), are registered by default by BeanWrapperImpl. Where the property editor is configurable in some fashion, you can of course still register your own variant to override the default one:

Table 5.2. Built-in PropertyEditors

ClassExplanation
ByteArrayPropertyEditorEditor for byte arrays. Strings will simply be converted to their corresponding byte representations. Registered by default by BeanWrapperImpl.
ClassEditorParses Strings representing classes to actual classes and the other way around. When a class is not found, an IllegalArgumentException is thrown. Registered by default by BeanWrapperImpl.
CustomBooleanEditorCustomizable property editor for Boolean properties. Registered by default by BeanWrapperImpl, but, can be overridden by registering custom instance of it as custom editor.
CustomCollectionEditorProperty editor for Collections, converting any source Collection to a given target Collection type.
CustomDateEditorCustomizable property editor for java.util.Date, supporting a custom DateFormat. NOT registered by default. Must be user registered as needed with appropriate format.
CustomNumberEditorCustomizable property editor for any Number subclass like Integer, Long, Float, Double. Registered by default by BeanWrapperImpl, but, can be overridden by registering custom instance of it as custom editor.
FileEditorCapable of resolving Strings to java.io.File objects. Registered by default by BeanWrapperImpl.
InputStreamEditorOne-way property editor, capable of taking a text string and producing (via an intermediate ResourceEditor and Resource) an InputStream, so InputStream properties may be directly set as Strings. Note that the default usage will not close the InputStream for you! Registered by default by BeanWrapperImpl.
LocaleEditorCapable of resolving Strings to Locale objects and vice versa (the String format is [language]_[country]_[variant], which is the same thing the toString() method of Locale provides). Registered by default by BeanWrapperImpl.
PropertiesEditorCapable of converting Strings (formatted using the format as defined in the Javadoc for the java.lang.Properties class) to Properties objects. Registered by default by BeanWrapperImpl.
StringArrayPropertyEditorCapable of resolving a comma-delimited list of String to a String-array and vice versa. Registered by default by BeanWrapperImpl.
StringTrimmerEditorProperty editor that trims Strings. Optionally allows transforming an empty string into a null value. NOT registered by default. Must be user registered as needed.
URLEditorCapable of resolving a String representation of a URL to an actual URL object. Registered by default by BeanWrapperImpl.

Spring uses the java.beans.PropertyEditorManager to set the search path for property editors that might be needed. The search path also includes sun.bean.editors, which includes PropertyEditors for Font, Color and all the primitive types. Note also that the standard JavaBeans infrastructure will automatically discover PropertyEditors (without you having to register them) if they are in the same package as the class they handle, and have the same name as that class, with 'Editor' appended.

5.3.3. Other features worth mentioning

Besides the features you've seen in the previous sections there a couple of features that might be interesting to you, though not worth an entire section.

  • determining readability and writability: using the isReadable() and isWritable() methods, you can determine whether or not a property is readable or writable

  • retrieving PropertyDescriptors: using getPropertyDescriptor(String) and getPropertyDescriptors() you can retrieve objects of type java.beans.PropertyDescriptor, that might come in handy sometimes

5.4. Validation using Spring's Validator interface

Spring's features a Validator interface you can use to validate objects. The Validator interface, is pretty straightforward and works using with a so-called Errors object. In other words, while validating, validators will report validation failures to the Errors object.

As said already, the Validator interface is pretty straightforward, just as implementing one yourself. Let's consider a small data object:

public class Person {
  private String name;
  private int age;

  // the usual suspects: getters and setters
}

Using the org.springframework.validation.Validator interface we're going to provide validation behavior for the Person class. This is the Validator interface:

  • supports(Class) - indicates whether or not this validator supports the given object

    validate(Object, org.springframework.validation.Errors) - validates the given object and in case of validation errors, put registers those with the given Errors object

Implementing a validator is fairly straightforward, especially when you know of the ValidationUtils Spring also provides. Let's review how a validator is created:

public class PersonValidator implements Validator {
	
	public boolean supports(Class clzz) {
		return Person.class.equals(clzz);
	}
	
	public void validate(Object obj, Errors e) {
		ValidationUtils.rejectIfEmpty(e, "name", "name.empty");
		Person p = (Person)obj;
		if (p.getAge() < 0) {
			e.rejectValue("age", "negativevalue");
		} else if (p.getAge() > 110) {
			e.rejectValue("age", "tooold");
		}
	}
}

As you can see, the ValidationUtils is used to reject the name property. Have a look at the JavaDoc for ValidationUtils to see what functionality it provides besides the example we gave just now.

5.5. The Errors interface

Validation errors are reported to the Errors object passed to the validator. In case of Spring Web MVC you can use spring:bind tags to inspect the error messages, but of course you can also inspect the errors object yourself. The methods it offers are pretty straightforward. More information can be found in the JavaDoc.

5.6. Resolving codes to error messages

We've talked about databinding and validation. Outputting messages corresponding to validation errors is the last thing we need to discuss. In the example we've shown above, we rejected the name and the age field. If, using a MessageSource, we're going to output the error messages we will do so using the error code we've given when rejecting the field ('name' and 'age' in this case). When you call (either directly, or indirectly, using for example the ValidationUtils class) rejectValue or one of the other reject method from the Errors interface, the underlying implementation will not only register the code, you've passed in, but also a number of additional error codes. What error codes it registers is determined by the MessageCodesResolver that is used. By default, the DefaultMessageCodesResolver is used, which for example not only register a message with the code you gave, but also messages that include the field name you passed to the reject method. So in case you reject a field using rejectValue("age", "tooold"), apart from the tooold code, Spring will also register tooold.age and tooold.age.int (so the first will include the field name and the second will include the type of the field).

More information on the MessageCodesResolver and the default strategy can be found online with the JavaDocs for MessageCodesResolver and DefaultMessageCodesResolver respectively.



[2] See the beans chapter for more information