DEV Community: Tom Hombergs

Hexagonal Architecture With Java and Spring

Tom Hombergs — Sun, 19 Jan 2020 03:10:52 +0000

The term "Hexagonal Architecture" has been around for a long time. Long enough that the primary source on this topic has been offline for a while and has only recently been rescued from the archives.

I found, however, that there are very few resources about how to actually implement an application in this architecture style. The goal of this article is to provide an opinionated way of implementing a web application in the hexagonal style with Java and Spring.

If you'd like to dive deeper into the topic, have a look at my book.

Code Example

This article is accompanied by a working code example on Github.

What is "Hexagonal Architecture"?

The main feature of "Hexagonal Architecture", as opposed to the common layered architecture style, is that the dependencies between our components point "inward", towards our domain objects:

The hexagon is just a fancy way to describe the core of the application that is made up of domain objects, use cases that operate on them, and input and output ports that provide an interface to the outside world.

Let's have a look at each of the stereotypes in this architecture style.

Domain Objects

In a domain rich with business rules, domain objects are the lifeblood of an application. Domain objects can contain both state and behavior. The closer the behavior is to the state, the easier the code will be to understand, reason about, and maintain.

Domain objects don't have any outward dependency. They're pure Java and provide an API for use cases to operate on them.

Because domain objects have no dependencies on other layers of the application, changes in other layers don't affect them. They can evolve free of dependencies. This is a prime example of the Single Responsibility Principle (the "S" in "SOLID"), which states that components should have only one reason to change. For our domain object, this reason is a change in business requirements.

Having a single responsibility lets us evolve our domain objects without having to take external dependencies in regard. This evolvability makes the hexagonal architecture style perfect for when you're practicing Domain-Driven Design. While developing, we just follow the natural flow of dependencies: we start coding in the domain objects and go outward from there. If that's not Domain-Driven, then I don't know what is.

Use Cases

We know use cases as abstract descriptions of what users are doing with our software. In the hexagonal architecture style, it makes sense to promote use cases to first-class citizens of our codebase.

A use case in this sense is a class that handles everything around, well, a certain use case. As an example let's consider the use case "Send money from one account to another" in a banking application. We'd create a class SendMoneyUseCase with a distinct API that allows a user to transfer money. The code contains all the business rule validations and logic that are specific to the use case and thus cannot be implemented within the domain objects. Everything else is delegated to the domain objects (there might be a domain object Account, for instance).

Similar to the domain objects, a use case class has no dependency on outward components. When it needs something from outside of the hexagon, we create an output port.

Input and Output Ports

The domain objects and use cases are within the hexagon, i.e. within the core of the application. Every communication to and from the outside happens through dedicated "ports".

An input port is a simple interface that can be called by outward components and that is implemented by a use case. The component calling such an input port is called an input adapter or "driving" adapter.

An output port is again a simple interface that can be called by our use cases if they need something from the outside (database access, for instance). This interface is designed to fit the needs of the use cases, but it's implemented by an outside component called an output or "driven" adapter. If you're familiar with the SOLID principles, this is an application of the Dependency Inversion Principle (the "D" in SOLID), because we're inverting the dependency from the use cases to the output adapter using an interface.

With input and output ports in place, we have very distinct places where data enters and leaves our system, making it easy to reason about the architecture.

Adapters

The adapters form the outer layer of the hexagonal architecture. They are not part of the core but interact with it.

Input adapters or "driving" adapters call the input ports to get something done. An input adapter could be a web interface, for instance. When a user clicks a button in a browser, the web adapter calls a certain input port to call the corresponding use case.

Output adapters or "driven" adapters are called by our use cases and might, for instance, provide data from a database. An output adapter implements a set of output port interfaces. Note that the interfaces are dictated by the use cases and not the other way around.

The adapters make it easy to exchange a certain layer of the application. If the application should be usable from a fat client additionally to the web, we add a fat client input adapter. If the application needs a different database, we add a new persistence adapter implementing the same output port interfaces as the old one.

Show Me Some Code!

After the brief introduction to the hexagonal architecture style above, let's finally have a look at some code. Translating the concepts of an architecture style into code is always subject to interpretation and flavor, so please don't take the following code examples as given, but instead as inspiration to creating your own style.

The code examples are all from my "BuckPal" example application on GitHub and revolve around the use case of transferring money from one account to another. Some code snippets are slightly modified for the purpose of this blog post, so have a look at the repo for the original code.

Building a Domain Object

We start by building a domain object that serves our use case. We create an Account class that manages withdrawals and deposits to an account:

@AllArgsConstructor(access = AccessLevel.PRIVATE)
public class Account {

  @Getter private final AccountId id;

  @Getter private final Money baselineBalance;

  @Getter private final ActivityWindow activityWindow;

  public static Account account(
          AccountId accountId,
          Money baselineBalance,
          ActivityWindow activityWindow) {
    return new Account(accountId, baselineBalance, activityWindow);
  }

  public Optional<AccountId> getId(){
    return Optional.ofNullable(this.id);
  }

  public Money calculateBalance() {
    return Money.add(
        this.baselineBalance,
        this.activityWindow.calculateBalance(this.id));
  }

  public boolean withdraw(Money money, AccountId targetAccountId) {

    if (!mayWithdraw(money)) {
      return false;
    }

    Activity withdrawal = new Activity(
        this.id,
        this.id,
        targetAccountId,
        LocalDateTime.now(),
        money);
    this.activityWindow.addActivity(withdrawal);
    return true;
  }

  private boolean mayWithdraw(Money money) {
    return Money.add(
        this.calculateBalance(),
        money.negate())
        .isPositiveOrZero();
  }

  public boolean deposit(Money money, AccountId sourceAccountId) {
    Activity deposit = new Activity(
        this.id,
        sourceAccountId,
        this.id,
        LocalDateTime.now(),
        money);
    this.activityWindow.addActivity(deposit);
    return true;
  }

  @Value
  public static class AccountId {
    private Long value;
  }

}

An Account can have many associated Activitys that each represents a withdrawal or a deposit to that account. Since we don't always want to load all activities for a given account, we limit it to a certain ActivityWindow. To still be able to calculate the total balance of the account, the Account class has the baselineBalance attribute containing the balance of the account at the start time of the activity window.

As you can see in the code above, we build our domain objects completely free of dependencies to the other layers of our architecture. We're free to model the code how we see fit, in this case creating a "rich" behavior that is very close to the state of the model to make it easier to understand.

We can use external libraries in our domain model if we choose to, but those dependencies should be relatively stable to prevent forced changes to our code. In the case above, we included Lombok annotations, for instance.

The Account class now allows us to withdraw and deposit money to a single account, but we want to transfer money between two accounts. So, we create a use case class that orchestrates this for us.

Building an Input Port

Before we actually implement the use case, however, we create the external API to that use case, which will become an input port in our hexagonal architecture:

public interface SendMoneyUseCase {

  boolean sendMoney(SendMoneyCommand command);

  @Value
  @EqualsAndHashCode(callSuper = false)
  class SendMoneyCommand extends SelfValidating<SendMoneyCommand> {

    @NotNull
    private final AccountId sourceAccountId;

    @NotNull
    private final AccountId targetAccountId;

    @NotNull
    private final Money money;

    public SendMoneyCommand(
        AccountId sourceAccountId,
        AccountId targetAccountId,
        Money money) {
      this.sourceAccountId = sourceAccountId;
      this.targetAccountId = targetAccountId;
      this.money = money;
      this.validateSelf();
    }
  }

}

By calling sendMoney(), an adapter outside of our application core can now invoke this use case.

We aggregated all the parameters we need into the SendMoneyCommand value object. This allows us to do the input validation in the constructor of the value object. In the example above we even used the Bean Validation annotation @NotNull, which is validated in the validateSelf() method. This way the actual use case code is not polluted with noisy validation code.

Now we need an implementation of this interface.

Building a Use Case and Output Ports

In the use case implementation we use our domain model to make a withdrawal from the source account and a deposit to the target account:

@RequiredArgsConstructor
@Component
@Transactional
public class SendMoneyService implements SendMoneyUseCase {

  private final LoadAccountPort loadAccountPort;
  private final AccountLock accountLock;
  private final UpdateAccountStatePort updateAccountStatePort;

  @Override
  public boolean sendMoney(SendMoneyCommand command) {

    LocalDateTime baselineDate = LocalDateTime.now().minusDays(10);

    Account sourceAccount = loadAccountPort.loadAccount(
        command.getSourceAccountId(),
        baselineDate);

    Account targetAccount = loadAccountPort.loadAccount(
        command.getTargetAccountId(),
        baselineDate);

    accountLock.lockAccount(sourceAccountId);
    if (!sourceAccount.withdraw(command.getMoney(), targetAccountId)) {
      accountLock.releaseAccount(sourceAccountId);
      return false;
    }

    accountLock.lockAccount(targetAccountId);
    if (!targetAccount.deposit(command.getMoney(), sourceAccountId)) {
      accountLock.releaseAccount(sourceAccountId);
      accountLock.releaseAccount(targetAccountId);
      return false;
    }

    updateAccountStatePort.updateActivities(sourceAccount);
    updateAccountStatePort.updateActivities(targetAccount);

    accountLock.releaseAccount(sourceAccountId);
    accountLock.releaseAccount(targetAccountId);
    return true;
  }

}

Basically, the use case implementation loads the source and target account from the database, locks the accounts so that no other transactions can take place at the same time, makes the withdrawal and deposit, and finally writes the new state of the accounts back to the database.

Also, by using @Component, we make this service a Spring bean to be injected into any components that need access to the SendMoneyUseCase input port without having a dependency on the actual implementation.

For loading and storing the accounts from and to the database, the implementation depends on the output ports LoadAccountPort and UpdateAccountStatePort, which are interfaces that we will later implement within our persistence adapter.

The shape of the output port interfaces is dictated by the use case. While writing the use case we may find that we need to load certain data from the database, so we create an output port interface for it. Those ports may be re-used in other use cases, of course. In our case, the output ports look like this:

public interface LoadAccountPort {

  Account loadAccount(AccountId accountId, LocalDateTime baselineDate);

}

public interface UpdateAccountStatePort {

  void updateActivities(Account account);

}

Building a Web Adapter

With the domain model, use cases, and input and output ports, we have now completed the core of our application (i.e. everything within the hexagon). This core doesn't help us, though, if we don't connect it with the outside world. Hence, we build an adapter that exposes our application core via a REST API:

@RestController
@RequiredArgsConstructor
public class SendMoneyController {

  private final SendMoneyUseCase sendMoneyUseCase;

  @PostMapping(path = "/accounts/send/{sourceAccountId}/{targetAccountId}/{amount}")
  void sendMoney(
      @PathVariable("sourceAccountId") Long sourceAccountId,
      @PathVariable("targetAccountId") Long targetAccountId,
      @PathVariable("amount") Long amount) {

    SendMoneyCommand command = new SendMoneyCommand(
        new AccountId(sourceAccountId),
        new AccountId(targetAccountId),
        Money.of(amount));

    sendMoneyUseCase.sendMoney(command);
  }

}

If you're familiar with Spring MVC, you'll find that this is a pretty boring web controller. It simply reads the needed parameters from the request path, puts them into a SendMoneyCommand and invokes the use case. In a more complex scenario, the web controller may also check authentication and authorization and do more sophisticated mapping of JSON input, for example.

The above controller exposes our use case to the world by mapping HTTP requests to the use case's input port. Let's now see how we can connect our application to a database by connecting the output ports.

Building a Persistence Adapter

While an input port is implemented by a use case service, an output port is implemented by a persistence adapter. Say we use Spring Data JPA as the tool of choice for managing persistence in our codebase. A persistence adapter implementing the output ports LoadAccountPort and UpdateAccountStatePort might then look like this:

@RequiredArgsConstructor
@Component
class AccountPersistenceAdapter implements
    LoadAccountPort,
    UpdateAccountStatePort {

  private final AccountRepository accountRepository;
  private final ActivityRepository activityRepository;
  private final AccountMapper accountMapper;

  @Override
  public Account loadAccount(
          AccountId accountId,
          LocalDateTime baselineDate) {

    AccountJpaEntity account =
        accountRepository.findById(accountId.getValue())
            .orElseThrow(EntityNotFoundException::new);

    List<ActivityJpaEntity> activities =
        activityRepository.findByOwnerSince(
            accountId.getValue(),
            baselineDate);

    Long withdrawalBalance = orZero(activityRepository
        .getWithdrawalBalanceUntil(
            accountId.getValue(),
            baselineDate));

    Long depositBalance = orZero(activityRepository
        .getDepositBalanceUntil(
            accountId.getValue(),
            baselineDate));

    return accountMapper.mapToDomainEntity(
        account,
        activities,
        withdrawalBalance,
        depositBalance);

  }

  private Long orZero(Long value){
    return value == null ? 0L : value;
  }

  @Override
  public void updateActivities(Account account) {
    for (Activity activity : account.getActivityWindow().getActivities()) {
      if (activity.getId() == null) {
        activityRepository.save(accountMapper.mapToJpaEntity(activity));
      }
    }
  }

}

The adapter implements the loadAccount() and updateActivities() methods required by the implemented output ports. It uses Spring Data repositories to load data from and save data to the database and an AccountMapper to map Account domain objects into AccountJpaEntity objects which represent an account within the database.

Again, we use @Component to make this a Spring bean that can be injected into the use case service above.

Is it Worth the Effort?

People often ask themselves whether an architecture like this is worth the effort (I include myself here). After all, we have to create port interfaces and we have x to map between multiple representations of the domain model. There may be a domain model representation within the web adapter and another one within the persistence adapter.

So, is it worth the effort?

As a professional consultant my answer is of course "it depends".

If we're building a CRUD application that simply stores and saves data, an architecture like this is probably overhead. If we're building an application with rich business rules that can be expressed in a rich domain model that combines state with behavior, then this architecture really shines because it puts the domain model in the center of things.

Dive Deeper

The above only gives an idea of what a hexagonal architecture might look like in real code. There are other ways of doing it, so feel free to experiment and find the way that best fits your needs. Also, the web and persistence adapters are just examples of adapters to the outside. There may be adapters to other third party systems or other user-facing frontends.

If you want to dive deeper into this topic, have a look at my book which goes into much more detail and also discusses things like testing, mapping strategies, and shortcuts.

All You Need To Know About Bean Validation With Spring Boot

Tom Hombergs — Tue, 07 Jan 2020 08:53:48 +0000

Bean Validation is the de-facto standard for implementing validation logic in the Java ecosystem. It's well integrated with Spring and Spring Boot.

However, there are some pitfalls. This tutorial goes over all major validation use cases and sports code examples for each.

Code Example

This article is accompanied by a working example code on GitHub.

Setting Up Validation

Spring Boot's Bean Validation support comes with the validation starter, which we can include into our project (Gradle notation):

implementation('org.springframework.boot:spring-boot-starter-validation')

It's not necessary to add the version number since the Spring Dependency Management Gradle plugin does that for us. If you're not using the plugin, you can find the most recent version here.

However, if we have also included the web starter, the validation starter comes for free:

implementation('org.springframework.boot:spring-boot-starter-web')

Note that the validation starter does no more than adding a dependency to a compatible version of hibernate validator, which is
the most widely used implementation of the Bean Validation specification.

Bean Validation Basics

Very basically, Bean Validation works by defining constraints to the fields of a class by annotating them with certain annotations.

Then, you pass an object of that class into a Validator which checks if the constraints are satisfied.

We'll see more details in the examples below.

Validating Input to a Spring MVC Controller

Let's say we have implemented a Spring REST controller and want to validate the input that' passed in by a client. There are three things we can validate for any incoming HTTP request:

the request body,
variables within the path (e.g. id in /foos/{id}) and,
query parameters.

Let's look at each of those in more detail.

Validating a Request Body

In POST and PUT requests, it's common to pass a JSON payload within the request body. Spring automatically maps the incoming JSON to a Java object. Now, we want to check if the incoming Java object meets our requirements.

This is our incoming payload class:

class Input {

  @Min(1)
  @Max(10)
  private int numberBetweenOneAndTen;

  @Pattern(regexp = "^[0-9]{1,3}\\.[0-9]{1,3}\\.[0-9]{1,3}\\.[0-9]{1,3}$")
  private String ipAddress;

  // ...
}

We have an int field that must have a value between 1 and 10, inclusively, and a String field that must contain an IP address (the regex actually still allows invalid IP addresses with octets greater than 255, but we're fixing that later in the tutorial).

Here's the REST controller that takes an Input object in the request body and validates it:

@RestController
class ValidateRequestBodyController {

  @PostMapping("/validateBody")
  ResponseEntity<String> validateBody(@Valid @RequestBody Input input) {
    return ResponseEntity.ok("valid");
  }

}

We simply have added the @Valid annotation to the Input parameter, which is also annotated with @RequestBody to mark that it should be read from the request body. By doing this, we're telling Spring to pass the object to a Validator before doing anything else.

@Valid on Complex Types

If the Input class contains a field with another complex type that should be validated, this field, too, needs to be annotated with @Valid.

If the validation fails, it will trigger a MethodArgumentNotValidException. By default, Spring will translate this exception to a HTTP status 400 (Bad Request).

We can verify this behavior with an integration test:

@ExtendWith(SpringExtension.class)
@WebMvcTest(controllers = ValidateRequestBodyController.class)
class ValidateRequestBodyControllerTest {

  @Autowired
  private MockMvc mvc;

  @Autowired
  private ObjectMapper objectMapper;

  @Test
  void whenInputIsInvalid_thenReturnsStatus400() throws Exception {
    Input input = invalidInput();
    String body = objectMapper.writeValueAsString(input);

    mvc.perform(post("/validateBody")
            .contentType("application/json")
            .content(body))
            .andExpect(status().isBadRequest());
  }
}

You can find more details about testing Spring MVC controllers in my article about the @WebMvcTest annotation.

Validating Path Variables and Request Parameters

Validating path variables and request parameters works a little differently.

We're not validating complex Java objects in this case, since path variables and request parameters are primitive types like int or their counterpart objects like Integer
or String.

Instead of annotating a class field like above, we're adding a constraint annotation (in this case @Min) directly to the method parameter in the Spring controller:

@RestController
@Validated
class ValidateParametersController {

  @GetMapping("/validatePathVariable/{id}")
  ResponseEntity<String> validatePathVariable(
      @PathVariable("id") @Min(5) int id) {
    return ResponseEntity.ok("valid");
  }

  @GetMapping("/validateRequestParameter")
  ResponseEntity<String> validateRequestParameter(
      @RequestParam("param") @Min(5) int param) { 
    return ResponseEntity.ok("valid");
  }
}

Note that we have to add Spring's @Validated annotation to the controller at class level to tell Spring to evaluate the constraint annotations on method parameters.

The @Validated annotation is only evaluated on class level in this case, even though it's allowed to be used on methods (we'll learn why it's allowed on method level when discussing validation groups later).

In contrast to request body validation a failed validation will trigger a ConstraintViolationException instead of a MethodArgumentNotValidException. Spring does not register a default exception handler for this exception, so it will by default cause a response with HTTP status 500 (Internal Server Error).

If we want to return a HTTP status 400 instead (which makes sense, since the client provided an invalid parameter, making it a bad request), we can add a custom exception handler to our contoller:

@RestController
@Validated
class ValidateParametersController {

  // request mapping method omitted

  @ExceptionHandler(ConstraintViolationException.class)
  @ResponseStatus(HttpStatus.BAD_REQUEST)
  ResponseEntity<String> handleConstraintViolationException(ConstraintViolationException e) {
    return new ResponseEntity<>("not valid due to validation error: " + e.getMessage(), 
      HttpStatus.BAD_REQUEST);
  }

}

Later in this tutorial we will look at how to return a structured error response that contains details on all failed validations for the client to inspect.

We can verify the validation behavior with an integration test:

@ExtendWith(SpringExtension.class)
@WebMvcTest(controllers = ValidateParametersController.class)
class ValidateParametersControllerTest {

  @Autowired
  private MockMvc mvc;

  @Test
  void whenPathVariableIsInvalid_thenReturnsStatus400() throws Exception {
    mvc.perform(get("/validatePathVariable/3"))
            .andExpect(status().isBadRequest());
  }

  @Test
  void whenRequestParameterIsInvalid_thenReturnsStatus400() throws Exception {
    mvc.perform(get("/validateRequestParameter")
            .param("param", "3"))
            .andExpect(status().isBadRequest());
  }

}

Validating Input to a Spring Service Method

Instead of (or additionally to) validating input on the controller level, we can also validate the input to any Spring components. In order to to this, we use a combination of the @Validated and @Valid annotations:

@Service
@Validated
class ValidatingService{

    void validateInput(@Valid Input input){
      // do something
    }

}

Again, the @Validated annotation is only evaluated on class level, so don't put it on a method in this use case.

Here's a test verifying the validation behavior:

@ExtendWith(SpringExtension.class)
@SpringBootTest
class ValidatingServiceTest {

  @Autowired
  private ValidatingService service;

  @Test
  void whenInputIsInvalid_thenThrowsException(){
    Input input = invalidInput();

    assertThrows(ConstraintViolationException.class, () -> {
      service.validateInput(input);
    });
  }

}

Validating JPA Entities

The last line of defense for validation is the persistence layer. By default, Spring Data uses Hibernate underneath, which supports Bean Validation out of the box.

Is the Persistence Layer the right Place for Validation?

We usually don't want to do validation as late as in the persistence layer because it means that the business code above has worked with potentially invalid objects which may lead to unforeseen errors. More on this topic in my article about Bean Validation Anti-Patterns.

Let's say want to store objects of our Input class to the database. First, we add the necessary JPA annotation @Entity and add an ID field:

@Entity
public class Input {

  @Id
  @GeneratedValue
  private Long id;

  @Min(1)
  @Max(10)
  private int numberBetweenOneAndTen;

  @Pattern(regexp = "^[0-9]{1,3}\\.[0-9]{1,3}\\.[0-9]{1,3}\\.[0-9]{1,3}$")
  private String ipAddress;

  // ...

}

Then, we create a Spring Data repository that provides us with methods to persist and query for Input objects:

public interface ValidatingRepository extends CrudRepository<Input, Long> {}

By default, any time we use the repository to store an Input object whose constraint annotations are violated, we'll get a ConstraintViolationException as this integration test demonstrates:

@ExtendWith(SpringExtension.class)
@DataJpaTest
class ValidatingRepositoryTest {

  @Autowired
  private ValidatingRepository repository;

  @Autowired
  private EntityManager entityManager;

  @Test
  void whenInputIsInvalid_thenThrowsException() {
    Input input = invalidInput();

    assertThrows(ConstraintViolationException.class, () -> {
      repository.save(input);
      entityManager.flush();
    });
  }

}

You can find more details about testing Spring Data repositories in my article about the @DataJpaTest annotation.

Note that Bean Validation is only triggered by Hibernate once the EntityManager is flushed. Hibernate flushes thes EntityManager automatically under certain circumstances, but in the case of our integration test we have to do this by hand.

If for any reason we want to disable Bean Validation in our Spring Data repositories, we can set the Spring Boot property spring.jpa.properties.javax.persistence.validation.mode to none.

Implementing A Custom Validator

If the available constraint annotations do not suffice for our use cases, we might want to create one ourselves.

In the Input class from above, we used a regular expression to validate that a String is a valid IP address. However, the regular expression is not complete: it allows octets with values greater than 255 (i.e. "111.111.111.333" would be considered valid).

Let's fix this by implementing a validator that implements this check in Java instead of with a regular expression (yes, I know that we could just use a more complex regular expression to achieve the same result, but we like to implement validations in Java, don't we?).

First, we create the custom constraint annotation IpAddress:

@Target({ FIELD })
@Retention(RUNTIME)
@Constraint(validatedBy = IpAddressValidator.class)
@Documented
public @interface IpAddress {

  String message() default "{IpAddress.invalid}";

  Class<?>[] groups() default { };

  Class<? extends Payload>[] payload() default { };

}

A custom constraint annotation needs all of the following:

the parameter message, pointing to a property key in ValidationMessages.properties, which is used to resolve a message in case of violation,
the parameter groups, allowing to define under which circumstances this validation is to be triggered (we're going to talk about validation groups later),
the parameter payload, allowing to define a payload to be passed with this validation (since this is a rarely used feature, we'll not cover it in this tutorial), and
a @Constraint annotation pointing to an implementation of the ConstraintValidator interface.

The validator implementation looks like this:

class IpAddressValidator implements ConstraintValidator<IpAddress, String> {

  @Override
  public boolean isValid(String value, ConstraintValidatorContext context) {
    Pattern pattern = 
      Pattern.compile("^([0-9]{1,3})\\.([0-9]{1,3})\\.([0-9]{1,3})\\.([0-9]{1,3})$");
    Matcher matcher = pattern.matcher(value);
    try {
      if (!matcher.matches()) {
        return false;
      } else {
        for (int i = 1; i <= 4; i++) {
          int octet = Integer.valueOf(matcher.group(i));
          if (octet > 255) {
            return false;
          }
        }
        return true;
      }
    } catch (Exception e) {
      return false;
    }
  }
}

We can now use the @IpAddress annotation just like any other constraint annotation:

class InputWithCustomValidator {

  @IpAddress
  private String ipAddress;

  // ...

}

Validating Programmatically

There may be cases when we want to invoke validation programmatically instead of relying on Spring's built-in Bean Validation support.

In this case, we can just create a Validator by hand and invoke it to trigger a validation:

class ProgrammaticallyValidatingService {

  void validateInput(Input input) {
    ValidatorFactory factory = Validation.buildDefaultValidatorFactory();
    Validator validator = factory.getValidator();
    Set<ConstraintViolation<Input>> violations = validator.validate(input);
    if (!violations.isEmpty()) {
      throw new ConstraintViolationException(violations);
    }
  }

}

This requires no Spring support whatsoever.

However, Spring Boot provides us with a pre-configured Validator instance. We can inject this instance into our service and use this instance instead of creating one by hand:

@Service
class ProgrammaticallyValidatingService {

  private Validator validator;

  ProgrammaticallyValidatingService(Validator validator) {
    this.validator = validator;
  }

  void validateInputWithInjectedValidator(Input input) {
    Set<ConstraintViolation<Input>> violations = validator.validate(input);
    if (!violations.isEmpty()) {
      throw new ConstraintViolationException(violations);
    }
  }
}

When this service is instantiated by Spring, it will automatically have a Validator instance injected into the constructor.

The following unit test proves that both methods above work as expected:

@ExtendWith(SpringExtension.class)
@SpringBootTest
class ProgrammaticallyValidatingServiceTest {

  @Autowired
  private ProgrammaticallyValidatingService service;

  @Test
  void whenInputIsInvalid_thenThrowsException(){
    Input input = invalidInput();

    assertThrows(ConstraintViolationException.class, () -> {
      service.validateInput(input);
    });
  }

  @Test
  void givenInjectedValidator_whenInputIsInvalid_thenThrowsException(){
    Input input = invalidInput();

    assertThrows(ConstraintViolationException.class, () -> {
      service.validateInputWithInjectedValidator(input);
    });
  }

}

Using Validation Groups to Validate Objects Differently for Different Use Cases

Often, certain objects are shared between different use cases.

Let's take the typical CRUD operations, for example: the "Create" use case and the "Update" use case will most probably both take the same object type as input. However, there may be validations that should be triggered under different circumstances:

only in the "Create" use case,
only in the "Update" use case, or
in both use cases.

The Bean Validation feature that allows us to implement validation rules like this is called "Validation Groups".

We have already seen that all constraint annotations must have a groups field. This can be used to pass any classes that each define a certain validation group that should be triggered.

For our CRUD example, we simply define two marker interfaces OnCreate and OnUpdate:

interface OnCreate {}

interface OnUpdate {}

We can then use these marker interfaces with any constraint annotation like this:

class InputWithGroups {

  @Null(groups = OnCreate.class)
  @NotNull(groups = OnUpdate.class)
  private Long id;

  // ...

}

This will make sure that the ID is empty in our "Create" use case and that it's not empty in our "Update" use case.

Spring supports validation groups with the @Validated annotation:

@Service
@Validated
class ValidatingServiceWithGroups {

    @Validated(OnCreate.class)
    void validateForCreate(@Valid InputWithGroups input){
      // do something
    }

    @Validated(OnUpdate.class)
    void validateForUpdate(@Valid InputWithGroups input){
      // do something
    }

}

Note that the @Validated annotation must again be applied to the whole class. To define which validation group should be active, it must also be applied at method level.

To make certain that the above works as expected, we can implement a unit test:

@ExtendWith(SpringExtension.class)
@SpringBootTest
class ValidatingServiceWithGroupsTest {

  @Autowired
  private ValidatingServiceWithGroups service;

  @Test
  void whenInputIsInvalidForCreate_thenThrowsException() {
    InputWithGroups input = validInput();
    input.setId(42L);

    assertThrows(ConstraintViolationException.class, () -> {
      service.validateForCreate(input);
    });
  }

  @Test
  void whenInputIsInvalidForUpdate_thenThrowsException() {
    InputWithGroups input = validInput();
    input.setId(null);

    assertThrows(ConstraintViolationException.class, () -> {
      service.validateForUpdate(input);
    });
  }

}

Careful with Validation Groups!

Using validation groups can easily become an anti-pattern since we're mixing concerns. With validation groups, the validated entity has to know the validation rules for all the use cases (groups) it is used in. More on this topic in my article about Bean Validation Anti-Patterns.

Returning Structured Error Responses

When a validation fails, we want to return a meaningful error message to the client. In order to enable the client to display a helpful error message, we should return a data structure that contains an error message for each
validation that failed.

First, we need to define that data structure. We'll call it ValidationErrorResponse and it contains a list of Violation objects:

public class ValidationErrorResponse {

  private List<Violation> violations = new ArrayList<>();

  // ...
}

public class Violation {

  private final String fieldName;

  private final String message;

  // ...
}

Then, we create a global ControllerAdvice that handles all ConstraintViolationExceptions that bubble up to the controller level. In order to catch validation errors for request bodies as well, we will also handle MethodArgumentNotValidExceptions:

@ControllerAdvice
class ErrorHandlingControllerAdvice {

  @ExceptionHandler(ConstraintViolationException.class)
  @ResponseStatus(HttpStatus.BAD_REQUEST)
  @ResponseBody
  ValidationErrorResponse onConstraintValidationException(
      ConstraintViolationException e) {
    ValidationErrorResponse error = new ValidationErrorResponse();
    for (ConstraintViolation violation : e.getConstraintViolations()) {
      error.getViolations().add(
        new Violation(violation.getPropertyPath().toString(), violation.getMessage()));
    }
    return error;
  }

  @ExceptionHandler(MethodArgumentNotValidException.class)
  @ResponseStatus(HttpStatus.BAD_REQUEST)
  @ResponseBody
  ValidationErrorResponse onMethodArgumentNotValidException(
      MethodArgumentNotValidException e) {
    ValidationErrorResponse error = new ValidationErrorResponse();
    for (FieldError fieldError : e.getBindingResult().getFieldErrors()) {
      error.getViolations().add(
        new Violation(fieldError.getField(), fieldError.getDefaultMessage()));
    }
    return error;
  }

}

What we're doing here is simply reading information about the violations out of the exceptions and translating them into our ValidationErrorResponse data structure.

Note the @ControllerAdvice annotation which makes the exception handler methods available globally to all controllers within the application context.

Conclusion

In this tutorial, we've gone through all major validation features we might need when building an application with Spring Boot.

If you want to get your hands dirty on the example code, have a look at the
github repository.