Since Spring 3, the Formatter API has provided a facility to bind an annotation to a org.springframework.format.Formatter implementation.
When creating a custom Formatter, we can define a corresponding annotation and bind it to that formatter.
In this example we are going to define our own formatter annotation.
To bind an annotation to a formatter, we must implement the AnnotationFormatterFactory interface:
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);
}
Example
In our last examplewe created a custom formatter AddressFormatter by extending Formatter interface. Here, we are going to bind the same formatter to our custom @AddressFormat annotation. Doing so will enable us to declare formatting directly on the field level.
Creating Backing Object Classes
public class Customer {
private Long id;
private String name;
private Address address;
//getters and setters
}
public class Address {
private String street;
private String city;
private String county;
private String zipCode;
//getters and setters
}
Creating our Formatter
import org.springframework.format.Formatter;
import java.text.ParseException;
import java.util.Locale;
public class AddressFormatter implements Formatter<Address> {
private Style style = Style.FULL;
public void setStyle (Style style) {
this.style = style;
}
@Override
public Address parse (String text, Locale locale) throws ParseException {
.....
return address;
}
@Override
public String print (Address a, Locale l) {
...
return addressString;
}
public enum Style {
FULL,
REGION
}
}
Creating Annotation
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
@Target({ElementType.METHOD, ElementType.FIELD, ElementType.PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
public @interface AddressFormat {
AddressFormatter.Style style () default AddressFormatter.Style.REGION;
}
Using annotation in our backing object class
package com.logicbig.example;
public class Customer {
private Long id;
private String name;
@AddressFormat(style = AddressFormatter.Style.FULL)
private Address address;
//getters and setters
}
Binding our Annotation by implementing AnnotationFormatterFactory
import org.springframework.format.AnnotationFormatterFactory;
import org.springframework.format.Parser;
import org.springframework.format.Printer;
import java.util.Arrays;
import java.util.HashSet;
import java.util.Set;
public class AddressFormatAnnotationFormatterFactory implements
AnnotationFormatterFactory<AddressFormat> {
@Override
public Set<Class<?>> getFieldTypes () {
return new HashSet<>(Arrays.asList(Address.class));
}
@Override
public Printer<?> getPrinter (AddressFormat annotation, Class<?> fieldType) {
return getAddressFormatter(annotation, fieldType);
}
@Override
public Parser<?> getParser (AddressFormat annotation, Class<?> fieldType) {
return getAddressFormatter(annotation, fieldType);
}
private AddressFormatter getAddressFormatter (AddressFormat annotation,
Class<?> fieldType) {
AddressFormatter formatter = new AddressFormatter();
formatter.setStyle(annotation.style());
return formatter;
}
}
Registering The AnnotationFormatterFactory
package com.logicbig.example;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.format.FormatterRegistry;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.ViewResolverRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
@EnableWebMvc
@Configuration
@ComponentScan
public class MyWebConfig implements WebMvcConfigurer {
@Override
public void configureViewResolvers(ViewResolverRegistry registry) {
registry.jsp("/WEB-INF/views/", ".jsp");
}
@Override
public void addFormatters(FormatterRegistry registry) {
AddressFormatAnnotationFormatterFactory factory = new AddressFormatAnnotationFormatterFactory();
registry.addFormatterForFieldAnnotation(factory);
}
}
Creating Controller
@Controller
@RequestMapping("/customers")
public class CustomerController {
@Autowired
private CustomerDataService customerDataService;
@RequestMapping(method = RequestMethod.GET)
private String handleRequest (Model model) {
model.addAttribute("customerList", customerDataService.getAllUsers());
return "customers";
}
}
customer.jsp
<%@ page language="java"
contentType="text/html; charset=ISO-8859-1"
pageEncoding="ISO-8859-1"%>
<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core"%>
<%@taglib uri="http://www.springframework.org/tags" prefix="spring" %>
<html>
<body>
<h3>Customer List </h3>
<table style="width:100%">
<c:forEach var="customer" items="${customerList}" varStatus="status">
<tr>
<td>
<spring:eval expression="customer.id" />
</td>
<td>
<spring:eval expression="customer.name" />
</td>
<td>
<spring:eval expression="customer.address" />
</td>
</tr>
</c:forEach>
</table>
</body>
</html>
Running Example
To try examples, run embedded Jetty (configured in pom.xml of example project below):
mvn jetty:run $ curl -s http://localhost:8080/spring-custom-formatter-annotation/customers
<html>
<body>
<h3>Customer List </h3>
<table style="width:100%">
<tr>
<td>
1
</td>
<td>
John Smith
</td>
<td>
123 Main St, New York, 10001, USA
</td>
</tr>
<tr>
<td>
2
</td>
<td>
Jane Doe
</td>
<td>
456 Oak Ave, Los Angeles, 90001, USA
</td>
</tr>
<tr>
<td>
3
</td>
<td>
Bob Johnson
</td>
<td>
789 Pine Rd, Chicago, 60601, USA
</td>
</tr>
</table>
</body>
</html>
Integration Test
package com.logicbig.example;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.test.context.ContextConfiguration;
import org.springframework.test.context.junit.jupiter.SpringExtension;
import org.springframework.test.context.junit.jupiter.web.SpringJUnitWebConfig;
import org.springframework.test.context.web.WebAppConfiguration;
import org.springframework.test.web.servlet.assertj.MockMvcTester;
import org.springframework.test.web.servlet.assertj.MvcTestResult;
import org.springframework.web.context.WebApplicationContext;
import java.text.ParseException;
import java.util.List;
import java.util.Locale;
import static org.assertj.core.api.Assertions.assertThat;
@SpringJUnitWebConfig(MyWebConfig.class)
public class CustomerControllerTest {
@Autowired
private WebApplicationContext wac;
private MockMvcTester mockMvc;
@BeforeEach
public void setup() {
this.mockMvc = MockMvcTester.from(this.wac);
}
@Test
public void testUserController() throws ParseException {
MvcTestResult result = this.mockMvc.get().uri("/customers").exchange();
assertThat(result)
.hasStatusOk()
.hasViewName("customers")
.model()
.containsKey("customerList");
List<Customer> customerList =
(List<Customer>) result.getMvcResult().getModelAndView()
.getModel().get("customerList");
assertThat(customerList).hasSize(3);
Customer customer = customerList.get(1);
assertThat(customer.getId()).isEqualTo(2L);
assertThat(customer.getName()).isEqualTo("Jane Doe");
assertThat(customer.getAddress().getStreet()).isEqualTo("456 Oak Ave");
assertThat(customer.getAddress().getCity()).isEqualTo("Los Angeles");
assertThat(customer.getAddress().getCounty()).isEqualTo("USA");
assertThat(customer.getAddress().getZipCode()).isEqualTo("90001");
AddressFormatter addressFormatter = new AddressFormatter();
String formattedAddress = addressFormatter.print(customer.getAddress(),
Locale.getDefault());
assertThat(formattedAddress).isEqualTo(
"456 Oak Ave, Los Angeles, 90001, USA");
Address parsedAddress = addressFormatter.parse(formattedAddress,
Locale.getDefault());
assertThat(parsedAddress).isEqualTo(customer.getAddress());
}
}
mvn clean test -Dtest="CustomerControllerTest" Output$ mvn clean test -Dtest="CustomerControllerTest"
[INFO] Scanning for projects...
[INFO]
[INFO] ------< com.logicbig.example:spring-custom-formatter-annotation >-------
[INFO] Building spring-custom-formatter-annotation 1.0-SNAPSHOT
[INFO] from pom.xml
[INFO] --------------------------------[ war ]---------------------------------
[INFO]
[INFO] --- clean:3.2.0:clean (default-clean) @ spring-custom-formatter-annotation ---
[INFO] Deleting D:\example-projects\spring-mvc\spring-custom-formatter-annotation\target
[INFO]
[INFO] --- resources:3.3.1:resources (default-resources) @ spring-custom-formatter-annotation ---
[WARNING] Using platform encoding (UTF-8 actually) to copy filtered resources, i.e. build is platform dependent!
[INFO] skip non existing resourceDirectory D:\example-projects\spring-mvc\spring-custom-formatter-annotation\src\main\resources
[INFO]
[INFO] --- compiler:3.15.0:compile (default-compile) @ spring-custom-formatter-annotation ---
[INFO] Recompiling the module because of changed source code.
[INFO] Compiling 10 source files with javac [debug target 25] to target\classes
[INFO]
[INFO] --- resources:3.3.1:testResources (default-testResources) @ spring-custom-formatter-annotation ---
[WARNING] Using platform encoding (UTF-8 actually) to copy filtered resources, i.e. build is platform dependent!
[INFO] skip non existing resourceDirectory D:\example-projects\spring-mvc\spring-custom-formatter-annotation\src\test\resources
[INFO]
[INFO] --- compiler:3.15.0:testCompile (default-testCompile) @ spring-custom-formatter-annotation ---
[INFO] Recompiling the module because of changed dependency.
[INFO] Compiling 2 source files with javac [debug target 25] to target\test-classes
[INFO] /D:/LogicBig/example-projects/spring-mvc/spring-custom-formatter-annotation/src/test/java/com/logicbig/example/CustomerControllerHamcrestTest.java: Some input files use unchecked or unsafe operations.
[INFO] /D:/LogicBig/example-projects/spring-mvc/spring-custom-formatter-annotation/src/test/java/com/logicbig/example/CustomerControllerHamcrestTest.java: Recompile with -Xlint:unchecked for details.
[INFO]
[INFO] --- surefire:3.2.5:test (default-test) @ spring-custom-formatter-annotation ---
[INFO] Using auto detected provider org.apache.maven.surefire.junitplatform.JUnitPlatformProvider
[WARNING] file.encoding cannot be set as system property, use <argLine>-Dfile.encoding=...</argLine> instead
[INFO]
[INFO] -------------------------------------------------------
[INFO] T E S T S
[INFO] -------------------------------------------------------
[INFO] Running com.logicbig.example.CustomerControllerTest
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.645 s -- in com.logicbig.example.CustomerControllerTest
[INFO]
[INFO] Results:
[INFO]
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 3.609 s
[INFO] Finished at: 2026-05-08T18:34:47+08:00
[INFO] ------------------------------------------------------------------------
INFO: Completed initialization in 1 ms
Example ProjectDependencies and Technologies Used: - spring-webmvc 7.0.6 (Spring Web MVC)
Version Compatibility: 3.2.9.RELEASE - 7.0.6 Version compatibilities of spring-webmvc with this example: Versions in green have been tested.
- spring-test 7.0.6 (Spring TestContext Framework)
- jakarta.servlet-api 6.1.0 (Jakarta Servlet API documentation)
- jakarta.servlet.jsp.jstl 3.0.1 (Jakarta Standard Tag Library Implementation)
- junit-jupiter-engine 6.0.3 (Module "junit-jupiter-engine" of JUnit)
- hamcrest 3.0 (Core API and libraries of hamcrest matcher framework)
- assertj-core 3.26.3 (Rich and fluent assertions for testing in Java)
- JDK 25
- Maven 3.9.11
|
