Using Enums as Request Parameters in Spring

1. Introduction

In most typical web applications, we often need to restrict a request parameter to a set of predefined values. Enums are a great way to do this.

In this tutorial, we’ll demonstrate how to use enums as web request parameters in Spring MVC.

2. Use Enums as Request Parameters

Let’s first define an enum for our examples:

public enum Modes {
    ALPHA, BETA;
}

We can then use this enum as a RequestParameter in a Spring controller:

@GetMapping("/mode2str")
public String getStringToMode(@RequestParam("mode") Modes mode) {
    // ...
}

Or we can use it as a PathVariable:

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

When we make a web request, such as /mode2str?mode=ALPHA, the request parameter is a String object. Spring can try to convert this String object to an Enum object by using its StringToEnumConverterFactory class.

The back-end conversion uses the Enum.valueOf method. Therefore, the input name string must exactly match one of the declared enum values.

When we make a web request with a string value that doesn’t match one of our enum values, like /mode2str?mode=unknown, Spring will fail to convert it to the specified enum type. In this case, we’ll get a ConversionFailedException.

3. @RequestBody and Enum Value

Moving on, let’s add a custom value to each constant in our Modes enum:

public enum Modes {
    ALPHA("A"),
    BETA("B");

    private final String text;

    Modes(String text) {
        this.text = text;
    }
}

In the code above, each enum constant is associated with a custom string value. ALPHA has the value “A“, while BETA has the value “B“.

By default, Jackson expects the JSON value to match the enum constant name. Therefore, a request containing “ALPHA” would be deserialized correctly, but “A” wouldn’t. To allow Jackson to use our custom values during deserialization, we can define a factory method and annotate it with @JsonCreator:

public enum Modes {
    // ...

    @JsonCreator
    public static Modes fromText(String text) {
        for (Modes modes : Modes.values()) {
            if (modes.getText()
                .equals(text)) {
                return modes;
            }
        }
        throw new IllegalArgumentException("Unknown mode value: " + text);
    }

    @Override
    public String toString() {
        return text;
    }

}

Here, the fromText() factory method searches for an enum constant whose text value matches the value provided in the JSON request. The @JsonCreator annotation tells Jackson to use this method when deserializing the enum.

Next, let’s write an entity class that uses the enum:

public class ModeEntity {

    private Long id;

    private String name;

    private Modes mode;
    // standard constructor, getters and setters
}

We can then use this entity as the request body in our controller:

@PostMapping("/create-modes")
public String create(@RequestBody ModeEntity entity) {
    return "created";
 }

Finally, let’s write a unit test to verify that Jackson correctly deserializes the custom enum value:

class ModeDeserializationUnitTest {

    private final ObjectMapper objectMapper = new ObjectMapper();

    @Test
    void whenJsonContainsA_thenDeserializesToAlpha() throws Exception {
        ModeEntity entity = objectMapper.readValue("{\"mode\": \"A\"}", ModeEntity.class);
        assertEquals(Modes.ALPHA, entity.getMode());
    }
}

The test above passes because @JsonCreator instructs Jackson to use the fromText() method when deserializing the mode property.

4. Custom Converter

In Java, it’s considered good practice to define enum values with uppercase letters, as they are constants. However, we may want to support lowercase letters in the request URL.

In this case, we need to create a custom converter:

public class StringToEnumConverter implements Converter<String, Modes> {
    @Override
    public Modes convert(String source) {
        return Modes.valueOf(source.toUpperCase());
    }
}

To use our custom converter, we need to register it in the Spring configuration:

@Configuration
public class WebConfig implements WebMvcConfigurer {
    @Override
    public void addFormatters(FormatterRegistry registry) {
        registry.addConverter(new StringToEnumConverter());
    }
}

5. Exception Handling

The Enum.valueOf method in the StringToEnumConverter will throw an IllegalArgumentException if our Modes enum doesn’t have a matching constant. We can handle this exception in our custom converter in different ways, depending on our requirements.

For example, we can simply have our converter return null for non-matching Strings:

public class StringToEnumConverter implements Converter<String, Modes> {
    @Override
    public Modes convert(String source) {
        try {
            return Modes.valueOf(source.toUpperCase());
        } catch (IllegalArgumentException e) {
            return null;
        }
    }
}

However, if we don’t handle the exception locally in the custom converter, Spring will throw a ConversionFailedException to the calling controller method. There are several ways to handle this exception.

For example, we can use a global exception handler class:

@ControllerAdvice
public class GlobalControllerExceptionHandler {
    @ExceptionHandler(ConversionFailedException.class)
    public ResponseEntity<String> handleConflict(RuntimeException ex) {
        return new ResponseEntity<>(ex.getMessage(), HttpStatus.BAD_REQUEST);
    }
}

6. Conclusion

In this article, we learned how to use enums as request parameters in Spring with some code examples.

We also provided a custom converter example that can map the input string to an enum constant. We can use an enum directly as a request parameter or path variable when the default, case-sensitive conversion is sufficient. However, if we need to support different input formats, such as lowercase enum values, we can use a custom converter.

Finally, we discussed how to handle the exception thrown by Spring when it encounters an unknown input string.