A Custom Data Binder in Spring MVC

1. Overview

This article will show how we can use Spring’s Data Binding mechanism in order to make our code more clear and readable by applying automatic primitives to objects conversions.

By default, Spring only knows how to convert simple types. In other words, once we submit data to controller Int, String or Boolean type of data, it will be bound to appropriate Java types automatically.

But in real-world projects, that won’t be enough, as we might need to bind more complex types of objects.

2. Binding Individual Objects to Request Parameters

Let’s start simple and first bind a simple type; we’ll have to provide a custom implementation of the Converter<S, T> interface where S is the type we are converting from, and T is the type we are converting to:

@Component
public class StringToLocalDateTimeConverter
  implements Converter<String, LocalDateTime> {

    @Override
    public LocalDateTime convert(String source) {
        return LocalDateTime.parse(
          source, DateTimeFormatter.ISO_LOCAL_DATE_TIME);
    }
}

Now we can use the following syntax in our controller:

@GetMapping("/findbydate/{date}")
public GenericEntity findByDate(@PathVariable("date") LocalDateTime date) {
    return ...;
}

2.1. Using Enums as Request Parameters

Next, we’ll see how to use enum as a RequestParameter.

Here, we have a simple enum Modes:

public enum Modes {
    ALPHA, BETA;
}

We’ll build a String to enum Converter as follows:

public class StringToEnumConverter implements Converter<String, Modes> {

    @Override
    public Modes convert(String from) {
        return Modes.valueOf(from);
    }
}

Then, we need to register our Converter:

@Configuration
public class WebConfig implements WebMvcConfigurer {

    @Override
    public void addFormatters(FormatterRegistry registry) {
        registry.addConverter(new StringToEnumConverter());
    }
}

Now we can use our Enum as a RequestParameter:

@GetMapping
public ResponseEntity<Object> getStringToMode(@RequestParam("mode") Modes mode) {
    // ...
}

Or as a PathVariable:

@GetMapping("/entity/findbymode/{mode}")
public GenericEntity findByEnum(@PathVariable("mode") Modes mode) {
    // ...
}

3. Binding a Hierarchy of Objects

Sometimes we need to convert the entire tree of the object hierarchy and it makes sense to have a more centralized binding rather than a set of individual converters.

In this example, we have AbstractEntity our base class:

public abstract class AbstractEntity {
    long id;
    public AbstractEntity(long id){
        this.id = id;
    }
}

And the sub-classes Foo and Bar:

public class Foo extends AbstractEntity {
    private String name;
    
    // standard constructors, getters, setters
}

public class Bar extends AbstractEntity {
    private int value;
    
    // standard constructors, getters, setters
}

In this case, we can implement ConverterFactory<S, R> where S will be the type we are converting from and R to be the base type defining the range of classes we can convert to:

public class StringToAbstractEntityConverterFactory 
  implements ConverterFactory<String, AbstractEntity>{

    @Override
    public <T extends AbstractEntity> Converter<String, T> getConverter(Class<T> targetClass) {
        return new StringToAbstractEntityConverter<>(targetClass);
    }

    private static class StringToAbstractEntityConverter<T extends AbstractEntity>
      implements Converter<String, T> {

        private Class<T> targetClass;

        public StringToAbstractEntityConverter(Class<T> targetClass) {
            this.targetClass = targetClass;
        }

        @Override
        public T convert(String source) {
            long id = Long.parseLong(source);
            if(this.targetClass == Foo.class) {
                return (T) new Foo(id);
            }
            else if(this.targetClass == Bar.class) {
                return (T) new Bar(id);
            } else {
                return null;
            }
        }
    }
}

As we can see, the only method that must implement is getConverter() which returns converter for needed type. The conversion process then is delegated to this converter.

Then, we need to register our ConverterFactory:

@Configuration
public class WebConfig implements WebMvcConfigurer {

    @Override
    public void addFormatters(FormatterRegistry registry) {
        registry.addConverterFactory(new StringToAbstractEntityConverterFactory());
    }
}

Finally, we can use it as we like in our controller:

@RestController
@RequestMapping("/string-to-abstract")
public class AbstractEntityController {

    @GetMapping("/foo/{foo}")
    public ResponseEntity<Object> getStringToFoo(@PathVariable Foo foo) {
        return ResponseEntity.ok(foo);
    }
    
    @GetMapping("/bar/{bar}")
    public ResponseEntity<Object> getStringToBar(@PathVariable Bar bar) {
        return ResponseEntity.ok(bar);
    }
}

4. Binding Domain Objects

There are cases when we want to bind data to objects, but it comes either in a non-direct way (for example, from Session, Header or Cookie variables) or even stored in a data source. In those cases, we need to use a different solution.

4.1. Custom Argument Resolver

First of all, we will define an annotation for such parameters:

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.PARAMETER)
public @interface Version {
}

Then, we will implement a custom HandlerMethodArgumentResolver:

public class HeaderVersionArgumentResolver
  implements HandlerMethodArgumentResolver {

    @Override
    public boolean supportsParameter(MethodParameter methodParameter) {
        return methodParameter.getParameterAnnotation(Version.class) != null;
    }

    @Override
    public Object resolveArgument(
      MethodParameter methodParameter, 
      ModelAndViewContainer modelAndViewContainer, 
      NativeWebRequest nativeWebRequest, 
      WebDataBinderFactory webDataBinderFactory) throws Exception {
 
        HttpServletRequest request 
          = (HttpServletRequest) nativeWebRequest.getNativeRequest();

        return request.getHeader("Version");
    }
}

The last thing is letting Spring know where to search for them:

@Configuration
public class WebConfig implements WebMvcConfigurer {

    //...

    @Override
    public void addArgumentResolvers(
      List<HandlerMethodArgumentResolver> argumentResolvers) {
        argumentResolvers.add(new HeaderVersionArgumentResolver());
    }
}

That’s it. Now we can use it in a controller:

@GetMapping("/entity/{id}")
public ResponseEntity findByVersion(
  @PathVariable Long id, @Version String version) {
    return ...;
}

As we can see, HandlerMethodArgumentResolver‘s resolveArgument() method returns an Object. In other words, we could return any object, not only String.

5. Conclusion

As a result, we got rid of many routine conversions and let Spring do most stuff for us. At the end, let’s conclude:

• For an individual simple type to object conversions we should use Converter implementation
• For encapsulating conversion logic for a range of objects, we can try ConverterFactory implementation
• For any data comes indirectly or it is required to apply additional logic to retrieve the associated data it’s better to use HandlerMethodArgumentResolver