Skip to content

9. Arquitetura em camadas e acesso a dados

Os exemplos anteriores armazenavam seus dados em memória. Uma aplicação real os armazena em um banco de dados e é organizada em camadas (veja o diagrama na introdução):

  • a camada web (controllers, views): lê a requisição, chama a camada de negócio, seleciona a view;
  • a camada de negócio: regras de negócio;
  • a camada DAO ([Data Access Object]): consultas ao banco de dados.

Cada camada conhece apenas a camada imediatamente abaixo dela, e o mínimo possível de detalhes sobre ela: a camada web desconhece o SQL, e a camada de negócio desconhece o HTML. Essa separação torna cada camada mais fácil de entender, testar e evoluir. O exemplo 28 aplica isso ao gerenciamento de uma lista de pessoas: é, em escala menor, o gerenciamento de médicos e clientes do estudo de caso.

Em [Java], o acesso ao banco de dados é organizado em várias camadas:

  • [JDBC] ([Java Database Connectivity]) é a interface padrão para que [Java] envie comandos SQL a um banco de dados. Cada SGBD fornece um driver [JDBC]: para o [MySQL], a biblioteca [mysql-connector-j]. Abrir uma conexão consome muitos recursos: [Spring Boot] usa um pool de conexões ([HikariCP]), que mantém algumas conexões abertas e as empresta às requisições;
  • [JPA] ([Jakarta Persistence API]) é o padrão do [Java] para ORM ([Object-Relational Mapper]): ele mapeia as classes [Java] (entidades) para tabelas do banco de dados e transforma as linhas lidas em objetos. [JPA] é apenas um padrão, composto por interfaces e anotações; o ORM que o implementa é, neste caso, o [Hibernate];
  • [Spring Data JPA] é acrescentado sobre isso: basta declarar uma interface DAO, e o [Spring Data JPA] escreve a implementação sozinho quando a aplicação é iniciada, inclusive as consultas, que ele deduz dos nomes dos métodos.

Tudo isso é fornecido pelo starter [spring-boot-starter-data-jpa].

9.1. Exemplo 28: um sistema de gerenciamento de pessoal em três camadas

28-layers/
├── database/
│   └── dbpersons.sql
├── src/
│   └── main/
│       ├── java/
│       │   └── example28/
│       │       ├── config/
│       │       │   └── WebConfig.java
│       │       ├── controllers/
│       │       │   └── PersonsController.java
│       │       ├── dao/
│       │       │   └── PersonsDao.java
│       │       ├── entities/
│       │       │   └── Person.java
│       │       ├── business/
│       │       │   ├── PersonData.java
│       │       │   ├── BusinessException.java
│       │       │   └── PersonsBusiness.java
│       │       ├── models/
│       │       │   └── PersonForm.java
│       │       └── Example28Application.java
│       └── resources/
│           ├── static/
│           │   ├── css/
│           │   │   └── styles.css
│           │   └── js/
│           │       └── app.js
│           ├── templates/
│           │   ├── fragments/
│           │   │   ├── field.html
│           │   │   └── confirmation.html
│           │   ├── persons/
│           │   │   ├── form.html
│           │   │   └── list.html
│           │   └── layout.html
│           ├── application.properties
│           └── messages.properties
└── pom.xml

9.1.1. O banco de dados

O banco de dados [dbpersons] é criado por um script SQL. Usando o [Laragon], você pode executá-lo, por exemplo, na ferramenta [HeidiSQL] (menu Arquivo / Executar arquivo SQL), ou pela linha de comando, a partir da pasta do exemplo:

mysql -u root < database/dbpersons.sql

O arquivo [database/dbpersons.sql]:

-- banco de dados do exemplo 28: uma única tabela, [persons]
-- o script é escrito em UTF-8
SET NAMES utf8mb4;
DROP DATABASE IF EXISTS dbpersons;
CREATE DATABASE dbpersons CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
USE dbpersons;

CREATE TABLE persons (
  id INT NOT NULL AUTO_INCREMENT,
  -- a versão da linha, incrementada pelo JPA a cada modificação
  version INT NOT NULL DEFAULT 0,
  first_name VARCHAR(30) NOT NULL,
  last_name VARCHAR(30) NOT NULL,
  age INT NOT NULL,
  PRIMARY KEY (id),
  -- duas pessoas não podem ter o mesmo nome e sobrenome
  CONSTRAINT unq_persons_first_name_last_name UNIQUE (first_name, last_name)
) ENGINE = InnoDB;

INSERT INTO persons (first_name, last_name, age) VALUES
  ('Marie', 'Pélissier', 42),
  ('Jacques', 'Bromard', 35),
  ('Philippe', 'Jandot', 58);
  • Linha 3: o script é escrito em UTF-8; isso é informado ao servidor para que os acentos dos dados ([Pélissier]) permaneçam intactos;
  • linha 5: o conjunto de caracteres [utf8mb4] aceita todos os caracteres (acentos, emojis etc.). A collation [utf8mb4_unicode_ci] compara strings sem distinguir letras maiúsculas de minúsculas nem acentos: para o [MySQL], [pelissier] e [Pélissier] são iguais;
  • linha 11: um número de versão, incrementado a cada modificação da linha (veja “bloqueio otimista”, adiante);
  • linha 17: uma restrição de unicidade nomeada: o banco de dados não permite duas pessoas com o mesmo nome e sobrenome. O nome da restrição será usado para identificar o erro.

9.1.2. A configuração

O arquivo [pom.xml]:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <parent>
    <groupId>course.springmvc</groupId>
    <artifactId>examples</artifactId>
    <version>1.0</version>
  </parent>
  <artifactId>example28</artifactId>

  <dependencies>
    <!-- as views Thymeleaf -->
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-thymeleaf</artifactId>
    </dependency>
    <!-- validação (Bean Validation, Hibernate Validator) -->
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-validation</artifactId>
    </dependency>
    <!-- Spring Data JPA (Hibernate) e o driver JDBC do MySQL -->
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-data-jpa</artifactId>
    </dependency>
    <dependency>
      <groupId>com.mysql</groupId>
      <artifactId>mysql-connector-j</artifactId>
      <scope>runtime</scope>
    </dependency>
  </dependencies>
</project>
  • Linhas 20–23: validação de dados (veja o Capítulo 3);
  • linhas 25–28: [Spring Data JPA], junto com o [Hibernate], o [HikariCP] e o gerenciamento de transações do [Spring];
  • linhas 29–33: o driver [JDBC] do [MySQL]. O escopo [runtime] indica que o código da aplicação não o usa diretamente (ele só conhece o [JPA]): o driver é necessário apenas em tempo de execução. Ele também funciona com o [MariaDB].

O arquivo [application.properties]:

# a porta de escuta do servidor (8080 por padrão)
server.port=5000
# as respostas de erro do Spring Boot não contêm a pilha de chamadas
spring.web.error.include-stacktrace=never
# a sessão (que carrega os atributos flash) é rastreada somente por um cookie
server.servlet.session.tracking-modes=cookie

# a conexão com o banco de dados: URL JDBC, usuário, senha (os do Laragon)
spring.datasource.url=jdbc:mysql://localhost:3306/dbpersons
spring.datasource.username=root
spring.datasource.password=
# o Hibernate não cria nem modifica as tabelas: esse é o papel do script SQL
spring.jpa.hibernate.ddl-auto=none
# a conexão com o banco de dados não é mantida aberta enquanto a view é construída
spring.jpa.open-in-view=false
# true: as instruções SQL enviadas ao banco de dados são exibidas no console
spring.jpa.show-sql=false
  • linha 6: as mensagens de sucesso são enviadas como atributos flash (veja o exemplo 20), armazenados na sessão: o cookie de sessão é suficiente para recuperá-los, sem que o ID da sessão seja adicionado à URL;
  • Linhas 9–11: a conexão com o banco de dados para a fonte de dados ([DataSource]) que o [Spring Boot] cria usando o [HikariCP]: URL [JDBC] (driver, servidor, porta, banco de dados), o nome de usuário e a senha. Esses são os valores padrão do [Laragon] (usuário [root], sem senha). Não é preciso especificar o tipo de banco de dados (nem sua versão): o [Hibernate] solicita essa informação ao servidor na primeira conexão e ajusta o SQL que gera de acordo com ela;
  • linha 13: o [Hibernate] é capaz de criar ou modificar tabelas com base nas entidades; isso é proibido ([none]): o banco de dados é criado pelo script SQL, que serve como referência;
  • linha 15: por padrão, o [Spring Boot] mantém a sessão [JPA] (e sua conexão com o banco de dados) aberta até que a view seja totalmente gerada ([Open Session In View]): uma view poderia então disparar consultas SQL sem que o desenvolvedor percebesse. Esse comportamento é desativado: todas as leituras são feitas pela camada de negócio antes da view. Quando essa propriedade não é especificada, o [Spring Boot] informa isso na inicialização com um aviso ([spring.jpa.open-in-view is enabled by default...]);
  • Linha 17: [true] exibe no console cada comando SQL enviado pelo [Hibernate] (veja a execução abaixo).

O arquivo [messages.properties] contém uma mensagem de erro de conversão (uma idade [abc]), como no exemplo 19. A classe [config/WebConfig.java] serve o [Bootstrap], como nos exemplos anteriores.

9.1.3. A entidade Person

O arquivo [entities/Person.java]:

package example28.entities;

import jakarta.persistence.Column;
import jakarta.persistence.Entity;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.GenerationType;
import jakarta.persistence.Id;
import jakarta.persistence.Table;
import jakarta.persistence.Version;

// uma linha da tabela [persons]
@Entity
@Table(name = "persons")
public class Person {

    // a chave primária, gerada pelo banco de dados (AUTO_INCREMENT); o JPA lê
    // seu valor novamente após cada INSERT
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    @Column(name = "id")
    private Integer id;

    // bloqueio otimista: o JPA incrementa a versão a cada UPDATE e adiciona
    // a condição "AND version = <valor lido>"
    @Version
    @Column(name = "version")
    private Integer version;

    @Column(name = "first_name", length = 30)
    private String firstName;

    @Column(name = "last_name", length = 30)
    private String lastName;

    @Column(name = "age")
    private int age;

    // um construtor sem parâmetros é exigido pelo JPA
    public Person() {
    }

    public Person(String firstName, String lastName, int age) {
        this.firstName = firstName;
        this.lastName = lastName;
        this.age = age;
    }

    public Integer getId() { return id; }

    public Integer getVersion() { return version; }

    public String getFirstName() { return firstName; }
    public void setFirstName(String firstName) { this.firstName = firstName; }

    public String getLastName() { return lastName; }
    public void setLastName(String lastName) { this.lastName = lastName; }

    public int getAge() { return age; }
    public void setAge(int age) { this.age = age; }
}
  • Linha 12: [@Entity] cria uma entidade [JPA] a partir da classe [Person]: cada linha da tabela será um objeto [Person]. As anotações vêm do pacote [jakarta.persistence]: são as do padrão [JPA], e não as do [Hibernate];
  • linha 13: a tabela correspondente (por padrão, seria [Person]);
  • Linhas 18–21: a chave primária ([@Id]). [@GeneratedValue(strategy = GenerationType.IDENTITY)] indica que seu valor é atribuído pelo banco de dados ([AUTO_INCREMENT]): o [Hibernate] lê o valor atribuído após cada [INSERT]. O tipo [Integer], e não [int], permite o valor [null]: uma pessoa que ainda não foi cadastrada não tem ID. [@Column] especifica o nome da coluna correspondente a cada campo;
  • linhas 25–27: a coluna de versão. [@Version] atribui o bloqueio otimista ao [Hibernate]: ele define a versão como 0 durante o [INSERT], aumenta-a em 1 a cada [UPDATE] e adiciona a condição [AND version = <value read>] a cada [UPDATE] (e a cada [DELETE]). Veremos mais adiante para que isso serve;
  • linhas 29–36: as demais colunas. [length] especifica a largura da coluna: só seria relevante se o [Hibernate] criasse a tabela por conta própria, o que não é o caso aqui (veja [ddl-auto]);
  • linhas 39–40: o [JPA] exige um construtor sem parâmetros: é o que o [Hibernate] usa para criar um objeto a partir de uma linha lida, antes de preencher seus campos;
  • linhas 48–59: os acessores (métodos [getX] e [setX]): a entidade é um JavaBean. Não há [setId] nem [setVersion]: esses dois valores são escritos apenas pelo [Hibernate], que acessa os campos diretamente.

9.1.4. A camada DAO

O arquivo [dao/PersonsDao.java]:

package example28.dao;

import java.util.List;
import java.util.Optional;

import org.springframework.data.jpa.repository.JpaRepository;

import example28.entities.Person;

// a camada DAO: consultas, sem regra de negócio.
// Uma interface, que o Spring Data JPA IMPLEMENTA ele mesmo na inicialização.
// JpaRepository<Person, Integer> já traz findById, save, deleteById...
public interface PersonsDao extends JpaRepository<Person, Integer> {

    // o nome do método descreve a consulta:
    // SELECT ... FROM persons ORDER BY last_name, first_name
    List<Person> findAllByOrderByLastNameAscFirstNameAsc();

    // uma pessoa com os mesmos nome e sobrenome, diferente de [exceptId]:
    // SELECT ... WHERE first_name = ? AND last_name = ? AND id <> ? LIMIT 1
    Optional<Person> findFirstByFirstNameAndLastNameAndIdNot(String firstName, String lastName, Integer exceptId);
}

Esta é toda a camada DAO: uma interface, sem uma única linha de código executável.

  • Linha 13: a interface herda de [JpaRepository<Person, Integer>] (uma entidade [Person], cuja chave é um [Integer]). Na inicialização, o [Spring Data JPA] cria uma classe que implementa essa interface e a transforma em um bean, que é então injetado. [JpaRepository] já fornece os métodos padrão: [findById] (leitura pela chave, resultado em um [Optional]), [findAll], [save] ([INSERT] ou [UPDATE]), [saveAndFlush], [deleteById], [count]... ;
  • Linha 17: uma consulta derivada: [Spring Data JPA] analisa o nome do método e deriva a consulta a partir dele. [findAll]: todas as pessoas; [By]: sem condições, já que nada o segue; [OrderByLastNameAscFirstNameAsc]: ordenadas por sobrenome e depois por nome, em ordem crescente;
  • linha 21: [findFirst]: a primeira pessoa encontrada ([LIMIT 1]), ou um [Optional] vazio; [ByFirstNameAndLastNameAndIdNot]: cujo nome e sobrenome correspondem aos fornecidos como parâmetros e cujo ID é diferente do terceiro parâmetro. Isso é útil ao modificar um registro, que não deve entrar em conflito consigo mesmo. A comparação é feita pelo [MySQL] e, portanto, segue as regras de collation do banco de dados: ignora maiúsculas e acentos.

Um erro em um nome de método ([findAllByOrderByLastNamee]) é detectado na inicialização: a aplicação se recusa a iniciar, informando uma propriedade desconhecida. Uma consulta complexa demais para um nome de método é escrita na linguagem [JPQL] ([Jakarta Persistence Query Language], um SQL que se refere a entidades e seus campos, e não a tabelas), em uma anotação [@Query]: o estudo de caso usa algumas delas.

9.1.5. A camada de negócio

O arquivo [business/BusinessException.java]:

1
2
3
4
5
6
7
8
9
package example28.business;

// uma regra de negócio rejeita a operação: a mensagem se destina ao usuário
public class BusinessException extends RuntimeException {

    public BusinessException(String message) {
        super(message);
    }
}

Uma [BusinessException] indica que uma regra de negócio está rejeitando uma operação. Não se trata de um erro de programa: sua mensagem se destina ao usuário. Ela herda de [RuntimeException]: é uma exceção não verificada (unchecked), que um método pode lançar sem declará-la ([throws]). Veremos que essa escolha também se aplica às transações.

O arquivo [business/PersonData.java]:

1
2
3
4
5
package example28.business;

// os dados de uma pessoa, como a camada web os repassa
public record PersonData(String firstName, String lastName, int age) {
}

Os dados de uma pessoa, como transmitidos pela camada web: a camada de negócio não conhece a classe do formulário.

O arquivo [business/PersonsBusiness.java]:

package example28.business;

import java.util.List;
import java.util.Objects;

import org.springframework.dao.DataIntegrityViolationException;
import org.springframework.orm.ObjectOptimisticLockingFailureException;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

import example28.dao.PersonsDao;
import example28.entities.Person;

// a camada de NEGÓCIO: as regras de negócio, e somente elas.
// @Transactional na classe: cada método público é executado dentro de uma
// transação, confirmada (COMMIT) ao final do método, cancelada (ROLLBACK) se
// ele lançar uma exceção
@Service
@Transactional
public class PersonsBusiness {

    private static final String NAMESAKE = "A person already has these first and last names.";
    private static final String MODIFIED = "This record has been modified meanwhile: reload it.";

    private final PersonsDao dao;

    public PersonsBusiness(PersonsDao dao) {
        this.dao = dao;
    }

    // readOnly: uma transação somente leitura
    @Transactional(readOnly = true)
    public List<Person> list() {
        return dao.findAllByOrderByLastNameAscFirstNameAsc();
    }

    @Transactional(readOnly = true)
    public Person read(int id) {
        return dao.findById(id).orElseThrow(() -> new BusinessException("This person does not exist (anymore)."));
    }

    public Person add(PersonData data) {
        // regra 1: não pode haver duas pessoas com os mesmos nome e sobrenome
        if (dao.findFirstByFirstNameAndLastNameAndIdNot(data.firstName(), data.lastName(), 0).isPresent()) {
            throw new BusinessException(NAMESAKE);
        }
        return save(new Person(data.firstName(), data.lastName(), data.age()));
    }

    public Person edit(int id, Integer version, PersonData data) {
        Person person = read(id);
        // regra 2: não modificamos um registro modificado nesse meio-tempo por outra pessoa
        if (!Objects.equals(person.getVersion(), version)) {
            throw new BusinessException(MODIFIED);
        }
        if (dao.findFirstByFirstNameAndLastNameAndIdNot(data.firstName(), data.lastName(), id).isPresent()) {
            throw new BusinessException(NAMESAKE);
        }
        // a entidade lida é "rastreada" pelo JPA: modificá-la basta
        person.setFirstName(data.firstName());
        person.setLastName(data.lastName());
        person.setAge(data.age());
        return save(person);
    }

    public Person delete(int id) {
        Person person = read(id);
        dao.deleteById(id);
        return person;
    }

    // saveAndFlush: INSERT ou UPDATE enviado IMEDIATAMENTE ao banco de dados (e não no
    // COMMIT), para poder capturar os erros do banco de dados aqui
    private Person save(Person person) {
        try {
            return dao.saveAndFlush(person);
        } catch (ObjectOptimisticLockingFailureException e) {
            // o UPDATE "WHERE id = ... AND version = ..." não modificou nenhuma linha
            throw new BusinessException(MODIFIED);
        } catch (DataIntegrityViolationException e) {
            // duas adições simultâneas: a restrição de unicidade do banco de dados rejeitou a segunda
            if (String.valueOf(e.getMostSpecificCause().getMessage()).contains("unq_persons_first_name_last_name")) {
                throw new BusinessException(NAMESAKE);
            }
            throw e;
        }
    }
}

Vamos comentar este código:

  • linha 18: a camada de negócio é um bean de serviço;
  • linha 19: [@Transactional], associada à classe, aplica-se a cada um de seus métodos públicos: o método é executado dentro de uma transação que é aberta ([START TRANSACTION]) antes de sua chamada, confirmada ([COMMIT]) no retorno e desfeita ([ROLLBACK]) se lançar uma exceção não verificada. Como acontece com [@PreAuthorize] (exemplo 26), o [Spring] envolve o bean em um proxy, que abre e fecha a transação em torno da chamada. Tudo o que o método faz, inclusive as chamadas ao DAO, ocorre dentro da mesma transação e na mesma conexão;
  • linhas 32–35: [readOnly = true]: uma transação somente leitura, que dispensa o [Hibernate] de verificar, no final, se há entidades modificadas;
  • linhas 37–40: uma pessoa ausente é uma [BusinessException]. [orElseThrow] retorna o conteúdo do [Optional] ou lança a exceção gerada pela lambda se ele estiver vazio;
  • linhas 42–48: a inclusão. Regra: não pode haver duas pessoas com o mesmo nome e sobrenome. Isso é verificado antes da gravação, para exibir uma mensagem clara. Nenhuma pessoa tem o ID 0: [IdNot] não exclui ninguém da busca aqui;
  • linhas 50–64: a atualização. Regra adicional: o bloqueio otimista (linhas 53–55). O formulário de atualização usa a versão do registro como ela era quando o formulário foi aberto. Se ela mudou nesse meio-tempo (outro usuário editou o mesmo registro), a atualização é rejeitada em vez de sobrescrever silenciosamente o trabalho desse usuário. [Objects.equals] compara duas [Integer] instâncias aceitando [null];
  • Linha 51: a chamada a [read] é uma chamada interna à classe: ela não passa pelo proxy, e o seu [readOnly] não se aplica. [read] simplesmente é executado dentro da transação de [edit];
  • linhas 60–63: a entidade lida na transação é acompanhada pelo [Hibernate] (diz-se que ela é “gerenciada”): basta modificar seus campos; o [Hibernate] detecta as alterações e gera um [UPDATE] para as colunas da tabela;
  • Linhas 66–70: a exclusão. A pessoa é lida primeiro, para verificar que ela existe e para que o controller possa mencionar seu nome;
  • Linhas 74–87: a gravação. Normalmente, o [Hibernate] envia os comandos [INSERT] e [UPDATE] ao banco de dados apenas no fim da transação, no [COMMIT], ou seja, depois de sair do método: um erro do banco de dados não poderia mais ser interceptado aqui. [saveAndFlush] salva a entidade e envia imediatamente ([flush]) os comandos SQL pendentes;
  • Linhas 77–79: a verificação de versão mencionada antes nem sempre é suficiente: dois usuários podem salvar o mesmo registro ao mesmo tempo, e ambos passam na verificação. O [UPDATE ... WHERE id = ? AND version = ?] do segundo usuário então não modifica nenhuma linha; o [Hibernate] detecta isso, e o [Spring] lança uma [ObjectOptimisticLockingFailureException], que se torna a mesma [BusinessException];
  • linhas 80–85: da mesma forma, duas inclusões simultâneas da mesma pessoa passam pela verificação de homônimos, mas a restrição de unicidade do banco de dados não permite que ambas sejam aceitas. O [Spring] traduz as exceções dos diversos bancos de dados e dos diversos ORMs em uma hierarquia comum de exceções: uma violação de restrição se torna uma [DataIntegrityViolationException]. [getMostSpecificCause()] retorna a exceção original, a do driver do [MySQL], cuja mensagem especifica o nome da restrição ([Duplicate entry '...' for key 'unq_persons_first_name_last_name']). Qualquer outra violação de restrição segue adiante (linha 85): trata-se de uma anomalia.

Em todos os casos em que uma exceção sai de um método de [PersonsBusiness] (inclusive [BusinessException], já que ela herda de [RuntimeException]), o proxy desfaz a transação: nenhuma das ações do método é mantida. Observação: por padrão, uma exceção verificada (checked, que herda de [Exception] sem herdar de [RuntimeException]) não provoca um rollback.

Verificamos esse último caso enviando 30 requisições para adicionar a mesma pessoa ao mesmo tempo: apenas uma foi aceita; para as demais, o banco de dados rejeitou o [INSERT] (erro [MySQL] nº 1062, que o [Hibernate] informa no console como um aviso [HHH000247]), e o usuário recebeu a mensagem de "homônimo", e não um erro 500.

9.1.6. A camada web

O arquivo [models/PersonForm.java]:

package example28.models;

import jakarta.validation.constraints.Max;
import jakarta.validation.constraints.Min;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.NotNull;
import jakarta.validation.constraints.Size;

// os campos do formulário e suas restrições (veja o exemplo 19)
public class PersonForm {

    @NotBlank(message = "The first name is required.")
    @Size(max = 30, message = "30 characters at most.")
    private String firstName;

    @NotBlank(message = "The last name is required.")
    @Size(max = 30, message = "30 characters at most.")
    private String lastName;

    @NotNull(message = "The age is required.")
    @Min(value = 0, message = "The age must be between 0 and 150.")
    @Max(value = 150, message = "The age must be between 0 and 150.")
    private Integer age;

    // a versão do registro, carregada por um campo oculto (somente na edição)
    private Integer version;

    public String getFirstName() { return firstName; }
    public void setFirstName(String firstName) { this.firstName = firstName; }

    public String getLastName() { return lastName; }
    public void setLastName(String lastName) { this.lastName = lastName; }

    public Integer getAge() { return age; }
    public void setAge(Integer age) { this.age = age; }

    public Integer getVersion() { return version; }
    public void setVersion(Integer version) { this.version = version; }
}

O formulário e suas restrições de validação (veja o exemplo 19), com a versão do registro (linha 26) transmitida por um campo oculto. A idade é um [Integer] e não um [int]: um campo vazio resulta em [null], o que é indicado por [@NotNull].

O arquivo [controllers/PersonsController.java]:

package example28.controllers;

import org.springframework.beans.propertyeditors.StringTrimmerEditor;
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.validation.BindingResult;
import org.springframework.web.bind.WebDataBinder;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.InitBinder;
import org.springframework.web.bind.annotation.ModelAttribute;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.servlet.mvc.support.RedirectAttributes;

import example28.entities.Person;
import example28.business.PersonData;
import example28.business.BusinessException;
import example28.business.PersonsBusiness;
import example28.models.PersonForm;
import jakarta.validation.Valid;

// a camada WEB: ela conhece apenas a camada de negócio
@Controller
public class PersonsController {

    private final PersonsBusiness business;

    public PersonsController(PersonsBusiness business) {
        this.business = business;
    }

    // as strings recebidas têm os espaços supérfluos removidos (veja o exemplo 19)
    @InitBinder
    public void initBinder(WebDataBinder binder) {
        binder.registerCustomEditor(String.class, new StringTrimmerEditor(true));
    }

    @GetMapping("/")
    public String home() {
        return "redirect:/persons";
    }

    @GetMapping("/persons")
    public String list(Model model) {
        model.addAttribute("persons", business.list());
        return "persons/list";
    }

    @GetMapping("/persons/add")
    public String addForm(Model model) {
        return form(model, "Add a person", "/persons/add", new PersonForm(), null);
    }

    @PostMapping("/persons/add")
    public String add(@Valid @ModelAttribute("person") PersonForm input, BindingResult result,
            Model model, RedirectAttributes redirect) {
        if (result.hasErrors()) {
            return form(model, "Add a person", "/persons/add", input, null);
        }
        try {
            Person p = business.add(new PersonData(input.getFirstName(), input.getLastName(), input.getAge()));
            redirect.addFlashAttribute("success", p.getFirstName() + " " + p.getLastName() + " has been added.");
            return "redirect:/persons";
        } catch (BusinessException e) {
            // uma regra de negócio recusa: exibimos o formulário novamente, com a mensagem no pé da página
            return form(model, "Add a person", "/persons/add", input, e.getMessage());
        }
    }

    @GetMapping("/persons/{id:\\d+}/edit")
    public String editForm(@PathVariable int id, Model model, RedirectAttributes redirect) {
        try {
            Person p = business.read(id);
            PersonForm values = new PersonForm();
            values.setFirstName(p.getFirstName());
            values.setLastName(p.getLastName());
            values.setAge(p.getAge());
            values.setVersion(p.getVersion());
            return form(model, "Edit a person", "/persons/" + id + "/edit", values, null);
        } catch (BusinessException e) {
            redirect.addFlashAttribute("error", e.getMessage());
            return "redirect:/persons";
        }
    }

    @PostMapping("/persons/{id:\\d+}/edit")
    public String edit(@PathVariable int id, @Valid @ModelAttribute("person") PersonForm input,
            BindingResult result, Model model, RedirectAttributes redirect) {
        String action = "/persons/" + id + "/edit";
        if (result.hasErrors()) {
            return form(model, "Edit a person", action, input, null);
        }
        try {
            PersonData data = new PersonData(input.getFirstName(), input.getLastName(), input.getAge());
            Person p = business.edit(id, input.getVersion(), data);
            redirect.addFlashAttribute("success", p.getFirstName() + " " + p.getLastName() + " has been edited.");
            return "redirect:/persons";
        } catch (BusinessException e) {
            return form(model, "Edit a person", action, input, e.getMessage());
        }
    }

    @PostMapping("/persons/{id:\\d+}/delete")
    public String delete(@PathVariable int id, RedirectAttributes redirect) {
        try {
            Person p = business.delete(id);
            redirect.addFlashAttribute("success", p.getFirstName() + " " + p.getLastName() + " has been deleted.");
        } catch (BusinessException e) {
            // nenhum formulário a exibir novamente: o erro também viaja como atributo flash
            redirect.addFlashAttribute("error", e.getMessage());
        }
        return "redirect:/persons";
    }

    // o modelo da view do formulário: título, endereço de envio, valores, erro global
    private String form(Model model, String title, String action, PersonForm values, String error) {
        model.addAttribute("title", title);
        model.addAttribute("action", action);
        model.addAttribute("person", values);
        model.addAttribute("error", error);
        return "persons/form";
    }
}

Vamos analisar este código:

  • linhas 26–30: o controller conhece apenas a camada de negócio;
  • linhas 33–36: as strings recebidas têm os espaços iniciais e finais removidos, e uma string vazia se torna [null] (veja o exemplo 19);
  • linhas 38–41: a raiz do site redireciona para a lista;
  • linhas 54–68: a inclusão, em três etapas: validação do formulário (erros: recarrega), chamada à camada de negócio (sucesso: mensagem flash e redirecionamento; veja o exemplo 20), [BusinessException] (recarrega com a mensagem no final da página). Qualquer outra exceção não é capturada: trata-se de uma anomalia que resultará em um erro 500;
  • Linha 70: [{id:\\d+}]: uma variável de caminho restringida por uma expressão regular (veja o exemplo 02): [\d+] designa uma sequência de dígitos (a barra invertida é duplicada na string [Java]). [/persons/abc/edit] não corresponde a nenhuma ação: erro 404;
  • linhas 70–84: o formulário de atualização, preenchido previamente com o registro lido do banco de dados, inclusive sua versão;
  • linhas 86–101: mesma estrutura da inclusão; a versão devolvida pelo formulário é transmitida à camada de negócio;
  • linhas 103–113: a exclusão. Não há formulário a reexibir: os eventuais erros também são transmitidos por meio do atributo flash;
  • linhas 116–122: o template da view do formulário, usado tanto para incluir quanto para modificar registros: título e endereço de envio diferentes, valores do formulário e erro da camada de negócio.

O arquivo [templates/persons/form.html]:

<!doctype html>
<html xmlns:th="http://www.thymeleaf.org" th:replace="~{layout :: page(~{::main})}">
<body>
<main>
  <h1 class="h3" th:text="${title}">Add a person</h1>
  <form method="post" th:action="${action}" th:object="${person}" novalidate>
    <!--/* a versão do registro lido: ela voltará com o formulário */-->
    <input type="hidden" th:field="*{version}">
    <div th:replace="~{fragments/field :: field(name='firstName', label='First name', type='text')}"></div>
    <div th:replace="~{fragments/field :: field(name='lastName', label='Last name', type='text')}"></div>
    <div th:replace="~{fragments/field :: field(name='age', label='Age', type='number')}"></div>
    <button class="btn btn-primary" type="submit">Save</button>
    <a class="btn btn-link" href="/persons">Cancel</a>
  </form>
</main>
</body>
</html>
  • Linha 6: [th:object] identifica o objeto do formulário; [th:action] recebe o endereço de envio fornecido pelo controller;
  • linha 8: o campo oculto que transporta a versão do registro: [th:field="*{version}"] gera seus atributos [name] e [value] (veja o exemplo 19);
  • Linhas 9–11: os três campos gerados pelo fragmento [field] do exemplo 19.

O arquivo [templates/layout.html]:

<!doctype html>
<html lang="en" xmlns:th="http://www.thymeleaf.org" th:fragment="page(content)">
<head>
  <meta charset="utf-8">
  <title>Persons</title>
  <link rel="stylesheet" href="/bootstrap/css/bootstrap.min.css">
  <link rel="stylesheet" href="/css/styles.css">
</head>
<body>
  <div class="container py-3" style="max-width: 40rem">
    <!--/* a mensagem de sucesso (atributo flash, após um redirecionamento): no topo */-->
    <div class="alert alert-success" role="status" th:if="${success != null}" th:text="${success}">success</div>
    <main th:replace="${content}"></main>
    <!--/* o erro: da requisição atual, ou de antes do redirecionamento (atributo flash) */-->
    <div class="error-area" role="alert" th:if="${error != null}" th:text="${error}">error</div>
  </div>
  <div th:replace="~{fragments/confirmation :: confirmation}"></div>
  <script src="/js/app.js"></script>
</body>
</html>
  • linha 12: a mensagem de sucesso, no topo da página;
  • linha 15: a mensagem de erro no final da página: ou a da requisição atual (colocada no template por [form]) ou a armazenada como atributo flash antes de um redirecionamento. Em ambos os casos, trata-se de um atributo [error] do template da view;
  • linhas 17–18: a janela de confirmação e seu script (veja o exemplo 21).

A view [persons/list.html] tem a mesma estrutura da lista de contatos do exemplo 21: para cada pessoa, um link para o formulário de edição e um formulário de exclusão POST, cujo envio é confirmado. O fragmento [fragments/field.html] é o mesmo do exemplo 19, enquanto a janela [fragments/confirmation.html] e o script [static/js/app.js] são os mesmos do exemplo 21, sem alterações.

9.1.7. Execução

Se os valores de [application.properties] não forem adequados (uma senha para [root], por exemplo), eles podem ser substituídos, sem modificar o arquivo, por variáveis de ambiente: o nome da propriedade é escrito em maiúsculas, com os pontos substituídos por sublinhados. No [Windows] ([PowerShell]):

$env:SPRING_DATASOURCE_PASSWORD="secret"; ..\mvnw spring-boot:run

Na inicialização, com o [MariaDB], o [Hibernate] exibe um aviso:

... WARN ... org.hibernate.orm.core : HHH000511: The 5.5.5 version for [org.hibernate.dialect.MySQLDialect] is no longer supported, hence certain features may not work properly.The minimum supported version is 8.0.0. Check the community dialects project for available legacy versions.

Isso não tem consequências: o [MariaDB] se apresenta ao driver do [MySQL] com o número de versão “5.5.5”, que o [Hibernate] interpreta como um [MySQL] muito antigo. Com o [MySQL] 8, ele não aparece.

A lista, na URLhttp://localhost:5000/:

Image

Um formulário inválido:

Image

Um homônimo: a regra de negócio o detecta. [MySQL], ao comparar usando a collation do banco de dados, rejeita também [marie pelissier], escrito em minúsculas e sem acentos. Aqui, a entrada [Marie Pélissier]:

Image

Uma inclusão bem-sucedida:

Image

Com [spring.jpa.show-sql=true] em [application.properties] (ou, sem modificar o arquivo, [../mvnw spring-boot:run -Dspring-boot.run.arguments=--spring.jpa.show-sql=true]), o console exibe cada comando SQL enviado pelo [Hibernate]. Para adicionar uma pessoa e depois exibir a lista após o redirecionamento:

1
2
3
Hibernate: select p1_0.id,p1_0.age,p1_0.first_name,p1_0.last_name,p1_0.version from persons p1_0 where p1_0.first_name=? and p1_0.last_name=? and p1_0.id<>? limit ?
Hibernate: insert into persons (age,first_name,last_name,version) values (?,?,?,?)
Hibernate: select p1_0.id,p1_0.age,p1_0.first_name,p1_0.last_name,p1_0.version from persons p1_0 order by p1_0.last_name,p1_0.first_name

Aqui vemos a busca por um homônimo (a consulta derivada do nome [findFirstByFirstNameAndLastNameAndIdNot]), o [INSERT] e, em seguida, a leitura da lista ([findAllByOrderByLastNameAscFirstNameAsc]). Os valores são passados separadamente como parâmetros (os [?]): é isso que protege contra injeções de SQL. Os comandos de transação ([START TRANSACTION], [COMMIT]) não são exibidos. Para modificar um registro:

1
2
3
Hibernate: select p1_0.id,p1_0.age,p1_0.first_name,p1_0.last_name,p1_0.version from persons p1_0 where p1_0.id=?
Hibernate: select p1_0.id,p1_0.age,p1_0.first_name,p1_0.last_name,p1_0.version from persons p1_0 where p1_0.first_name=? and p1_0.last_name=? and p1_0.id<>? limit ?
Hibernate: update persons set age=?,first_name=?,last_name=?,version=? where id=? and version=?

[UPDATE] grava a nova versão e verifica a antiga ([where id=? and version=?]): este é o bloqueio otimista. E para uma exclusão:

Hibernate: select p1_0.id,p1_0.age,p1_0.first_name,p1_0.last_name,p1_0.version from persons p1_0 where p1_0.id=?
Hibernate: delete from persons where id=? and version=?

[deleteById] não releu o registro: ele já era acompanhado na transação desde a chamada a [read].

O bloqueio otimista: dois formulários estão abertos sobre o mesmo registro; o primeiro é salvo (a versão passa de 0 para 1); o segundo, que ainda tem a versão 0, é rejeitado:

Image

Exclusão, com confirmação:

Image

Image