1460 lines
72 KiB
XML
1460 lines
72 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
|
|
|
|
<chapter id="validation">
|
|
<title>Validation, Data Binding, and Type Conversion</title>
|
|
|
|
<section id="validation-introduction">
|
|
<title>Introduction</title>
|
|
|
|
<para>There are pros and cons for considering validation as business logic,
|
|
and Spring offers a design for validation (and data binding) that
|
|
does not exclude either one of them. Specifically validation should 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 <interfacename>Validator</interfacename> interface that
|
|
is both basic and eminently usable in every layer of an application.</para>
|
|
|
|
<para>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
|
|
<interfacename>DataBinder</interfacename> to do exactly that. The
|
|
<interfacename>Validator</interfacename> and the
|
|
<interfacename>DataBinder</interfacename> make up the <literal>validation</literal> package,
|
|
which is primarily used in but not limited to the MVC framework.</para>
|
|
|
|
<para>The <interfacename>BeanWrapper</interfacename> is a fundamental concept in the
|
|
Spring Framework and is used in a lot of places. However, you probably
|
|
will not have the need to use the <interfacename>BeanWrapper</interfacename> directly. Because this
|
|
is reference documentation however, we felt that some explanation might be
|
|
in order. We will explain the <interfacename>BeanWrapper</interfacename> in this chapter since, if you were
|
|
going to use it at all, you would most likely do so when trying to bind data to objects.</para>
|
|
|
|
<para>Spring's DataBinder and the lower-level BeanWrapper both use PropertyEditors to parse and format property values.
|
|
The <interfacename>PropertyEditor</interfacename> concept is part of the JavaBeans specification, and is also explained in this chapter.
|
|
Spring 3 introduces a "core.convert" package that provides a general type conversion facility, as well as a higher-level "format" package for formatting UI field values.
|
|
These new packages may be used as simpler alternatives to PropertyEditors, and will also be discussed in this chapter.</para>
|
|
|
|
</section>
|
|
|
|
<section id="validator">
|
|
<title>Validation using Spring's <interfacename>Validator</interfacename> interface</title>
|
|
<para>Spring's features a <interfacename>Validator</interfacename> interface that you can
|
|
use to validate objects. The <interfacename>Validator</interfacename> interface works using
|
|
an <interfacename>Errors</interfacename> object so that while validating, validators can report
|
|
validation failures to the <interfacename>Errors</interfacename> object.</para>
|
|
<para>Let's consider a small data object:</para>
|
|
<programlisting language="java"><![CDATA[
|
|
public class Person {
|
|
|
|
private String name;
|
|
private int age;
|
|
|
|
]]><lineannotation>// the usual getters and setters...</lineannotation><![CDATA[
|
|
}]]></programlisting>
|
|
<para>We're going to provide validation behavior for the <classname>Person</classname>
|
|
class by implementing the following two methods of the
|
|
<interfacename>org.springframework.validation.Validator</interfacename> interface:
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para><methodname>supports(Class)</methodname> - Can this
|
|
<interfacename>Validator</interfacename> validate instances of the supplied
|
|
<classname>Class</classname>?</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><methodname>validate(Object, org.springframework.validation.Errors)</methodname> -
|
|
validates the given object and in case of validation errors, registers
|
|
those with the given <interfacename>Errors</interfacename> object</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<para>
|
|
Implementing a <interfacename>Validator</interfacename> is fairly straightforward,
|
|
especially when you know of the <classname>ValidationUtils</classname> helper class
|
|
that the Spring Framework also provides.</para>
|
|
<programlisting language="java"><![CDATA[public class PersonValidator implements Validator {
|
|
|
|
]]><lineannotation>/**
|
|
* This <interfacename>Validator</interfacename> validates <emphasis role="bold">just</emphasis> <classname>Person</classname> instances
|
|
*/</lineannotation><![CDATA[
|
|
public boolean supports(Class clazz) {
|
|
return Person.class.equals(clazz);
|
|
}
|
|
|
|
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", "too.darn.old");
|
|
}
|
|
}
|
|
}]]></programlisting>
|
|
<para>As you can see, the <literal>static</literal> <methodname>rejectIfEmpty(..)</methodname>
|
|
method on the <classname>ValidationUtils</classname> class is used to reject the
|
|
<literal>'name'</literal> property if it is <literal>null</literal> or the empty string.
|
|
Have a look at the Javadoc for the <classname>ValidationUtils</classname> class to see
|
|
what functionality it provides besides the example shown previously.</para>
|
|
<para>While it is certainly possible to implement a single
|
|
<interfacename>Validator</interfacename> class to validate each of the nested objects
|
|
in a rich object, it may be better to encapsulate the validation logic for each nested
|
|
class of object in its own <interfacename>Validator</interfacename> implementation. A
|
|
simple example of a <emphasis>'rich'</emphasis> object would be a
|
|
<classname>Customer</classname> that is composed of two <classname>String</classname>
|
|
properties (a first and second name) and a complex <classname>Address</classname> object.
|
|
<classname>Address</classname> objects may be used independently of
|
|
<classname>Customer</classname> objects, and so a distinct
|
|
<classname>AddressValidator</classname> has been implemented. If you want your
|
|
<classname>CustomerValidator</classname> to reuse the logic contained within the
|
|
<classname>AddressValidator</classname> class without recourse to copy-n-paste you can
|
|
dependency-inject or instantiate an <classname>AddressValidator</classname> within your
|
|
<classname>CustomerValidator</classname>, and use it like so:</para>
|
|
<programlisting language="java"><![CDATA[public class CustomerValidator implements Validator {
|
|
|
|
private final Validator addressValidator;
|
|
|
|
public CustomerValidator(Validator addressValidator) {
|
|
if (addressValidator == null) {
|
|
throw new IllegalArgumentException("The supplied [Validator] is required and must not be null.");
|
|
}
|
|
if (!addressValidator.supports(Address.class)) {
|
|
throw new IllegalArgumentException(
|
|
"The supplied [Validator] must support the validation of [Address] instances.");
|
|
}
|
|
this.addressValidator = addressValidator;
|
|
}
|
|
|
|
]]><lineannotation>/**
|
|
* This <interfacename>Validator</interfacename> validates <classname>Customer</classname> instances, and any subclasses of <classname>Customer</classname> too
|
|
*/</lineannotation><![CDATA[
|
|
public boolean supports(Class clazz) {
|
|
return Customer.class.isAssignableFrom(clazz);
|
|
}
|
|
|
|
public void validate(Object target, Errors errors) {
|
|
ValidationUtils.rejectIfEmptyOrWhitespace(errors, "firstName", "field.required");
|
|
ValidationUtils.rejectIfEmptyOrWhitespace(errors, "surname", "field.required");
|
|
Customer customer = (Customer) target;
|
|
try {
|
|
errors.pushNestedPath("address");
|
|
ValidationUtils.invokeValidator(this.addressValidator, customer.getAddress(), errors);
|
|
} finally {
|
|
errors.popNestedPath();
|
|
}
|
|
}
|
|
}]]></programlisting>
|
|
<para>Validation errors are reported to the <interfacename>Errors</interfacename>
|
|
object passed to the validator. In case of Spring Web MVC you can use
|
|
<literal><spring:bind/></literal> tag to inspect the error messages, but
|
|
of course you can also inspect the errors object yourself. More information about
|
|
the methods it offers can be found from the Javadoc.</para>
|
|
</section>
|
|
<section id="validation-conversion">
|
|
<title>Resolving codes to error messages</title>
|
|
<para>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 <literal>name</literal> and the <literal>age</literal> field.
|
|
If we're going to output the error messages by using a <interfacename>MessageSource</interfacename>,
|
|
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
|
|
<classname>ValidationUtils</classname> class) <literal>rejectValue</literal> or one of
|
|
the other <literal>reject</literal> methods from the <interfacename>Errors</interfacename>
|
|
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 <interfacename>MessageCodesResolver</interfacename> that is used.
|
|
By default, the <classname>DefaultMessageCodesResolver</classname> is used, which for example
|
|
not only registers 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
|
|
<literal>rejectValue("age", "too.darn.old")</literal>, apart from the
|
|
<literal>too.darn.old</literal> code, Spring will also register
|
|
<literal>too.darn.old.age</literal> and <literal>too.darn.old.age.int</literal>
|
|
(so the first will include the field name and the second will include the type of the
|
|
field); this is done as a convenience to aid developers in targeting error
|
|
messages and suchlike.</para>
|
|
<para>More information on the <interfacename>MessageCodesResolver</interfacename> and the default
|
|
strategy can be found online with the Javadocs for
|
|
<ulink url="http://static.springframework.org/spring/docs/2.5.x/api/org/springframework/validation/MessageCodesResolver.html">MessageCodesResolver</ulink>
|
|
and
|
|
<ulink url="http://static.springframework.org/spring/docs/2.5.x/api/org/springframework/validation/DefaultMessageCodesResolver.html">DefaultMessageCodesResolver</ulink>
|
|
respectively.</para>
|
|
</section>
|
|
|
|
<section id="beans-beans">
|
|
<title>Bean manipulation and the <interfacename>BeanWrapper</interfacename></title>
|
|
|
|
<para>The <literal>org.springframework.beans</literal> 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 convention
|
|
where (by way of an example) a property named <literal>bingoMadness</literal> would have a setter
|
|
method <methodname>setBingoMadness(..)</methodname> and a getter method <methodname>getBingoMadness()</methodname>.
|
|
For more information about JavaBeans and the specification, please refer
|
|
to Sun's website ( <ulink url="http://java.sun.com/products/javabeans/">java.sun.com/products/javabeans</ulink>).</para>
|
|
|
|
<para>One quite important class in the beans package is the
|
|
<interfacename>BeanWrapper</interfacename> interface and its corresponding
|
|
implementation (<classname>BeanWrapperImpl</classname>). As quoted from the
|
|
Javadoc, the <interfacename>BeanWrapper</interfacename> 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
|
|
<interfacename>BeanWrapper</interfacename> offers support for nested properties, enabling the setting of
|
|
properties on sub-properties to an unlimited depth. Then, the <interfacename>BeanWrapper</interfacename>
|
|
supports the ability to add standard JavaBeans
|
|
<interfacename>PropertyChangeListeners</interfacename> and
|
|
<interfacename>VetoableChangeListeners</interfacename>, without the need for
|
|
supporting code in the target class. Last but not least, the <interfacename>BeanWrapper</interfacename>
|
|
provides support for the setting of indexed properties. The <interfacename>BeanWrapper</interfacename>
|
|
usually isn't used by application code directly, but by the
|
|
<interfacename>DataBinder</interfacename> and the
|
|
<interfacename>BeanFactory</interfacename>.</para>
|
|
|
|
<para>The way the <interfacename>BeanWrapper</interfacename> works is partly indicated by its name:
|
|
<emphasis>it wraps a bean</emphasis> to perform actions on that bean, like
|
|
setting and retrieving properties.</para>
|
|
|
|
<section id="beans-beans-conventions">
|
|
<title>Setting and getting basic and nested properties</title>
|
|
|
|
<para>Setting and getting properties is done using the
|
|
<literal>setPropertyValue(s)</literal> and
|
|
<literal>getPropertyValue(s)</literal> 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:</para>
|
|
<table id="beans-beans-conventions-properties-tbl">
|
|
<title>Examples of properties</title>
|
|
|
|
<tgroup cols="2">
|
|
<colspec colname="c1" colwidth="1*" />
|
|
<colspec colname="c2" colwidth="3*" />
|
|
<thead>
|
|
<row>
|
|
<entry>Expression</entry>
|
|
<entry>Explanation</entry>
|
|
</row>
|
|
</thead>
|
|
|
|
<tbody>
|
|
<row>
|
|
<entry><literal>name</literal></entry>
|
|
|
|
<entry>Indicates the property <literal>name</literal>
|
|
corresponding to the methods <methodname>getName()</methodname> or
|
|
<methodname>isName()</methodname> and
|
|
<methodname>setName(..)</methodname></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><literal>account.name</literal></entry>
|
|
|
|
<entry>Indicates the nested property <literal>name</literal>
|
|
of the property <literal>account</literal> corresponding e.g.
|
|
to the methods <literal>getAccount().setName()</literal> or
|
|
<literal>getAccount().getName()</literal></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><literal>account[2]</literal></entry>
|
|
|
|
<entry>Indicates the <emphasis>third</emphasis> element of the
|
|
indexed property <literal>account</literal>. Indexed
|
|
properties can be of type <literal>array</literal>,
|
|
<literal>list</literal> or other <emphasis>naturally
|
|
ordered</emphasis> collection</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><literal>account[COMPANYNAME]</literal></entry>
|
|
|
|
<entry>Indicates the value of the map entry indexed by the key
|
|
<emphasis>COMPANYNAME</emphasis> of the Map property
|
|
<literal>account</literal></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
|
|
<para>Below you'll find some examples of working with the <interfacename>BeanWrapper</interfacename> to
|
|
get and set properties.</para>
|
|
|
|
<para><emphasis>(This next section is not vitally important to you if you're not
|
|
planning to work with the <interfacename>BeanWrapper</interfacename> directly. If you're
|
|
just using the <interfacename>DataBinder</interfacename> and the
|
|
<interfacename>BeanFactory</interfacename> and their out-of-the-box implementation, you
|
|
should skip ahead to the section about
|
|
<interfacename>PropertyEditors</interfacename>.)</emphasis></para>
|
|
|
|
<para>Consider the following two classes:</para>
|
|
<programlisting language="java"><![CDATA[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;
|
|
}
|
|
}]]></programlisting>
|
|
|
|
<programlisting language="java"><![CDATA[public class Employee {
|
|
private String name;
|
|
private float salary;
|
|
|
|
public String getName() {
|
|
return this.name;
|
|
}
|
|
public void setName(String name) {
|
|
this.name = name;
|
|
}
|
|
public float getSalary() {
|
|
return salary;
|
|
}
|
|
public void setSalary(float salary) {
|
|
this.salary = salary;
|
|
}
|
|
}]]></programlisting>
|
|
|
|
<para>The following code snippets show some examples of how to retrieve
|
|
and manipulate some of the properties of instantiated
|
|
<literal>Companies</literal> and <literal>Employees</literal>:</para>
|
|
<programlisting language="java"><![CDATA[BeanWrapper company = BeanWrapperImpl(new Company());
|
|
]]><lineannotation>// setting the company name..</lineannotation><![CDATA[
|
|
company.setPropertyValue("name", "Some Company Inc.");
|
|
]]><lineannotation>// ... can also be done like this:</lineannotation><![CDATA[
|
|
PropertyValue value = new PropertyValue("name", "Some Company Inc.");
|
|
company.setPropertyValue(value);
|
|
|
|
]]><lineannotation>// ok, let's create the director and tie it to the company:</lineannotation><![CDATA[
|
|
BeanWrapper jim = BeanWrapperImpl(new Employee());
|
|
jim.setPropertyValue("name", "Jim Stravinsky");
|
|
company.setPropertyValue("managingDirector", jim.getWrappedInstance());
|
|
|
|
]]><lineannotation>// retrieving the salary of the managingDirector through the company</lineannotation><![CDATA[
|
|
Float salary = (Float) company.getPropertyValue("managingDirector.salary");]]></programlisting>
|
|
</section>
|
|
|
|
<section id="beans-beans-conversion">
|
|
<title>Built-in <interface>PropertyEditor</interface> implementations</title>
|
|
|
|
<para>Spring uses the concept of <literal>PropertyEditors</literal> to effect the conversion
|
|
between an <classname>Object</classname> and a <classname>String</classname>. If you think about it,
|
|
it sometimes might be handy to be able to represent properties in a different way than the object itself.
|
|
For example, a <classname>Date</classname> can be represented in a human readable way (as the
|
|
<classname>String</classname> '<literal>2007-14-09</literal>'), 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 <classname>Date</classname> objects). This behavior can be achieved by
|
|
<emphasis>registering custom editors</emphasis>, of type <interfacename>java.beans.PropertyEditor</interfacename>.
|
|
Registering custom editors on a <interfacename>BeanWrapper</interfacename> or alternately in a specific IoC
|
|
container as mentioned in the previous chapter, gives it the knowledge of how to convert properties to the
|
|
desired type. Read more about <interfacename>PropertyEditors</interfacename> in the Javadoc of the
|
|
<literal>java.beans</literal> package provided by Sun.</para>
|
|
|
|
<para>A couple of examples where property editing is used in Spring:
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para><emphasis>setting properties on beans</emphasis> is done
|
|
using <literal>PropertyEditors</literal>. When mentioning
|
|
<literal>java.lang.String</literal> 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 <classname>Class</classname>-parameter) use the
|
|
<classname>ClassEditor</classname> to try to resolve the parameter to
|
|
a <classname>Class</classname> object.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis>parsing HTTP request parameters</emphasis> in
|
|
Spring's MVC framework is done using all kinds of <literal>PropertyEditors</literal>
|
|
that you can manually bind in all subclasses of the
|
|
<classname>CommandController</classname>.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
|
|
<para>Spring has a number of built-in <literal>PropertyEditors</literal> to make life easy.
|
|
Each of those is listed below and they are all located in the
|
|
<literal>org.springframework.beans.propertyeditors</literal> package. Most, but not all (as indicated below),
|
|
are registered by default by <classname>BeanWrapperImpl</classname>. Where the property editor is configurable
|
|
in some fashion, you can of course still register your own variant to override the default one:</para>
|
|
|
|
<table id="beans-beans-property-editors-tbl">
|
|
<title>Built-in <literal>PropertyEditors</literal></title>
|
|
|
|
<tgroup cols="2">
|
|
<colspec colname="c1" colwidth="3*" />
|
|
<colspec colname="c2" colwidth="5*" />
|
|
|
|
<thead>
|
|
<row>
|
|
<entry>Class</entry>
|
|
<entry>Explanation</entry>
|
|
</row>
|
|
</thead>
|
|
|
|
<tbody>
|
|
<row>
|
|
<entry><classname>ByteArrayPropertyEditor</classname></entry>
|
|
|
|
<entry>Editor for byte arrays. Strings will simply be
|
|
converted to their corresponding byte representations.
|
|
Registered by default by <classname>BeanWrapperImpl</classname>.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><classname>ClassEditor</classname></entry>
|
|
|
|
<entry>Parses Strings representing classes to actual classes
|
|
and the other way around. When a class is not found, an
|
|
<classname>IllegalArgumentException</classname> is thrown. Registered by default by
|
|
<classname>BeanWrapperImpl</classname>.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><classname>CustomBooleanEditor</classname></entry>
|
|
|
|
<entry>Customizable property editor for <classname>Boolean</classname> properties.
|
|
Registered by default by <classname>BeanWrapperImpl</classname>, but, can be
|
|
overridden by registering custom instance of it as custom
|
|
editor.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><classname>CustomCollectionEditor</classname></entry>
|
|
<entry>Property editor for Collections, converting any source
|
|
<interfacename>Collection</interfacename> to a given target <interfacename>Collection</interfacename> type.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><classname>CustomDateEditor</classname></entry>
|
|
|
|
<entry>Customizable property editor for java.util.Date,
|
|
supporting a custom DateFormat. NOT registered by default. Must
|
|
be user registered as needed with appropriate format.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><classname>CustomNumberEditor</classname></entry>
|
|
|
|
<entry>Customizable property editor for any Number subclass
|
|
like <classname>Integer</classname>, <classname>Long</classname>,
|
|
<classname>Float</classname>, <classname>Double</classname>. Registered
|
|
by default by <classname>BeanWrapperImpl</classname>, but can be
|
|
overridden by registering custom instance of it as a custom editor.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><classname>FileEditor</classname></entry>
|
|
|
|
<entry>Capable of resolving Strings to
|
|
<classname>java.io.File</classname> objects. Registered by default by
|
|
<classname>BeanWrapperImpl</classname>. </entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><classname>InputStreamEditor</classname></entry>
|
|
|
|
<entry>One-way property editor, capable of taking a text
|
|
string and producing (via an intermediate <classname>ResourceEditor</classname> and
|
|
<interfacename>Resource</interfacename>) an
|
|
<interfacename>InputStream</interfacename>, so <interfacename>InputStream</interfacename>
|
|
properties may be directly set as Strings. Note that the default usage
|
|
will not close the <interfacename>InputStream</interfacename> for
|
|
you! Registered by default by <classname>BeanWrapperImpl</classname>.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><classname>LocaleEditor</classname></entry>
|
|
|
|
<entry>Capable of resolving Strings to
|
|
<classname>Locale</classname> 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 <classname>BeanWrapperImpl</classname>.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><classname>PatternEditor</classname></entry>
|
|
|
|
<entry>Capable of resolving Strings to JDK 1.5
|
|
<classname>Pattern</classname> objects and vice versa.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><classname>PropertiesEditor</classname></entry>
|
|
|
|
<entry>Capable of converting Strings (formatted using the
|
|
format as defined in the Javadoc for the java.lang.Properties
|
|
class) to <classname>Properties</classname> objects. Registered by
|
|
default by <classname>BeanWrapperImpl</classname>.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><classname>StringTrimmerEditor</classname></entry>
|
|
|
|
<entry>Property editor that trims Strings. Optionally allows
|
|
transforming an empty string into a <literal>null</literal> value. NOT
|
|
registered by default; must be user registered as needed.</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry><classname>URLEditor</classname></entry>
|
|
|
|
<entry>Capable of resolving a String representation of a URL
|
|
to an actual <classname>URL</classname> object. Registered by
|
|
default by <classname>BeanWrapperImpl</classname>.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
|
|
<para>
|
|
Spring uses the <interfacename>java.beans.PropertyEditorManager</interfacename> to set
|
|
the search path for property editors that might be needed. The search path also includes
|
|
<literal>sun.bean.editors</literal>, which includes
|
|
<interfacename>PropertyEditor</interfacename> implementations for types such as
|
|
<classname>Font</classname>, <classname>Color</classname>, and most of the primitive types.
|
|
Note also that the standard JavaBeans infrastructure will automatically discover
|
|
<interfacename>PropertyEditor</interfacename> classes (without you having to register them
|
|
explicitly) if they are in the same package as the class they handle, and have the same name
|
|
as that class, with <literal>'Editor'</literal> appended; for example, one could have the
|
|
following class and package structure, which would be sufficient for the
|
|
<classname>FooEditor</classname> class to be recognized and used as the
|
|
<interfacename>PropertyEditor</interfacename> for <classname>Foo</classname>-typed
|
|
properties.
|
|
</para>
|
|
<programlisting><![CDATA[com
|
|
chank
|
|
pop
|
|
Foo
|
|
FooEditor ]]><lineannotation>// the <interfacename>PropertyEditor</interfacename> for the <classname>Foo</classname> class</lineannotation></programlisting>
|
|
<para>Note that you can also use the standard <interfacename>BeanInfo</interfacename> JavaBeans
|
|
mechanism here as well (described
|
|
<ulink url="http://java.sun.com/docs/books/tutorial/javabeans/customization/index.html">in not-amazing-detail here</ulink>).
|
|
Find below an example of using the <interfacename>BeanInfo</interfacename> mechanism for
|
|
explicitly registering one or more <interfacename>PropertyEditor</interfacename> instances
|
|
with the properties of an associated class.</para>
|
|
<programlisting><![CDATA[com
|
|
chank
|
|
pop
|
|
Foo
|
|
FooBeanInfo ]]><lineannotation>// the <interfacename>BeanInfo</interfacename> for the <classname>Foo</classname> class</lineannotation></programlisting>
|
|
<para>
|
|
Here is the Java source code for the referenced <classname>FooBeanInfo</classname> class. This
|
|
would associate a <classname>CustomNumberEditor</classname> with the <literal>age</literal>
|
|
property of the <classname>Foo</classname> class.
|
|
</para>
|
|
<programlisting language="java"><![CDATA[public class FooBeanInfo extends SimpleBeanInfo {
|
|
|
|
public PropertyDescriptor[] getPropertyDescriptors() {
|
|
try {
|
|
final PropertyEditor numberPE = new CustomNumberEditor(Integer.class, true);
|
|
PropertyDescriptor ageDescriptor = new PropertyDescriptor("age", Foo.class) {
|
|
public PropertyEditor createPropertyEditor(Object bean) {
|
|
return numberPE;
|
|
};
|
|
};
|
|
return new PropertyDescriptor[] { ageDescriptor };
|
|
}
|
|
catch (IntrospectionException ex) {
|
|
throw new Error(ex.toString());
|
|
}
|
|
}
|
|
}]]></programlisting>
|
|
|
|
|
|
<section id="beans-beans-conversion-customeditor-registration">
|
|
<title>Registering additional custom <interfacename>PropertyEditors</interfacename></title>
|
|
|
|
<para>When setting bean properties as a string value, a Spring IoC container
|
|
ultimately uses standard JavaBeans <literal>PropertyEditors</literal> to convert these
|
|
Strings to the complex type of the property. Spring pre-registers a number
|
|
of custom <literal>PropertyEditors</literal> (for example, to convert a classname expressed
|
|
as a string into a real <classname>Class</classname> object). Additionally, Java's standard
|
|
JavaBeans <interfacename>PropertyEditor</interfacename> lookup mechanism allows a
|
|
<classname>PropertyEditor</classname> for a class simply to be named appropriately and
|
|
placed in the same package as the class it provides support for, to be found automatically.</para>
|
|
<para>If there is a need to register other custom <literal>PropertyEditors</literal>, there
|
|
are several mechanisms available. The most manual approach, which is not normally convenient or
|
|
recommended, is to simply use the <methodname>registerCustomEditor()</methodname> method of the
|
|
<interfacename>ConfigurableBeanFactory</interfacename> interface, assuming you have a
|
|
<interfacename>BeanFactory</interfacename> reference. Another, slightly more convenient, mechanism is to use
|
|
a special bean factory post-processor called <classname>CustomEditorConfigurer</classname>.
|
|
Although bean factory post-processors can be used with <interfacename>BeanFactory</interfacename>
|
|
implementations, the <classname>CustomEditorConfigurer</classname> has a nested property setup, so it is
|
|
strongly recommended that it is used with the <interfacename>ApplicationContext</interfacename>, where
|
|
it may be deployed in similar fashion to any other bean, and automatically detected and applied.</para>
|
|
<para>Note that all bean factories and application contexts automatically use a number of built-in property
|
|
editors, through their use of something called a <interfacename>BeanWrapper</interfacename> to handle
|
|
property conversions. The standard property editors that the <interfacename>BeanWrapper</interfacename>
|
|
registers are listed in <link linkend="beans-beans-conversion">the previous section</link>. Additionally,
|
|
<literal>ApplicationContexts</literal> also override or add an additional number of editors
|
|
to handle resource lookups in a manner appropriate to the specific application context type.</para>
|
|
|
|
<para>Standard JavaBeans <interfacename>PropertyEditor</interfacename> instances are used to convert
|
|
property values expressed as strings to the actual complex type of the property.
|
|
<classname>CustomEditorConfigurer</classname>, a bean factory post-processor, may be used to conveniently
|
|
add support for additional <interfacename>PropertyEditor</interfacename> instances to an
|
|
<interfacename>ApplicationContext</interfacename>.</para>
|
|
<para>Consider a user class <classname>ExoticType</classname>, and another class
|
|
<classname>DependsOnExoticType</classname> which needs <classname>ExoticType</classname> set as a property:</para>
|
|
|
|
<programlisting language="java"><![CDATA[package example;
|
|
|
|
public class ExoticType {
|
|
|
|
private String name;
|
|
|
|
public ExoticType(String name) {
|
|
this.name = name;
|
|
}
|
|
}
|
|
|
|
public class DependsOnExoticType {
|
|
|
|
private ExoticType type;
|
|
|
|
public void setType(ExoticType type) {
|
|
this.type = type;
|
|
}
|
|
}]]></programlisting>
|
|
<para>When things are properly set up, we want to be able to assign the type property as a string, which a
|
|
<interfacename>PropertyEditor</interfacename> will behind the scenes convert into an actual
|
|
<classname>ExoticType</classname> instance:</para>
|
|
<programlisting language="xml"><![CDATA[<bean id="sample" class="example.DependsOnExoticType">
|
|
<property name="type" value="aNameForExoticType"/>
|
|
</bean>]]></programlisting>
|
|
<para>The <interfacename>PropertyEditor</interfacename> implementation could look similar to this:</para>
|
|
<programlisting language="java"><lineannotation>// converts string representation to <classname>ExoticType</classname> object</lineannotation><![CDATA[
|
|
package example;
|
|
|
|
public class ExoticTypeEditor extends PropertyEditorSupport {
|
|
|
|
private String format;
|
|
|
|
public void setFormat(String format) {
|
|
this.format = format;
|
|
}
|
|
|
|
public void setAsText(String text) {
|
|
if (format != null && format.equals("upperCase")) {
|
|
text = text.toUpperCase();
|
|
}
|
|
ExoticType type = new ExoticType(text);
|
|
setValue(type);
|
|
}
|
|
}]]></programlisting>
|
|
<para>Finally, we use <classname>CustomEditorConfigurer</classname> to register the new
|
|
<interfacename>PropertyEditor</interfacename> with the <interfacename>ApplicationContext</interfacename>,
|
|
which will then be able to use it as needed:</para>
|
|
<programlisting language="xml"><![CDATA[<bean class="org.springframework.beans.factory.config.CustomEditorConfigurer">
|
|
<property name="customEditors">
|
|
<map>
|
|
<entry key="example.ExoticType">
|
|
<bean class="example.ExoticTypeEditor">
|
|
<property name="format" value="upperCase"/>
|
|
</bean>
|
|
</entry>
|
|
</map>
|
|
</property>
|
|
</bean>]]></programlisting>
|
|
|
|
<section id="beans-beans-conversion-customeditor-registration-per">
|
|
<title>Using <interfacename>PropertyEditorRegistrars</interfacename></title>
|
|
|
|
<para>Another mechanism for registering property editors with the Spring container is to create and use
|
|
a <interfacename>PropertyEditorRegistrar</interfacename>. This interface is particularly useful when you
|
|
need to use the same set of property editors in several different situations: write a corresponding
|
|
registrar and reuse that in each case. <literal>PropertyEditorRegistrars</literal> work in conjunction
|
|
with an interface called <interfacename>PropertyEditorRegistry</interfacename>, an interface
|
|
that is implemented by the Spring <interfacename>BeanWrapper</interfacename> (and
|
|
<interfacename>DataBinder</interfacename>). <literal>PropertyEditorRegistrars</literal> are particularly
|
|
convenient when used in conjunction with the <classname>CustomEditorConfigurer</classname>
|
|
(introduced <link linkend="beans-beans-conversion-customeditor-registration">here</link>), which exposes a
|
|
property called <methodname>setPropertyEditorRegistrars(..)</methodname>:
|
|
<literal>PropertyEditorRegistrars</literal> added to a <classname>CustomEditorConfigurer</classname> in this
|
|
fashion can easily be shared with <interfacename>DataBinder</interfacename> and Spring MVC
|
|
<interfacename>Controllers</interfacename>. Furthermore, it avoids the need for synchronization on custom
|
|
editors: a <interfacename>PropertyEditorRegistrar</interfacename> is expected to create fresh
|
|
<interfacename>PropertyEditor</interfacename> instances for each bean creation attempt.</para>
|
|
<para>Using a <interfacename>PropertyEditorRegistrar</interfacename> is perhaps best illustrated with an
|
|
example. First off, you need to create your own <interfacename>PropertyEditorRegistrar</interfacename>
|
|
implementation:</para>
|
|
|
|
<programlisting language="java"><![CDATA[package com.foo.editors.spring;
|
|
|
|
public final class CustomPropertyEditorRegistrar implements PropertyEditorRegistrar {
|
|
|
|
public void registerCustomEditors(PropertyEditorRegistry registry) {
|
|
|
|
]]><lineannotation>// it is expected that new <interfacename>PropertyEditor</interfacename> instances are created</lineannotation><![CDATA[
|
|
registry.registerCustomEditor(ExoticType.class, new ExoticTypeEditor());
|
|
|
|
]]><lineannotation>// you could register as many custom property editors as are required here...</lineannotation><![CDATA[
|
|
}
|
|
}]]></programlisting>
|
|
<para>See also the <classname>org.springframework.beans.support.ResourceEditorRegistrar</classname> for an
|
|
example <interfacename>PropertyEditorRegistrar</interfacename> implementation. Notice how in its
|
|
implementation of the <methodname>registerCustomEditors(..)</methodname> method it creates new instances
|
|
of each property editor.</para>
|
|
<para>Next we configure a <classname>CustomEditorConfigurer</classname> and inject an
|
|
instance of our <classname>CustomPropertyEditorRegistrar</classname> into it:</para>
|
|
<programlisting language="xml"><![CDATA[<bean class="org.springframework.beans.factory.config.CustomEditorConfigurer">
|
|
<property name="propertyEditorRegistrars">
|
|
<list>
|
|
<ref bean="customPropertyEditorRegistrar"/>
|
|
</list>
|
|
</property>
|
|
</bean>
|
|
|
|
<bean id="customPropertyEditorRegistrar" class="com.foo.editors.spring.CustomPropertyEditorRegistrar"/>]]></programlisting>
|
|
|
|
<para>Finally, and in a bit of a departure from the focus of this chapter, for those of you using
|
|
<link linkend="mvc">Spring's MVC web framework</link>, using <interfacename>PropertyEditorRegistrars</interfacename>
|
|
in conjunction with data-binding <interfacename>Controllers</interfacename> (such as
|
|
<classname>SimpleFormController</classname>) can be very convenient. Find below an example of using a
|
|
<interfacename>PropertyEditorRegistrar</interfacename> in the implementation of an <methodname>initBinder(..)</methodname>
|
|
method:</para>
|
|
|
|
<programlisting language="java"><![CDATA[public final class RegisterUserController extends SimpleFormController {
|
|
|
|
private final PropertyEditorRegistrar customPropertyEditorRegistrar;
|
|
|
|
public RegisterUserController(PropertyEditorRegistrar propertyEditorRegistrar) {
|
|
this.customPropertyEditorRegistrar = propertyEditorRegistrar;
|
|
}
|
|
|
|
protected void initBinder(HttpServletRequest request, ServletRequestDataBinder binder) throws Exception {
|
|
]]><emphasis role="bold">this.customPropertyEditorRegistrar.registerCustomEditors(binder);</emphasis><![CDATA[
|
|
}
|
|
|
|
]]><lineannotation>// other methods to do with registering a <classname>User</classname></lineannotation><![CDATA[
|
|
}]]></programlisting>
|
|
|
|
<para>This style of <interfacename>PropertyEditor</interfacename> registration can lead to concise code (the
|
|
implementation of <methodname>initBinder(..)</methodname> is just one line long!), and allows common
|
|
<interfacename>PropertyEditor</interfacename> registration code to be encapsulated in a class and then
|
|
shared amongst as many <interfacename>Controllers</interfacename> as needed.</para>
|
|
|
|
</section>
|
|
|
|
</section>
|
|
|
|
</section>
|
|
</section>
|
|
|
|
<section id="core.convert">
|
|
<title>Spring 3 Type Conversion</title>
|
|
<para>
|
|
Spring 3 introduces a <filename>core.convert</filename> package that provides a general type conversion system.
|
|
The system defines an API to implement type conversion logic, as well as an API to execute type conversions at runtime.
|
|
Within a Spring container, if configured, this system can be used as an alternative to PropertyEditors to convert externalized bean property value strings to required property types.
|
|
The public API may also be used anywhere in your application where type conversion is needed.
|
|
</para>
|
|
<section id="core-convert-Converter-API">
|
|
<title>Converter API</title>
|
|
<para>
|
|
The API to implement type conversion logic is simple and strongly typed:
|
|
</para>
|
|
<programlisting language="java"><![CDATA[
|
|
package org.springframework.core.converter;
|
|
|
|
public interface Converter<S, T> {
|
|
|
|
T convert(S source);
|
|
|
|
}]]></programlisting>
|
|
<para>
|
|
To create your own Converter, simply implement the interface above.
|
|
Parameterize S as the type you are converting from, and T as the type you are converting to.
|
|
For each call to convert(S), the source argument is guaranteed to be NOT null.
|
|
Your Converter may throw any Exception if conversion fails.
|
|
An IllegalArgumentException should be thrown to report an invalid source value.
|
|
Take care to ensure your Converter implementation is thread-safe.
|
|
</para>
|
|
<para>
|
|
Several converter implementations are provided in the <filename>core.convert.converters</filename> package as a convenience.
|
|
These include converters from Strings to Numbers and other common types.
|
|
Consider <classname>StringToInteger</classname> as an example Converter implementation:
|
|
</para>
|
|
<programlisting language="java">package org.springframework.core.convert.converters;
|
|
|
|
public class StringToInteger implements Converter<String, Integer> {
|
|
|
|
public Integer convert(String source) {
|
|
return Integer.valueOf(source);
|
|
}
|
|
|
|
}</programlisting>
|
|
</section>
|
|
<section id="core-convert-ConverterFactory-SPI">
|
|
<title>ConverterFactory</title>
|
|
<para>
|
|
When you need to centralize the conversion logic for an entire class hierarchy, for example, when converting from String to java.lang.Enum objects, implement a <interfacename>ConverterFactory</interfacename>:
|
|
</para>
|
|
<programlisting language="java"><![CDATA[
|
|
package org.springframework.core.converter;
|
|
|
|
public interface ConverterFactory<S, R> {
|
|
|
|
<T extends R> Converter<S, T> getConverter(Class<T> targetType);
|
|
|
|
}]]></programlisting>
|
|
<para>
|
|
Parameterize S to be type you are converting from and R to be base type defining the <emphasis>range</emphasis> of classes you can convert to.
|
|
Then implement getConverter(Class<T>), where T is a subclass of R.
|
|
</para>
|
|
<para>
|
|
Consider the <classname>StringToEnum</classname> ConverterFactory as an example:
|
|
</para>
|
|
<programlisting language="java"><![CDATA[
|
|
public class StringToEnumFactory implements ConverterFactory<String, Enum> {
|
|
|
|
public <T extends Enum> Converter<String, T> getConverter(Class<T> targetType) {
|
|
return new StringToEnum(targetType);
|
|
}
|
|
|
|
private final class StringToEnum<T extends Enum> implements Converter<String, T> {
|
|
|
|
private Class<T> enumType;
|
|
|
|
public StringToEnum(Class<T> enumType) {
|
|
this.enumType = enumType;
|
|
}
|
|
|
|
public T convert(String source) {
|
|
return (T) Enum.valueOf(this.enumType, source.trim());
|
|
}
|
|
}
|
|
}]]></programlisting>
|
|
</section>
|
|
<section id="core-convert-ConversionService-API">
|
|
<title>ConversionService API</title>
|
|
<para>
|
|
The ConversionService defines a public API for executing type conversion logic at runtime.
|
|
Converters are often executed behind this facade interface:
|
|
</para>
|
|
<programlisting language="java"><![CDATA[
|
|
public interface ConversionService {
|
|
|
|
boolean canConvert(Class<?> sourceType, Class<?> targetType);
|
|
|
|
<T> T convert(Object source, Class<T> targetType);
|
|
|
|
}]]></programlisting>
|
|
<para>
|
|
Most ConversionService implementations also implement <interface>ConverterRegistry</interface>, which provides an SPI for registering converters.
|
|
Internally, a ConversionService implementation delegates to its registered Converters and ConverterFactories to carry out type conversion logic.
|
|
</para>
|
|
<para>
|
|
Two ConversionService implementations are provided with the system in the <filename>core.convert.support</filename> package.
|
|
<classname>GenericConversionService</classname> is a generic implementation designed to be explicitly configured, either programatically or declaratively as a Spring bean.
|
|
<classname>DefaultConversionService</classname> is a subclass that pre-registers the common Converters in the <filename>core.converter</filename> package as a convenience.
|
|
</para>
|
|
</section>
|
|
<section id="core-convert-Spring-config">
|
|
<title>Configuring a ConversionService</title>
|
|
<para>
|
|
A ConversionService is a stateless object designed to be instantiated at application startup, then shared between multiple threads.
|
|
In a Spring application, you typically configure a ConversionService instance per Spring container (or ApplicationContext).
|
|
That ConversionService will be picked up by Spring and then used whenever a type conversion needs to be performed by the framework.
|
|
You may also inject this ConversionService into any of your beans and invoke it directly.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
If no ConversionService is registered with Spring, the original PropertyEditor-based system is used.
|
|
</para>
|
|
</note>
|
|
<para>
|
|
To register the DefaultConversionService with Spring, simply configure it as a bean with the id <code>conversionService</code>:
|
|
</para>
|
|
<programlisting language="xml"><![CDATA[
|
|
<bean id="conversionService" class="org.springframework.core.convert.support.DefaultConversionService" />]]>
|
|
</programlisting>
|
|
<para>
|
|
To override the default set of converters with your own custom converter(s), set the <code>converters</code> property:
|
|
</para>
|
|
<programlisting language="xml"><![CDATA[
|
|
<bean id="conversionService" class="org.springframework.core.convert.support.DefaultConversionService">
|
|
<property name="converters">
|
|
<list>
|
|
<bean class="example.MyCustomConverter" />
|
|
</list>
|
|
</property>
|
|
</bean>]]></programlisting>
|
|
</section>
|
|
<section id="core-convert-programmatic-usage">
|
|
<title>Using a ConversionService programatically</title>
|
|
<para>
|
|
To work with a ConversionService instance programatically, simply inject a reference to it like you would for any other bean:
|
|
</para>
|
|
<programlisting language="java"><![CDATA[
|
|
@Service
|
|
public class MyService {
|
|
|
|
@Autowired
|
|
public MyService(ConversionService conversionService) {
|
|
this.conversionService = conversionService;
|
|
}
|
|
|
|
public void doIt() {
|
|
this.conversionService.convert(...)
|
|
}
|
|
}]]></programlisting>
|
|
</section>
|
|
</section>
|
|
|
|
<section id="ui.format">
|
|
<title>Spring 3 Field Formatting</title>
|
|
<para>
|
|
As discussed in the previous section, <link linkend="core.convert"><filename>core.convert</filename></link> is a general-purpose type conversion system.
|
|
It provides a unified ConversionService API as well as a strongly-typed Converter SPI for implementing conversion logic from one type to another.
|
|
A Spring Container uses this system to bind bean property values.
|
|
In addition, both the Spring Expression Language (SpEL) and DataBinder use this system to bind field values.
|
|
For example, when SpEL needs to coerce a <classname>Short</classname> to a <classname>Long</classname> to complete an <function>expression.setValue(Object bean, Object value)</function> attempt, the core.convert system performs the coercion.
|
|
</para>
|
|
<para>
|
|
Now consider the type conversion requirements of a typical client environment such as a web or desktop application.
|
|
In such environments, you typically convert <emphasis>from String</emphasis> to support the client postback process, as well as back <emphasis>to String</emphasis> to support the view rendering process.
|
|
In addition, you often need to localize String values.
|
|
The more general <emphasis>core.convert</emphasis> Converter SPI does not address such <emphasis>formatting</emphasis> requirements directly.
|
|
To directly address them, Spring 3 introduces a convenient Formatter SPI that provides a simple and robust alternative to PropertyEditors for client environments.
|
|
</para>
|
|
<para>
|
|
In general, use the Converter SPI when you need to implement general-purpose type conversion logic; for example, for converting between a java.util.Date and and java.lang.Long.
|
|
Use the Formatter SPI when you're working in a client environment, such as a web application, and need to parse and print localized field values.
|
|
The ConversionService provides a unified type conversion API for both SPIs.
|
|
</para>
|
|
<section id="format-Formatter-SPI">
|
|
<title>Formatter SPI</title>
|
|
<para>
|
|
The Formatter SPI to implement field formatting logic is simple and strongly typed:
|
|
</para>
|
|
<programlisting language="java"><![CDATA[
|
|
package org.springframework.format;
|
|
|
|
public interface Formatter<T> extends Printer<T>, Parser<T> {
|
|
}]]>
|
|
</programlisting>
|
|
<para>
|
|
Where Formatter extends from the Printer and Parser building-block interfaces:
|
|
</para>
|
|
<programlisting language="java"><![CDATA[
|
|
public interface Printer<T> {
|
|
String print(T fieldValue, Locale locale);
|
|
}]]>
|
|
</programlisting>
|
|
<programlisting language="java"><![CDATA[
|
|
import java.text.ParseException;
|
|
|
|
public interface Parser<T> {
|
|
T parse(String clientValue, Locale locale) throws ParseException;
|
|
}]]>
|
|
</programlisting>
|
|
<para>
|
|
To create your own Formatter, simply implement the Formatter interface above.
|
|
Parameterize T to be the type of object you wish to format, for example, <classname>java.util.Date</classname>.
|
|
Implement the <methodname>print</methodname> operation to print an instance of T for display in the client locale.
|
|
Implement the <methodname>parse</methodname> operation to parse an instance of T from the formatted representation returned from the client locale.
|
|
Your Formatter should throw a ParseException or IllegalArgumentException if a parse attempt fails.
|
|
Take care to ensure your Formatter implementation is thread-safe.
|
|
</para>
|
|
<para>
|
|
Several Formatter implementations are provided in <filename>format</filename> subpackages as a convenience.
|
|
The <filename>number</filename> package provides a NumberFormatter, CurrencyFormatter, and PercentFormatter to format java.lang.Number objects using a java.text.NumberFormat.
|
|
The <filename>datetime</filename> package provides a DateFormatter to format java.util.Date objects with a java.text.DateFormat.
|
|
The <filename>datetime.joda</filename> package provides comprehensive datetime formatting support based on the <ulink url="http://joda-time.sourceforge.net">Joda Time library</ulink>.
|
|
</para>
|
|
<para>
|
|
Consider <classname>DateFormatter</classname> as an example <interfacename>Formatter</interfacename> implementation:
|
|
</para>
|
|
<programlisting language="java"><![CDATA[
|
|
package org.springframework.format.datetime;
|
|
|
|
public final class DateFormatter implements Formatter<Date> {
|
|
|
|
private String pattern;
|
|
|
|
public DateFormatter(String pattern) {
|
|
this.pattern = pattern;
|
|
}
|
|
|
|
public String print(Date date, Locale locale) {
|
|
if (date == null) {
|
|
return "";
|
|
}
|
|
return getDateFormat(locale).format(date);
|
|
}
|
|
|
|
public Date parse(String formatted, Locale locale) throws ParseException {
|
|
if (formatted.length() == 0) {
|
|
return null;
|
|
}
|
|
return getDateFormat(locale).parse(formatted);
|
|
}
|
|
|
|
protected DateFormat getDateFormat(Locale locale) {
|
|
DateFormat dateFormat = new SimpleDateFormat(this.pattern, locale);
|
|
dateFormat.setLenient(false);
|
|
return dateFormat;
|
|
}
|
|
|
|
}]]></programlisting>
|
|
<para>
|
|
The Spring team welcomes community-driven Formatter contributions; see <ulink url="http://jira.springframework.org">http://jira.springframework.org</ulink> to contribute.
|
|
</para>
|
|
</section>
|
|
<section id="format-CustomFormatAnnotations">
|
|
<title>Annotation-driven Formatting</title>
|
|
<para>
|
|
As you will see, field formatting can be configured by field type or annotation.
|
|
To bind an Annotation to a formatter, implement AnnotationFormatterFactory:
|
|
</para>
|
|
<programlisting language="java"><![CDATA[
|
|
package org.springframework.format;
|
|
|
|
public interface AnnotationFormatterFactory<A extends Annotation> {
|
|
|
|
Set<Class<?>> getFieldTypes();
|
|
|
|
Printer<?> getPrinter(A annotation, Class<?> fieldType);
|
|
|
|
Parser<?> getParser(A annotation, Class<?> fieldType);
|
|
|
|
}]]>
|
|
</programlisting>
|
|
<para>
|
|
Parameterize A to be the field annotationType you wish to associate formatting logic with, for example <code>org.springframework.format.annotation.DateTimeFormat</code>.
|
|
Have <methodname>getFieldTypes</methodname> return the types of fields the annotation may be used on.
|
|
Have <methodname>getPrinter</methodname> return a Printer to print the value of an annotated field.
|
|
Have <methodname>getParser</methodname> return a Parser to parse a clientValue for an annotated field.
|
|
</para>
|
|
<para>
|
|
The example AnnotationFormatterFactory implementation below binds the @NumberFormat Annotation to a formatter.
|
|
This annotation allows either a number style or pattern to be specified:
|
|
</para>
|
|
<programlisting language="java"><![CDATA[
|
|
public final class NumberFormatAnnotationFormatterFactory implements AnnotationFormatterFactory<NumberFormat> {
|
|
|
|
public Set<Class<?>> getFieldTypes() {
|
|
return new HashSet<Class<?>>(asList(new Class<?>[] {
|
|
Short.class, Integer.class, Long.class, Float.class, Double.class, BigDecimal.class, BigInteger.class }));
|
|
}
|
|
|
|
public Printer<Number> getPrinter(NumberFormat annotation, Class<?> fieldType) {
|
|
return configureFormatterFrom(annotation, fieldType);
|
|
}
|
|
|
|
public Parser<Number> getParser(NumberFormat annotation, Class<?> fieldType) {
|
|
return configureFormatterFrom(annotation, fieldType);
|
|
}
|
|
|
|
private Formatter<Number> configureFormatterFrom(NumberFormat annotation, Class<?> fieldType) {
|
|
if (!annotation.pattern().isEmpty()) {
|
|
return new NumberFormatter(annotation.pattern());
|
|
} else {
|
|
Style style = annotation.style();
|
|
if (style == Style.PERCENT) {
|
|
return new PercentFormatter();
|
|
} else if (style == Style.CURRENCY) {
|
|
return new CurrencyFormatter();
|
|
} else {
|
|
return new NumberFormatter();
|
|
}
|
|
}
|
|
}
|
|
}]]>
|
|
</programlisting>
|
|
<para>
|
|
To trigger formatting, simply annotate fields with @NumberFormat:
|
|
</para>
|
|
<programlisting language="java"><![CDATA[
|
|
public class MyModel {
|
|
|
|
@NumberFormat(style=Style.CURRENCY)
|
|
private BigDecimal decimal;
|
|
|
|
}]]>
|
|
</programlisting>
|
|
<section id="format.annotations.api">
|
|
<title>Format Annotation API</title>
|
|
<para>
|
|
A portable format annotation API exists in the <filename>org.springframework.format.annotation</filename> package.
|
|
Use @NumberFormat to format java.lang.Number fields.
|
|
Use @DateTimeFormat to format java.util.Date, java.util.Calendar, java.util.Long, or Joda Time fields.
|
|
</para>
|
|
<para>
|
|
The example below uses @DateTimeFormat to format a java.util.Date as a ISO Date (yyyy-MM-dd):
|
|
</para>
|
|
<programlisting language="java"><![CDATA[
|
|
public class MyModel {
|
|
|
|
@DateTimeFormat(iso=ISO.DATE)
|
|
private Date date;
|
|
|
|
}]]>
|
|
</programlisting>
|
|
</section>
|
|
</section>
|
|
<section id="format-FormatterRegistry-SPI">
|
|
<title>FormatterRegistry SPI</title>
|
|
<para>
|
|
At runtime, Formatters are registered in a FormatterRegistry.
|
|
The FormatterRegistry SPI allows you to configure Formatting rules centrally, instead of duplicating such configuration across your Controllers.
|
|
For example, you might want to enforce that all Date fields are formatted a certain way, or fields with a specific annotation are formatted in a certain way.
|
|
With a shared FormatterRegistry, you define these rules once and they are applied whenever formatting is needed.
|
|
</para>
|
|
<para>
|
|
Review the FormatterRegistry SPI below:
|
|
</para>
|
|
<programlisting language="java"><![CDATA[
|
|
package org.springframework.format;
|
|
|
|
public interface FormatterRegistry {
|
|
|
|
void addFormatterForFieldType(Class<?> fieldType, Printer<?> printer, Parser<?> parser);
|
|
|
|
void addFormatterForFieldType(Class<?> fieldType, Formatter<?> formatter);
|
|
|
|
void addFormatterForAnnotation(AnnotationFormatterFactory<?, ?> factory);
|
|
|
|
}]]></programlisting>
|
|
<para>
|
|
As shown above, Formatters can be registered by fieldType or annotation.
|
|
<classname>FormattingConversionService</classname> is the implementation of <classname>FormatterRegistry</classname> suitable for most environments.
|
|
This implementation may be configured programatically, or declaratively as a Spring bean using <classname>FormattingConversionServiceFactoryBean</classname>.
|
|
Because this implemementation also implements <classname>ConversionService</classname>, it can be directly configured for use with Spring's DataBinder and the Spring Expression Language (SpEL).
|
|
</para>
|
|
</section>
|
|
<section id="format-configuring-FormatterRegistry">
|
|
<title>Configuring Formatting in Spring MVC</title>
|
|
<para>
|
|
In a Spring MVC application, you may configure a custom ConversionService instance explicity as an attribute of the <literal>annotation-driven</literal> element of the MVC namespace.
|
|
This ConversionService will then be used anytime a type conversion is required during Controller model binding.
|
|
If not configured explicitly, Spring MVC will automatically register default formatters and converters for common types such as numbers and dates.
|
|
</para>
|
|
<para>
|
|
To rely on default formatting rules, no custom configuration is required in your Spring MVC config XML:
|
|
</para>
|
|
<programlisting language="xml"><![CDATA[
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
<beans xmlns="http://www.springframework.org/schema/beans"
|
|
xmlns:mvc="http://www.springframework.org/schema/mvc"
|
|
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
|
xsi:schemaLocation="
|
|
http://www.springframework.org/schema/beans
|
|
http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
|
|
http://www.springframework.org/schema/mvc
|
|
http://www.springframework.org/schema/mvc/spring-mvc-3.0.xsd">
|
|
|
|
<mvc:annotation-driven/>
|
|
|
|
</beans>
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
With this one-line of configuation, default formatters for Numbers and Date types will be installed, including support for the @NumberFormat and @DateTimeFormat annotations.
|
|
Full support for the Joda Time formatting library is also installed if Joda Time is present on the classpath.
|
|
</para>
|
|
<para>
|
|
To inject a ConversionService instance with custom formatters and converters registered, set the conversion-service attribute:
|
|
</para>
|
|
<programlisting language="xml"><![CDATA[
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
<beans xmlns="http://www.springframework.org/schema/beans"
|
|
xmlns:mvc="http://www.springframework.org/schema/mvc"
|
|
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
|
xsi:schemaLocation="
|
|
http://www.springframework.org/schema/beans
|
|
http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
|
|
http://www.springframework.org/schema/mvc
|
|
http://www.springframework.org/schema/mvc/spring-mvc-3.0.xsd">
|
|
|
|
<mvc:annotation-driven conversion-service="conversionService" />
|
|
|
|
<bean id="conversionService" class="org.springframework.format.support.FormattingConversionServiceFactoryBean" />
|
|
|
|
</beans>
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
A custom ConversionService instance is often constructed by a FactoryBean that internally registers custom Formatters and Converters programatically before the ConversionService is returned.
|
|
See FormatingConversionServiceFactoryBean for an example.
|
|
</para>
|
|
</section>
|
|
</section>
|
|
<section id="validation.beanvalidation">
|
|
<title>Spring 3 Validation</title>
|
|
<para>
|
|
Spring 3 introduces several enhancements to its validation support.
|
|
First, the JSR-303 Bean Validation API is now fully supported.
|
|
Second, when used programatically, Spring's DataBinder can now validate objects as well as bind to them.
|
|
Third, Spring MVC now has support for declaratively validating @Controller inputs.
|
|
</para>
|
|
<section id="validation.beanvalidation.overview">
|
|
<title>Overview of the JSR-303 Bean Validation API</title>
|
|
<para>
|
|
JSR-303 standardizes validation constraint declaration and metadata for the Java platform.
|
|
Using this API, you annotate domain model properties with declarative validation constraints and the runtime enforces them.
|
|
There are a number of built-in constraints you can can take advantage of.
|
|
You may also define your own custom constraints.
|
|
</para>
|
|
<para>
|
|
To illustrate, consider a simple PersonForm model with two properties:
|
|
</para>
|
|
<programlisting language="java"><![CDATA[
|
|
public class PersonForm {
|
|
private String name;
|
|
private int age;
|
|
}]]></programlisting>
|
|
<para>
|
|
JSR-303 allows you to define declarative validation constraints against such properties:
|
|
</para>
|
|
<programlisting language="java"><![CDATA[
|
|
public class PersonForm {
|
|
|
|
@NotNull
|
|
@Max(64)
|
|
private String name;
|
|
|
|
@Min(0)
|
|
private int age;
|
|
|
|
}]]></programlisting>
|
|
<para>
|
|
When an instance of this class is validated by a JSR-303 Validator, these constraints will be enforced.
|
|
</para>
|
|
<para>
|
|
For general information on JSR-303, see the <ulink url="http://jcp.org/en/jsr/detail?id=303">Bean Validation Specification</ulink>.
|
|
For information on the specific capabilities of the default reference implementation, see the <ulink url="https://www.hibernate.org/412.html">Hibernate Validator</ulink> documentation.
|
|
To learn how to setup a JSR-303 implementation as a Spring bean, keep reading.
|
|
</para>
|
|
</section>
|
|
<section id="validation.beanvalidation.spring">
|
|
<title>Configuring a Bean Validation Implementation</title>
|
|
<para>
|
|
Spring provides full support for the JSR-303 Bean Validation API.
|
|
This includes convenient support for bootstrapping a JSR-303 implementation as a Spring bean.
|
|
This allows a <code>javax.validation.Validator</code> to be injected wherever validation is needed in your application.
|
|
</para>
|
|
<para>
|
|
Use the <classname>LocalValidatorFactoryBean</classname> to configure a default JSR-303 Validator as a Spring bean:
|
|
</para>
|
|
<programlisting language="xml"><![CDATA[
|
|
<bean id="validator" class="org.springframework.validation.beanvalidation.LocalValidatorFactoryBean" />]]>
|
|
</programlisting>
|
|
<para>
|
|
The basic configuration above will trigger JSR-303 to initialize using its default bootstrap mechanism.
|
|
A JSR-303 provider, such as Hibernate Validator, is expected to be present in the classpath and will be detected automatically.
|
|
</para>
|
|
<section id="validation.beanvalidation.spring.inject">
|
|
<title>Injecting a Validator</title>
|
|
<para>
|
|
<classname>LocalValidatorFactoryBean</classname> implements both <code>javax.validation.Validator</code> and <code>org.springframework.validation.Validator</code>.
|
|
You may inject a reference to one of these two interfaces into beans that need to invoke validation logic.
|
|
</para>
|
|
<para>
|
|
Inject a reference to <code>javax.validation.Validator</code> if you prefer to work with the JSR-303 API directly:
|
|
</para>
|
|
<programlisting language="java">
|
|
import javax.validation.Validator;
|
|
|
|
@Service
|
|
public class MyService {
|
|
|
|
@Autowired
|
|
private Validator validator;
|
|
</programlisting>
|
|
<para>
|
|
Inject a reference to <code>org.springframework.validation.Validator</code> if your bean requires the Spring Validation API:
|
|
</para>
|
|
<programlisting language="java"><![CDATA[
|
|
import org.springframework.validation.Validator;
|
|
|
|
@Service
|
|
public class MyService {
|
|
|
|
@Autowired
|
|
private Validator validator;
|
|
|
|
}]]></programlisting>
|
|
</section>
|
|
<section id="validation.beanvalidation.spring.constraints">
|
|
<title>Configuring Custom Constraints</title>
|
|
<para>
|
|
Each JSR-303 validation constraint consists of two parts.
|
|
First, a @Constraint annotation that declares the constraint and its configurable properties.
|
|
Second, an implementation of the <code>javax.validation.ConstraintValidator</code> interface that implements the constraint's behavior.
|
|
To associate a declaration with an implementation, each @Constraint annotation references a corresponding ValidationConstraint implementation class.
|
|
At runtime, a <code>ConstraintValidatorFactory</code> instantiates the referenced implementation when the constraint annotation is encountered in your domain model.
|
|
</para>
|
|
<para>
|
|
By default, the <classname>LocalValidatorFactoryBean</classname> configures a <code>SpringConstraintValidatorFactory</code> that uses Spring to create ConstraintValidator instances.
|
|
This allows your custom ConstraintValidators to benefit from dependency injection like any other Spring bean.
|
|
</para>
|
|
<para>
|
|
Shown below is an example of a custom @Constraint declaration, followed by an associated <code>ConstraintValidator</code> implementation that uses Spring for dependency injection:
|
|
</para>
|
|
<programlisting language="java"><![CDATA[
|
|
@Target({ElementType.METHOD, ElementType.FIELD})
|
|
@Retention(RetentionPolicy.RUNTIME)
|
|
@Constraint(validatedBy=MyConstraintValidator.class)
|
|
public @interface MyConstraint {
|
|
}]]></programlisting>
|
|
<programlisting language="java"><![CDATA[
|
|
import javax.validation.ConstraintValidator;
|
|
|
|
public class MyConstraintValidator implements ConstraintValidator {
|
|
|
|
@Autowired;
|
|
private Foo aDependency;
|
|
|
|
...
|
|
}]]></programlisting>
|
|
<para>
|
|
As you can see, a ConstraintValidator implementation may have its dependencies @Autowired like any other Spring bean.
|
|
</para>
|
|
</section>
|
|
<section id="validation.beanvalidation.spring.other">
|
|
<title>Additional Configuration Options</title>
|
|
<para>
|
|
The default <classname>LocalValidatorFactoryBean</classname> configuration should prove sufficient for most cases.
|
|
There are a number of other configuration options for various JSR-303 constructs, from message interpolation to traversal resolution.
|
|
See the JavaDocs of <classname>LocalValidatorFactoryBean</classname> more information on these options.
|
|
</para>
|
|
</section>
|
|
</section>
|
|
<section id="validation.binder">
|
|
<title>Configuring a DataBinder</title>
|
|
<para>
|
|
Since Spring 3, a DataBinder instance can be configured with a Validator.
|
|
Once configured, the Validator may be invoked by calling <code>binder.validate()</code>.
|
|
Any validation Errors are automatically added to the binder's BindingResult.
|
|
</para>
|
|
<para>
|
|
When working with the DataBinder programatically, this can be used to invoke validation logic after binding to a target object:
|
|
</para>
|
|
<programlisting language="java">Foo target = new Foo();
|
|
DataBinder binder = new DataBinder(target);
|
|
binder.setValidator(new FooValidator());
|
|
|
|
<lineannotation>// bind to the target object</lineannotation>
|
|
binder.bind(propertyValues);
|
|
|
|
<lineannotation>// validate the target object</lineannotation>
|
|
binder.validate();
|
|
|
|
<lineannotation>// get BindingResult that includes any validation errors</lineannotation>
|
|
BindingResult results = binder.getBindingResult();
|
|
</programlisting>
|
|
</section>
|
|
<section id="validation.mvc">
|
|
<title>Spring MVC 3 Validation</title>
|
|
<para>
|
|
Beginning with Spring 3, Spring MVC has the ability to automatically validate @Controller inputs.
|
|
In previous versions it was up to the developer to manually invoke validation logic.
|
|
</para>
|
|
<section id="validation.mvc.triggering">
|
|
<title>Triggering @Controller Input Validation</title>
|
|
<para>
|
|
To trigger validation of a @Controller input, simply annotate the input argument as @Valid:
|
|
</para>
|
|
<programlisting language="java">@Controller
|
|
public class MyController {
|
|
|
|
@RequestMapping("/foo", method=RequestMethod.POST)
|
|
public void processFoo(<emphasis role="bold">@Valid</emphasis> Foo foo) { <lineannotation>/* ... */</lineannotation> }
|
|
</programlisting>
|
|
<para>
|
|
Spring MVC will validate a @Valid object after binding so-long as an appropriate Validator has been configured.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
The @Valid annotation is part of the standard JSR-303 Bean Validation API, and is not a Spring-specific construct.
|
|
</para>
|
|
</note>
|
|
</section>
|
|
<section id="validation.mvc.configuring">
|
|
<title>Configuring a Validator for use by Spring MVC</title>
|
|
<para>
|
|
The Validator instance invoked when a @Valid method argument is encountered may be configured in two ways.
|
|
First, you may call binder.setValidator(Validator) within a @Controller's @InitBinder callback.
|
|
This allows you to configure a Validator instance per @Controller class:
|
|
</para>
|
|
<programlisting language="java"><![CDATA[
|
|
@Controller
|
|
public class MyController {
|
|
|
|
@InitBinder
|
|
protected void initBinder(WebDataBinder binder) {
|
|
binder.setValidator(new FooValidator());
|
|
}
|
|
|
|
@RequestMapping("/foo", method=RequestMethod.POST)
|
|
public void processFoo(@Valid Foo foo) { ... }
|
|
|
|
}]]></programlisting>
|
|
<para>
|
|
Second, you may call setValidator(Validator) on the global WebBindingInitializer.
|
|
This allows you to configure a Validator instance across all @Controllers.
|
|
This can be achieved easily by using the Spring MVC namespace:
|
|
</para>
|
|
<programlisting language="xml"><![CDATA[
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
<beans xmlns="http://www.springframework.org/schema/beans"
|
|
xmlns:mvc="http://www.springframework.org/schema/mvc"
|
|
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
|
xsi:schemaLocation="
|
|
http://www.springframework.org/schema/beans
|
|
http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
|
|
http://www.springframework.org/schema/mvc
|
|
http://www.springframework.org/schema/mvc/spring-mvc-3.0.xsd">
|
|
|
|
<mvc:annotation-driven validator="globalValidator"/>
|
|
|
|
</beans>
|
|
]]>
|
|
</programlisting>
|
|
</section>
|
|
<section id="validation.mvc.jsr303">
|
|
<title>Configuring a JSR-303 Validator for use by Spring MVC</title>
|
|
<para>
|
|
With JSR-303, the default <code>javax.validation.Validator</code> implementation is typically global.
|
|
A single instance typically validates <emphasis>all</emphasis> application objects that declare validation constraints.
|
|
To configure such a general purpose Validator for use by Spring MVC, simply add a JSR-303 Provider to your classpath.
|
|
Spring MVC will detect it and automatically configure JSR-303 for use across all Controllers.
|
|
</para>
|
|
<para>
|
|
The Spring MVC configuration required to configure JSR-303 support is shown below:
|
|
</para>
|
|
<programlisting language="xml"><![CDATA[
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
<beans xmlns="http://www.springframework.org/schema/beans"
|
|
xmlns:mvc="http://www.springframework.org/schema/mvc"
|
|
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
|
xsi:schemaLocation="
|
|
http://www.springframework.org/schema/beans
|
|
http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
|
|
http://www.springframework.org/schema/mvc
|
|
http://www.springframework.org/schema/mvc/spring-mvc-3.0.xsd">
|
|
|
|
<!-- JSR-303 support detected on classpath and configured automatically -->
|
|
<mvc:annotation-driven/>
|
|
|
|
</beans>
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
With this minimal configuration, anytime a @Valid @Controller input is encountered, it will be validated by the JSR-303 provider.
|
|
JSR-303, in turn, will enforce any constraints declared against the input.
|
|
Any ConstaintViolations will automatically be exposed as errors in the BindingResult renderable by standard Spring MVC form tags.
|
|
</para>
|
|
</section>
|
|
</section>
|
|
</section>
|
|
</chapter> |