Category Archives: Spring Data

Spring Data JPA Avançado – Epecificações e queryDSL

Neste post eu gostaria de mergulhar dentro de alguns recursos e como eles poderiam lhe ajudar a simplificar a implementação da camada de acesso a dados ainda mais. A abstração do repositório Spring Data consiste de um modelo de programação baseado em interface, algumas classes de fábrica e um Spring namespace para facilmente configurar a infraestrutura. Uma interface de repositório típica se parece com isso:

public interface CustomerRepository extends JpaRepository<Customer, Long> {

Customer findByEmailAddress(String emailAddress);
List<Customer> findByLastname(String lastname, Sort sort);
Page<Customer> findByFirstname(String firstname, Pageable pageable);

}

O primeiro método simplesmente espera encontrar um único cliente com um determinado endereço de email, o segundo método retorna todos os clientes com um determinado sobrenome e aplica-se a ordenação determinada ao resultado, enquanto o terceiro método retorna uma página de clientes. Para mais  detalhes dê uma olhada neste artigo (inglês)

Embora essa abordagem seja realmente conveniente (você não precisa escrever uma única linha de implementação de código para ter as queries executadas) temos 2 desvantagens nisso: primeira, o número de métodos de consultas pode crescer para grandes aplicações por causa disso – e esse é o segundo ponto, as consultas definem um conjunto fixo de criterias. Para evitar essas 2 desvantagens, não seria legal se você pudesse chegar com um conjunto de atributos atômicos que você pudesse combinar dinamicamente para construir uma consulta?

Se você é uma usuário de JPA a muito tempo, você pode responder: não é pra isso que a API Criteria serve? Correto, então vamos dar uma olhada como se parece um exemplo de implementação de regra de negócio utilizando a API Criteria JPA. Esse é o caso de uso: nos aniversários deles nós queremos enviar um voucher para todos cliente de longa data. Como recuperaríamos aqueles com essa combinação?

Nós praticamente temos 2 partes para o predicate (atributo/predicado): o aniversário assim como o que nós chamamos de cliente-de-longa-data. Vamos assumir que isso significa que a criação da conta do cliente foi a pelo menos 2 anos atrás. Assim é como se pareceria a implementação utilizando a API Crieria JPA:

LocalDate today = new LocalDate();

CriteriaBuilder builder = em.getCriteriaBuilder();
CriteriaQuery<Customer> query = builder.createQuery(Customer.class);
Root<Customer> root = query.from(Customer.class);

Predicate hasBirthday = builder.equal(root.get(Customer_.birthday), today);
Predicate isLongTermCustomer = builder.lessThan(root.get(Customer_.createdAt), today.minusYears(2);
query.where(builder.and(hasBirthday, isLongTermCustomer));
em.createQuery(query.select(root)).getResultList();

O que temos aqui? Criamos uma nova LocalDate por conveniência e seguimos com três linhas padrões para estabelecer as instâncias da infraestrutura JPA necessária. Então temos duas linhas construindo os atributos/predicados, uma para concatenar as duas e uma ultima para executar a consulta atual. Estamos usando classes de meta-modelagem introduzidas com JPA 2.0 e geradas pela API de Processamento de Anotações. O principal problema com este código é que os atributos não são fáceis de externalizar e reutilizar porque você precisa configurar o CriteriaBuilder, CriteriaQuery e o Root primeiro. Além da readaptação do código é tão pobre quanto é difícil de deduzir rapidamente a intenção do código à primeira vista.

Especificações
Para estar apto para definir atributos/predicados reutilizáveis nós introduzimos a interface de Especificação que é derivada dos conceitos introduzidos no livro Domain Driven Design de Eric Vans. Ele define uma especificação como um atributo sobre uma entidade a qual é exatamente o que nossa interface de especificação representa. Atualmente consiste em apenas um único método:

public interface Specification<T> {

Predicate toPredicate(Root<T> root, CriteriaQuery query, CriteriaBuilder cb);

}

então agora podemos facilmente utilizar uma classe utilitária como essa:

public CustomerSpecifications {
  public static Specification<Customer> customerHasBirthday() {
    return new Specification<Customer> {
      public Predicate toPredicate(Root<T> root, CriteriaQuery query, CriteriaBuilder cb) {
        return cb.equal(root.get(Customer_.birthday), today);
      }
    };
  }

  public static Specification<Customer> isLongTermCustomer() {
    return new Specification<Customer> {
      public Predicate toPredicate(Root<T> root, CriteriaQuery query, CriteriaBuilder cb) {
        return cb.lessThan(root.get(Customer_.createdAt), new LocalDate.minusYears(2));
      }
    };
  }
}

Reconhecidamente, não é o código mais bonito do mundo, mas fornece nossa necessidade inicial muito bem: podemos nos referir a um conjunto de especificações atômicas. A próxima questão é: como vamos executar essas especificações? Para fazer isso, você simplesmente estende JpaSpecificationExecutor na interface do seu repositório e assim “puxa” uma API para executar especificações:

public interface CustomerRepository extends JpaRepository<Customer>, JpaSpecificationExecutor {
  // Seus métodos de consulta aqui!!!
}

Um cliente pode agora fazer:

customerRepository.findAll(hasBirthday());
customerRepository.findAll(isLongTermCustomer());

A implementação do repositório básico irá preparar o CriteriaQuery, Root e CriteriaBuilder para você, aplique o atributo/predicado criado por uma especificação determinada e execute a consulta. Mas nós não poderiamos apenas ter criado métodos simples de consulta para realizar isso? Correto, mas lembre-se do nossa segunda necessidade inicial. Nós queremos estar aptos para combinar livremente especificações atômicas para criar novos na hora. Para fazer isso nós temos especificações da classe utilitária que fornece os métodos and(…) e or(…) para concatenar especificações anatomicas. Temos também um where(…) que fornece uma doce semântica que faz a expressão mais legível. O exemplo do caso se uso que vimos no começo parece com isso:

customerRepository.findAll(where(customerHasBirthday()).and(isLongTermCustomer()));

Isto fica mais legível, melhorando tanto a legibilidade quanto fornecendo flexibilidade adicional comparado ao uso da API Criteria JPA sozinha. A única ressalva aqui é que subindo com a implementação da especificação requer algum esforço  de codificação.

QueryDSL
Para curar essa dor um projeto open-source chamado Querydsl surgiu com uma abordagem bastante similar mas também diferente. Assim como a API Criteria JPA ela usa um processador de anotações Java 6 para gerar objetos meta-modelos mas produz uma API muito mais acessível. Outra coisa legal sobre o projeto, é que não tem suporte apenas para JPA, mas também aceita consultas Hibernate, JDO, Lucene, JDBC e até coleções simples.

Então para tê-lo instalado e rodando você adiciona o QueryDSL ao seu pom.xml e configura o plugin APT plugin conforme abaixo:

<plugin>
   <groupId>com.mysema.maven</groupId>
   <artifactId>maven-apt-plugin</artifactId>
   <version>1.0</version>
   <executions>
      <execution>
        <phase>generate-sources</phase>
        <goals>
          <goal>process</goal>
        </goals>
        <configuration>
            <outputDirectory>target/generated-sources</outputDirectory>
            <processor>com.mysema.query.apt.jpa.JPAAnnotationProcessor</processor>
        </configuration>
      </execution>
   </executions>
</plugin>

Isso irá fazer o seu build criar classes de consulta especiais – QCustomer dentro do mesmo pacote no nosso caso.

QCustomer customer = QCustomer.customer;
LocalDate today = new LocalDate();
BooleanExpression customerHasBirthday = customer.birthday.eq(today);
BooleanExpression isLongTermCustomer = customer.createdAt.lt(today.minusYears(2));

Este não é apenas o Inglês quase fluente fora da caixa (?), o BooleanExpressions, é mesmo reutilizável sem mais empacotamento do qual nos livra da especificação wrapper adicional (um pouco desagradável de implementar). Um plus adicional é que você tem o auto-complete de código da IDE a cada ponto do lado direito de atribuição, então customer. + CTRL + SPACE listará todas as propriedades. customer.birthday. + CTRL + SPACE listará todas as palavras-chave disponíveis e assim por diante. Para executar os atributos do QueryDSL você simplesmente estende QueryDslPredicateExecutor ao seu repositório:

public interface CustomerRepository extends JpaRepository<Customer>, QueryDslPredicateExecutor {
  // Seus métodos de consulta aqui!!!
}

Os clientes podem simplesmente fazer:

BooleanExpression customerHasBirthday = customer.birthday.eq(today);
BooleanExpression isLongTermCustomer = customer.createdAt.lt(today.minusYears(2));
customerRepository.findAll(customerHasBirthday.and(isLongTermCustomer));

Resumo
A abstração do repositório Spring Data JPA permite a execução de atributos/predicados ou via atributos API Criteria JPA wrapped dentro de um objeto de especificação ou via atributos QueryDSL. Para permitir essa funcionalidade você simplesmente deixa seu repositório extender JpaSpecificationExecutor ou QueryDslPredicateExecutor (você poderia até mesmo usar os 2 se você gostou). Veja que você precisa dos JAR’s do QueryDSL na classe no caso de você decidir pela abordagem do QueryDSL.

Mais uma coisa
Mais uma coisa legal sobre a abordagem do QueryDSL é que ela não está apenas disponível para os nossos repositórios JPA, mas para nosso apoio MongoDB também. A funcionalidade é inclusa apenas no release M2 do Spring Data MongoDB. Além de ambos módulos Mongo e JPA do Spring Data, são suportados na plataforma CloudFoundry. Veja os exemplos em cloudfoundry-samples wiki para iniciar  em Spring Data e CloudFoundry.

Fonte: SpringSource – Oliver Gierke

Anúncios