L'API Criteria

Introduction

Avec les requêtes basées sur des chaînes de caractères (JPQL, HQL ou SQL), il n’est pas possible de contrôler leur syntaxe avant leur exécution de manière automatique.

Par exemple, une faute de frappe, une mauvaise entité dans une requête JPQL et/ou une mauvaise syntaxe n’empêchent pas la compilation du code source :

Query query = em.createQuery("SELCT e From EntiteInexistante e WHERE AND  
e.champ = 'valeur'");
 

De ce fait, Hibernate a mis en place une API nommée Criteria afin de prendre en compte cette problématique. Cela a aussi permis la construction de requêtes dynamiques via une liste d’interfaces et d’objets. JPA a introduit sa propre API de construction de requêtes lors de sa version 2.0, qui est aussi nommée Criteria, qui est désormais la norme et est donc reprise par chacune de ses implémentations. Ainsi, lors de l’utilisation de l’API Criteria, il est important de s’assurer de la version utilisée : javax.persistence pour JPA (celle qui nous intéresse) et org.hibernate pour l’API d’Hibernate.

Comme la construction d’une requête avec l’API Criteria de JPA se fait avec l’instanciation de différents objets et appels de méthodes, elle est un peu plus complexe et verbeuse que l’écriture avec JPQL.

Par exemple...

L’API Metamodel

L’API Metamodel est donc l’API de JPA qui permet de définir le métamodèle au sein d’une application basée sur JPA.

Le métamodèle est une liste de classes représentant la structure des données de l’unité de persistance, c’est une image des différentes entités utilisées.

Ainsi, chaque classe du métamodèle décrit une entité avec ses propriétés et ses relations avec les autres, sans décrire son lien avec la base de données (ex. : la colonne) ni ses interactions (ex. : le type de cascade).

Ce métamodèle a deux utilités :

Ainsi, deux types de métamodèles existent :

Généralités

L’API Criteria permet d’interroger les données du contexte de persistance, donc par extension, la base de données. Ainsi, comme pour une requête JPQL, HQL ou encore SQL, une requête Criteria peut être séparée en cinq parties :

De plus, chacune de ces parties peut accepter des expressions telles qu’un attribut, une condition, une opération...

Cette API est articulée autour du CriteriaBuilder. C’est-à-dire que le point de départ de construction de chaque requête Criteria est toujours une instance d’un CriteriaBuilder. Cette instance se récupère depuis un EntityManager ...

Le type d’opération

Le type d’opération est l’action effectuée sur la base de données. Il n’est possible de réaliser que trois types d’opérations avec l’API Criteria qui sont la lecture, la modification et la suppression (SELECT, UPDATE et DELETE). Chacune de ces opérations a ses propres classes qui sont :

La récupération de ces classes se fait depuis le CriteriaBuilder avec leur méthode createXXX() où XXX correspond au mot-clé pour la classe voulue. Ce qui implique qu’avant de construire une requête Criteria, il faut savoir quel type d’opération va être effectué.

Ainsi, pour chaque opération voulue, les méthodes sont :

Par exemple, pour récupérer un CriteriaDelete afin de supprimer des entités Personne :

EntityManager em = ...; 
 
//Récupération du CriteriaBuilder 
CriteriaBuilder cb = em.getCriteriaBuilder(); 
 
//Récupération du CriteriaDelete 
CriteriaDelete<Personne> cd = cb.createCriteriaDelete(Personne.class);
 

Le périmètre (FROM)

Le périmètre d’une requête sert à définir les données qui sont impliquées dans la manipulation. Que ce soit les données qui seront retournées, modifiées, supprimées ou utilisées en interne (restriction, regroupement, tri). Avec une requête basée sur une chaîne de caractères (JPQL, SQL...), ce sont les informations qui se trouvent entre le mot-clé FROM et le mot-clé WHERE. C’est-à-dire les tables à utiliser avec leurs jointures éventuelles.

CriteriaQuery cq = ...  
 
//Définition de l'entité Root 
Root<Personne> p = cq.from(Personne.class);
 

FROM Personne p
 

CriteriaQuery...

Les restrictions (WHERE)

Les restrictions permettent de limiter les données impactées par le périmètre de la requête. Elles correspondent à la clause WHERE d’une requête JPQL. Ainsi, pour paramétrer les restrictions d’une requête Criteria, il faut utiliser la méthode where() que ce soit pour un CriteriaQuery, CriteriaUpdate ou CriteriaDelete.

L’appel de la méthode where() peut être fait de cinq manières différentes :

Il faut savoir qu’un Predicate hérite de Expression<Boolean> et permet donc d’évaluer des conditions. Les différentes possibilités des Predicate sont décrites à la section Les expressions.

De plus, la méthode where() remplace à chaque appel les anciennes conditions. Ainsi, les conditions de restriction doivent être paramétrées en une seule fois.

Par exemple :

Root<PersonneAdresse> pa = cq.from(PersonneAdresse.class); 
 
Predicate condition1 = ...  
Predicate condition2 = ... 
 
cq.where(condition1);  
cq.where(condition2);
 

Donne en JPQL :

WHERE condition2
 

Root<PersonneAdresse> pa = cq.from(PersonneAdresse.class); 
 
//Récupération de l'attribut...

Le regroupement (GROUP BY et HAVING)

Le regroupement permet de faire des opérations d’agrégation sur des données. Il se décompose en deux étapes. La première est la définition des données à regrouper (la clause GROUP BY) et la deuxième est une étape de restriction sur les données regroupées (la clause HAVING). Comme avec JPQL, ce regroupement ne peut être effectué que sur une opération de type sélection, c’est-à-dire avec un objet CriteriaQuery. Ainsi, il faut utiliser les méthodes groupBy() et having(). La méthode groupBy() utilise des Expression<?> et la méthode having() utilise une Expression<Boolean> ou des Predicate (comme la méthode where()).

CriteriaQuery cq =... 
 
 
Expression<?> eGroupBy = ... 
Predicate prHaving = ...  
 
cq.groupBy(eGroupBy); 
cq.having(prHaving);
 

Ce qui va donner en JPQL :

GROUP BY eGroupBy HAVING prHaving
 

Ces deux méthodes fonctionnent comme la méthode where(), c’est-à-dire que l’appel de ces méthodes remplace les anciennes données. Ce qui implique que l’appel de ces méthodes sans paramètre supprime l’ancienne configuration.

CriteriaQuery cq =... 
 
 
Expression<?> eGroupBy1 = ... 
Expression<?> eGroupBy2 = ... 
 
Predicate prHaving = ...  
 
cq.groupBy(eGroupBy1);  
cq.groupBy(eGroupBy2); 
 
cq.having(prHaving);  
cq.having();
 

Ce qui va donner en JPQL :

GROUP BY eGroupBy2 -- Pas de HAVING
 

Comme pour JQL, les Predicate...

Le tri (ORDER BY)

Le tri permet d’organiser les données qui sont sélectionnées. C’est la clause ORDER BY d’une requête. De ce fait, le tri n’est disponible que pour les CriteriaQuery (les requêtes SELECT) en utilisant leur méthode orderBy() et en lui passant en paramètre de 0 à n objets Order sous la forme de suite d’objets (séparés par une virgule), d’une List<Order> ou d’un tableau d’Order. 

CriteriaQuery cq =... 
 
 
Order tri = ... 
 
 
cq.orderBy(tri);
 

Ce qui va donner en JPQL :

ORDER BY tri
 

Comme pour les méthodes where(), groupBy() et having(), la méthode orderBy() réinitialise à chaque fois les conditions de tri, ce qui implique que la dernière utilisation est celle prise en compte, et si elle est vide, le tri est effacé. 

Ci-dessous, l’état de la clause ORDER BY en fonction de l’appel de la méthode orderBy(...) :

CriteriaQuery cq =... 
 
 
Order tri = ... 
Order tri2 = ... 
 
//JPQL : -- Pas de tri 
 
cq.orderBy(tri);  
//JPQL : ORDER BY tri 
 
cq.orderBy(tri2); 
//JPQL : ORDER BY tri2 
 
 
cq.orderBy(); 
//JPQL : -- Pas de tri
 

Les expressions

Avec l’API Criteria, l’objet Expression<?> représente une valeur, que ce soit une donnée littérale (booléen, String...), une variable (Root, Join, paramètre), ou le résultat d’une fonction.

Root<Personne> p = ...  
 
//Récupération de l'attribut nom 
Path<String> attNom = p.get(Personne_.nom);
 

Path<String> attNumSecu =  
p.get(Personne_.personneDetail).get(PersonneDetail_.numSecu);
 

Exemples

FROM Entite
 

String requete = "FROM Personne"; 
 
List<Personne> lstPers = em.createQuery(requete).getResultList();
 

EntityManager em = ... 
 
//Définition de la requête 
CriteriaBuilder cb = em.getCriteriaBuilder(); 
CriteriaQuery cq = cb.createQuery(); 
Root<Personne> p = cq.from(Personne.class); 
 
//Exécution de la requête 
List<Personne> res = em.createQuery(cq).getResultList();