Consultas com HQL no Hibernate 3

O Hibernate possui uma linguagem de consulta para retornar objetos da base de dados (com SELECT) chamada HQL que � muito parecida com o SQL, mas ao inv�s de efetuar operaç�es nas tabelas e colunas da base de dados, o HQL trabalha com objetos persistentes e suas propriedades, ou seja, classes e propriedades das classes. O HQL inspirou a criaç�o da JPQL (Java Persistence Query Language) que faz parte da especificaç�o oficial da JPA. A linguagem HQL n�o se limita apenas a consultas, mas tamb�m pode ser usada para alterar informaç�es da base de dados (com INSERT, UPDATE, DELETE). O HQL n�o permite que possamos alterar a estrutura da base de dados.

A utilizaç�o da HQL � sempre bastante recomendada para evitarmos problemas de portabilidade e principalmente termos como vantagens a geraç�o do SQL por parte do Hibernate feita da melhor forma e mais otimizada, e tamb�m as estrat�gias de cache que o Hibernate cria.

Sintaxe B�sica do SELECT

O HQL tem sua pr�pria sintaxe e gram�tica, sendo escritas como Strings ao contr�rio da API Criteria do Hibernate que tem a forma de uma API convencional do Java. As consultas HQL s�o traduzidas pelo Hibernate em consultas SQL. Al�m disso, o Hibernate tamb�m prov� uma API que permite consultas SQL diretamente.

O SELECT � utilizado para consultar classes e suas propriedades na base de dados. Apesar da linguagem HQL ter um poder expressivo altamente poderoso, se quisermos uma maior complexidade utilizando joins e like, devemos optar pela API Criteria que � mais apropriada. Na Listagem 1 temos um exemplo de como utilizar o comando SELECT.

Listagem 1. Comando SQL

[SELECT [DISTINCT] property [, ...]]
           FROM path [[AS] alias] [, ...] [FETCH ALL PROPERTIES]
           WHERE logicalExpression
           GROUP BY property [, ...]
           HAVING logicalExpression
           ORDER BY property [ASC | DESC] [, ...]

O atributo path � o nome completo da entidade. O �alias� podem ser usados para abreviar refer�ncias para entidades espec�ficas ou suas propriedades e tamb�m pode ser utilizado quando nomes de propriedades usadas s�o amb�guas. O atributo property � o nome das propriedades das entidades listadas no path ap�s FROM. Se utilizarmos o FETCH ALL PROPERTIES, as sem�nticas lazy loading ser�o ignoradas e dessa forma, todas as propriedades dos objetos recuperados ser�o ativamente carregados (isto n�o � aplicado recursivamente). Uma das diferenças ao utilizarmos JPQL ao inv�s de HQL � que a JPQL requer a cl�usula SELECT, ao passo que no HQL podemos omitir o SELECT.

Palavras-chaves do HQL podem ser mai�sculas ou min�sculas. Por outro lado, o nome das classes e propriedades s�o case sensitive. Assim, uma consulta �from Produto� � similar a �FROM Produto�, mas uma consulta �from produto� n�o � o mesmo que �from Produto�.

Um �alias� pode ser usado com AS definido ou sem, como por exemplo �from Produto produto� ou �from Produto as produto�.

Se tivermos nomes de classes duplicados na aplicaç�o podemos utilizar o pacote com o nome da classe como, por exemplo, �from com.exemplo.produtos.Produto�.

Outra forma de usar o SELECT � retornar apenas algumas propriedades ao inv�s do objeto inteiro, como por exemplo: �select produto.nome from Produto produto� onde essa consulta retornaria uma LISTA de objetos String.

Mas se quisermos retornar alguns atributos, ter�amos o HQL �select produto.nome, produto.preco from Produto produto� onde ter�amos um resultado contendo uma lista de arrays de objetos, onde cada array representa um conjunto de propriedades.

Utilizando Restriç�es

Assim como no SQL, podemos usar a cl�usula WHERE para selecionar resultados que combinam com as nossas consultas. HQL prov� diferentes express�es que podemos usar para construir uma consulta. As poss�veis express�es s�o:

Operadores L�gicos: OR, AND, NOT
Operadores de Igualdade: =,
Operadores de Comparaç�o: , =, like, not like, between, not between
Operadores Matem�ticos: +, -, *, /
Operadores de Concatenaç�o: ||
Cases: Case when then else _ end
Express�es de Coleç�o: some, exists, all, any

Al�m dessas ainda podemos usar a seguintes express�es nas cl�usulas where:

Par�metros nomeados do HQL: :date, :quantity
Par�metros de consulta JDBC: ?
Operadores de Data e Tempo do SQL-92: current_time(), current_date(), current_timestamp()
Funç�es SQL (Suportados pela Base de Dados): length(), upper(), lower(), ltrim(), rtrim(), etc.

Dessa forma, podemos construir cl�usulas com WHERE no HQL t�o poderosas quanto uma consulta SQL. Segue abaixo uma consulta HQL que demonstra algumas das restriç�es discutidas acima:


  from Produto where preco > 25.0 and nome like ''Tec%''

Nesse exemplo temos as operaç�es ">", "and", e "like". Nessa consulta estamos procurando produtos com preços acima de 25.0 e que tenham nomes iniciando com "Tec".

Usando Par�metros Nomeados

Uma funcionalidade extremamente importante nas consultas HQL do Hibernate s�o os par�metros nomeados. Isto faz com que a escrita de consultas que aceitam entradas do usu�rio seja bastante simples e ainda defende nosso c�digo contra ataques de SQL Injection. Se n�o utilizarmos par�metros nomeados podemos estar sendo vulner�veis a esse tipo de ataque.

Par�metros nomeados no Hibernate s�o iguais aos utilizados pela JDBC (?), por�m o Hibernate � menos confuso. Na Listagem 2 temos um exemplo bastante simples, mas que demonstra de forma clara como podemos usar par�metros nomeados no Hibernate

Listagem 2. Par�metros nomeados

String hql = "from Produto where preco > :preco";
  Query query = session.createQuery(hql);
  query.setDouble("preco",25.0);
  List results = query.list();

No exemplo acima, no lugar do valor 25.0 em query.setDouble("preco",25.0); provavelmente ter�amos uma vari�vel, pois n�o sabemos o valor que ser� inserido ali. Se j� soubermos o valor podemos colocar ele diretamente dentro da String como na Listagem 3.

Listagem 3. Valor direto na String

String detalhesProdutoHQL = "from DetalhesProduto where nome=''Veja''";
  Query detalhesProdutoQuery = session.createQuery(detalhesProdutoHQL);
  DetalhesProduto detalhesProduto = 
  (DetalhesProduto) detalhesProdutoQuery.list().get(0);

Outra situaç�o interessante � quando j� temos um objeto e queremos fazer alguma consulta em cima deste objeto. Podemos imaginar a situaç�o em que temos o objeto pesquisado no exemplo acima e vamos usar esse objeto para fazer outra pesquisa, como � exemplificado na Listagem 4.

Listagem 4. Nova pesquisa

String hql = "from Produto as produto where 
   produto.detalhes=:detalhesProduto";
  Query query = session.createQuery(hql);
  query.setEntity("detalhesProduto",detalhesProduto);
  List results = query.list();

Paginaç�o

A paginaç�o � muito �til quando temos uma grande quantidade de informaç�o retornada atrav�s de uma consulta e queremos exibir apenas algumas dessas informaç�es. Isso � muito utilizado nas aplicaç�es Web onde devemos construir uma p�gina apropriada para o usu�rio sem poluir muito a tela.

Existem dois m�todos na interface Query para paginaç�o: setFirstResult() e setMaxResults(). O m�todo setFirstResult() requer um inteiro que representa a primeira linha no result set, podendo iniciar na linha 0. O m�todo setMaxResults() retorna um n�mero fixo de objetos. Na Listagem 5 temos um exemplo de paginaç�o no Hibernate.

Listagem 5. Paginaç�o

Query query = session.createQuery("from Produto");
  query.setFirstResult(1);
  query.setMaxResults(2);
  List results = query.list();

O Hibernate usa o comando SQL apropriado dependendo da base de dados, dessa forma, se o Banco de dados utilizado for Microsoft SQL Server ele usar� o comando top, se estivermos usando o Banco de dados HSQLDB o Hibernate usar� o comando top e limit. Devemos ficar alerta para poss�vel problemas de performance na utilizaç�o de paginaç�o.

Obtendo Resultados �nicos

A interface Query do HQL prov� o m�todo uniqueResult() que � utilizando para obter apenas um �nico objeto de uma consulta HQL, caso n�o seja retornado nenhum resultado teremos um null como retorno do m�todo. Caso tenhamos mais de um objeto retornado teremos uma exceç�o NonUniqueResultException.

Nesse caso, poder�amos utilizar o m�todo setMaxResults() como discutido na sess�o anterior. Na Listagem 6 temos um exemplo da utilizaç�o de uniqueResult().

Listagem 6. Usando resultados �nicos

String hql = "from Produto where preco > 25.0";
  Query query = session.createQuery(hql);
  query.setMaxResults(1);
  Produto produto = (Produto) query.uniqueResult();
  //testa resultados nulos se necess�rio

Ordenando Resultados

Para ordenar os resultados de uma consulta HQL podemos utilizar a clausula order by ascendente (asc) ou descendente (desc). Em HQL podemos fazer como no exemplo abaixo:


  from Produto p where p.preco > 25.0 order by p.preco desc

Se quisermos um comando �order� para mais de uma propriedade basta separarmos por v�rgulas como abaixo:


  from Produto p order by p.nome asc, p.preco asc

Associaç�es

Assim como no SQL, com HQL tamb�m podemos fazer relacionamentos entre classes (tabelas) utilizando a clausula join. O Hibernate tamb�m suporta cinco diferentes tipos de joins: inner join, cross join, left outer join, right outer join e full outer join.

Se utilizarmos o cross join n�o precisamos especificar nada, basta colocar as classes separadas por v�rgulas ap�s o from, como exemplificado abaixo:


  from Produto p, DetalhesProduto d

Para utilizarmos o inner join devemos fazer da seguinte forma:


  select d.descricao, p.nome, p.preco from Produto p 
   inner join p.detalhesProduto as d

Ou ent�o da forma abaixo:


  from Produto p inner join p.detalhesProduto as d

Como retorno teremos arrays de objetos retornados. Se quisermos melhorar performance ainda podemos utilizar o fetch para as consultas. Segue abaixo um exemplo:


  from DetalhesProduto d inner join fetch d.produto as p

Dessa forma teremos como resultado apenas a classe DetalhesProduto e nenhum objeto Produto. Produto somente ser� carregado quando acessarmos a sua propriedade.

Agregaç�o

Assim como no SQL, utilizando HQL tamb�m temos os m�todos agregados. Segue abaixo os m�todos de agregaç�o dispon�veis no Hibernate:

avg(nome da propriedade): Retorna a m�dia do valor da propriedade.
count(nome da propriedade ou *): Retorna o n�mero de vezes que a propriedade ocorre no resultado.
max(nome da propriedade): O valor m�ximo do valor da propriedade.
min(nome da propriedade): O valor m�nimo do valor da propriedade.
sum(nome da propriedade): A soma total dos valores da propriedade.

Segue abaixo um exemplo que determina os valores m�nimo e m�ximo a serem retornados da consulta:


  select min(produto.preco), max(produto.preco) from Produto produto

Com isso, neste artigo vimos como fazer consultas utilizando o HQL, como utilizar restriç�es com as consultas, como utilizar os par�metros nomeados evitando ataques SQL Injection, como utilizar paginaç�es e outras funcionalidades que fazem do HQL uma poderosa linguagem de consulta.

Bibliografia

[1]Hibernate - JBoss Community, dispon�vel em www.hibernate.org/

[2]Documentaç�o de Refer�ncia Hibernate, dispon�vel em https://docs.jboss.org/hibernate/orm/3.5/reference/en/html/queryhql.html

[3] Introduç�o ao Hibernate, dispon�vel em https://docs.jboss.org/hibernate/orm/6.3/introduction/html_single/Hibernate_Introduction.html

[4] Jeff Linwood and Dave Minter. An introduction to persistence using Hibernate 3.5, Second Edition. Apress.

[5] Steve Perkins. Hibernate Search by Example: Explore the Hibernate Search system and use its extraordinary search features in your own applications. Packt Publishing.