Programação para Web II

Em um projeto Maven com o parent ou BOM do Spring Boot 4, adicione o starter de persistência e o driver JDBC do MySQL:

O starter reúne Spring Data JPA, Hibernate ORM e a infraestrutura JDBC. Mesmo antes de usar interfaces do Spring Data, podemos trabalhar diretamente com o EntityManager.

As versões devem acompanhar o gerenciamento de dependências do Spring Boot 4. Use com.mysql:mysql-connector-j, sem fixar uma versão diferente da gerenciada pelo BOM. Consulte a documentação do Connector/J. Esse driver é JDBC, não R2DBC.

Uma entidade é uma classe anotada com @Entity, com identificador e construtor sem argumentos público ou protegido. Para portabilidade em JPA 3.2, a classe e seus membros persistentes não devem ser final.

O Long permite representar um identificador ainda não atribuído por null. GenerationType.IDENTITY utiliza a coluna de identidade do banco, como o AUTO_INCREMENT do MySQL. @GeneratedValue também admite SEQUENCE, TABLE, AUTO e UUID (para identificadores UUID ou String); portanto, a anotação, isoladamente, não significa auto incremento.

@Table explicita a tabela. Sem ela, o nome lógico padrão é o nome da entidade, mas a estratégia de nomes físicos do provedor ou do Spring Boot pode transformar esse nome. Como @Id está no campo, os exemplos usam acesso aos campos: o provedor não depende dos getters e setters para persistir os atributos.

Implementar Serializable não é uma exigência geral de uma entidade. Essa interface é necessária em cenários que exigem serialização da instância, como sua passagem por valor em uma interface remota.

Configure a conexão em src/main/resources/application.properties. Crie previamente o banco pwebii e um usuário com acesso a ele. Defina as variáveis de ambiente DB_USER e DB_PASSWORD antes de iniciar a aplicação.

url, username e password identificam o banco e as credenciais. show-sql exibe comandos SQL e format_sql facilita sua leitura.

A propriedade ddl-auto controla a interação do Hibernate com o esquema:

update é conveniente para exercícios, mas não substitui um histórico de migrações. Em uma aplicação publicada, prefira migrações com Flyway ou Liquibase e uma escolha explícita de none ou validate. Consulte a documentação de inicialização do banco no Spring Boot.

O escopo determina quando uma instância de bean é criada e compartilhada:

Os quatro últimos escopos exigem um contexto web adequado. Um bean prototype injetado diretamente em um singleton é resolvido na criação desse singleton; isso não produz uma nova instância a cada chamada de método.

Controllers e repositórios singleton devem evitar campos mutáveis com dados de usuários ou requisições. A injeção de EntityManager gerenciada pelo Spring usa um proxy; não significa que um único EntityManager real possa ser compartilhado livremente entre threads.

Referência: escopos de beans no Spring Framework.

A classe PessoaRepository concentra o acesso aos dados. As operações de escrita usam transações; consultas são marcadas como somente leitura.

@Repository identifica um componente de acesso a dados e permite sua participação na tradução de exceções de persistência do Spring. @PersistenceContext fornece o acesso ao contexto de persistência.

A consulta usa JPQL: Pessoa e nome são a entidade e o atributo Java, não a tabela tb_pessoa e suas colunas. Informar Pessoa.class cria uma consulta tipada e evita conversões de uma lista sem tipo.

O método save() acima insere entidades novas; update() demonstra merge(). Esses nomes são escolhas desta classe e não possuem automaticamente o comportamento dos métodos do Spring Data JPA.

A injeção por construtor deixa explícita a dependência obrigatória do controller e permite armazená-la em um campo final. Quando há apenas um construtor, o Spring o utiliza automaticamente, sem exigir @Autowired. Este é o padrão adotado nos exemplos de controllers e serviços deste material, conforme a documentação de injeção de dependências e a regra de seleção do construtor.

O template src/main/resources/templates/pessoas/list.html recebe a coleção pessoas. As transações deste exemplo ficam no repositório. Quando uma operação de negócio envolve várias chamadas, delimite a transação em um serviço, como veremos no tópico de Spring Data JPA.

@Transactional funciona por interceptação das chamadas ao bean. Na configuração padrão por proxy, chamar um método anotado a partir de outro método da mesma instância não inicia uma nova interceptação. Por padrão, RuntimeException e Error provocam rollback; exceções verificadas exigem configuração quando também devem provocá-lo. readOnly = true é uma indicação de otimização, não um bloqueio universal de escrita.

Referência: transações declarativas no Spring.

No exemplo, cada pessoa possui um endereço obrigatório, e um endereço pode estar vinculado a, no máximo, uma pessoa. As entidades ocupam tabelas distintas. A chave estrangeira fica em tb_pessoa.id_endereco, com restrição de unicidade.

optional = false declara que a referência é obrigatória; nullable = false e unique = true descrevem as restrições da coluna. Como não configuramos cascata, associe uma instância de Endereco já persistida ou persista o endereço antes da pessoa, na mesma transação.

Um objeto de valor que deva compartilhar a tabela da pessoa pode ser modelado com @Embeddable e @Embedded, em vez desta associação entre entidades.

Agora uma pessoa pode possuir zero ou vários endereços, e cada endereço pertence a uma pessoa. Substitua o mapeamento anterior: a chave estrangeira passa para tb_endereco.id_pessoa.

O lado @ManyToOne é o proprietário desta associação. O método auxiliar mantém as referências consistentes ao adicionar um novo endereço; uma transferência entre pessoas também deve retirar o endereço da coleção anterior.

Sem cascata, persistir Pessoa não persiste automaticamente seus novos endereços. Na mesma transação, persista a pessoa, associe os endereços e persista cada um deles.

@OneToMany também admite mapeamento unidirecional; o uso de mappedBy neste exemplo decorre da escolha bidirecional. Referência: API de OneToMany.

Nesta alternativa, pessoas podem compartilhar endereços, e cada pessoa pode ter vários endereços. Uma tabela intermediária registra os pares de identificadores.

joinColumns identifica a referência ao proprietário, Pessoa; inverseJoinColumns identifica a referência a Endereco. A restrição composta impede repetir o mesmo par no banco.

O Set evita duplicatas conforme equals() e hashCode(). Ao implementá-los em entidades, não use associações nem atributos mutáveis que alterem o hash enquanto o objeto estiver na coleção.

Se a relação precisar de atributos próprios, como “data de início da residência”, modele uma entidade associativa com duas relações @ManyToOne. Referência: API de ManyToMany.

Em SINGLE_TABLE, uma coluna discriminadora identifica a subclasse de cada registro. É a estratégia padrão quando uma hierarquia de entidades não declara outra estratégia.

A tabela tb_pessoa contém id, nome, tipo, cpf e cnpj. Em um registro do tipo F, cnpj não se aplica; em um registro do tipo J, cpf não se aplica. Por isso, uma restrição NOT NULL incondicional nessas colunas específicas não representa corretamente essa modelagem. Campos comuns, como nome, ainda podem ser obrigatórios.

Em JOINED, os campos comuns ficam na tabela da raiz, e os específicos ficam nas tabelas das subclasses. O identificador da subclasse também referencia o registro da raiz.

Uma pessoa física ocupa uma linha em tb_pessoa e outra em tb_pessoafisica, ligadas pelo identificador. As subclasses herdam @Id; não declaram uma nova identidade. Nesta alternativa, retire os discriminadores do exemplo SINGLE_TABLE.

Em TABLE_PER_CLASS, cada tabela concreta reúne os campos próprios e herdados. Como Pessoa é abstrata, neste exemplo não há uma tabela para instâncias diretas dela.

O gerador em tabela compartilha a geração de IDs da hierarquia e funciona com o MySQL deste exemplo. No Hibernate, IDENTITY não é suportado nessa estratégia. TABLE exige acesso adicional à tabela geradora; bancos com sequências permitem avaliar SEQUENCE como alternativa.

Retire @PrimaryKeyJoinColumn das subclasses nesta alternativa: os campos herdados ficam em cada tabela concreta, sem uma tabela raiz para a junção. O suporte a TABLE_PER_CLASS é opcional na especificação JPA 3.2, embora seja oferecido pelo Hibernate.

Referências: API de Inheritance e herança no Hibernate ORM.

Substitua a classe manual PessoaRepository pela interface abaixo. Elas são duas alternativas de implementação, não devem coexistir com o mesmo nome.

Pessoa é o tipo da entidade e Long é o tipo de sua chave. Coloque a interface no pacote da aplicação ou em um subpacote para que a configuração automática a encontre. Não é necessário implementar seus métodos nem adicionar @Repository à interface neste caso.

Ao estender JpaRepository, a interface já recebe os métodos básicos de acesso aos dados. Você não precisa declará-los novamente: o Spring Data JPA fornece a implementação em tempo de execução. O método findByNome, declarado no exemplo, acrescenta uma busca específica da nossa aplicação.

No controller anterior, troque repository.pessoas() por repository.findAll(). O nome save() agora segue o contrato do Spring Data, diferente do método manual que apenas chamava persist().

Referência: API de JpaRepository.

Para buscar pessoas pelo nome, declaramos apenas a assinatura do método:

O Spring Data JPA interpreta o nome do método para criar a consulta. Esse recurso é chamado de consulta derivada:

Por exemplo, em um método de serviço ou controller que já recebeu o repositório por construtor:

Importe java.util.List na classe que faz a chamada. A consulta procura o nome informado, em vez de um trecho dele. A diferenciação entre maiúsculas, minúsculas e acentos depende das regras de comparação do banco de dados.

Não é necessário escrever SQL, usar @Query ou criar uma classe que implemente essa interface para realizar essa busca. O nome após findBy deve corresponder a um atributo existente na entidade. Os métodos herdados, como findAll() e save(), continuam disponíveis normalmente.

Referência: Spring Data JPA — consultas derivadas dos nomes dos métodos.

Podemos combinar atributos de Pessoa com palavras-chave para declarar outras buscas. Os métodos abaixo retornam List<Pessoa> e devem ser declarados na interface para serem utilizados.

Asc indica ordem crescente; Desc, decrescente. Métodos sem OrderBy ou ordenação explícita não garantem a ordem dos resultados.

Na última chamada, as duas condições devem ser atendidas. Os parâmetros seguem a ordem dos atributos no nome do método. Não redeclare os métodos herdados da tabela anterior.

Referência: Spring Data JPA — Query Creation.

A anotação @Query, colocada acima do método, permite escrever a consulta diretamente na interface. Neste exemplo, acrescentamos uma busca pelo nome à mesma PessoaRepository; mantenha os métodos anteriores.

Mantenha também o import de java.util.List. A consulta usa JPQL, que trabalha com entidades e atributos Java:

Para esse argumento, a busca equivale à de findByNome("Ana"). Com @Query, a consulta está na anotação; o nome buscarPorNome não precisa seguir a convenção findBy. Os métodos herdados continuam disponíveis.

Referência: Spring Data JPA — Using @Query e Using Named Parameters.

O índice da primeira página é zero. Ordenar também por id desempata nomes iguais. Page oferece totais, podendo executar uma consulta de contagem; Slice é uma alternativa em métodos de consulta quando basta saber se há uma próxima parte.

Um serviço define a unidade de trabalho. Neste exemplo, buscamos a pessoa e alteramos seu nome dentro da mesma transação:

A entidade obtida permanece gerenciada na transação; o Hibernate detecta a alteração sem exigir outro save(). O controller deve receber e chamar o serviço para executar essa operação. Valide novoNome conforme as regras da aplicação antes de atribuí-lo.

As operações CRUD herdadas possuem configuração transacional. Métodos de consulta declarados na interface não recebem automaticamente a mesma configuração; para operações de leitura que exijam um limite transacional, use um serviço com @Transactional(readOnly = true).

Referência: transações no Spring Data JPA.