Ajout d'élément au FROM

Il est souvent nécessaire d'ajouter une autre entité au FROM de la requête, pour ce faire, il existe deux méthodes :

• addFrom(Class entityClass) : ajoute une entité au FROM (Ex : addFrom(Contact.class);)

• addFrom(Class entityClass, String alias) : ajoute une entité au FROM avec un alias (Ex : addFrom(Contact.class, "C");)

C'est généralement la dernière méthode qui sera la plus utilisé, l'utilisation des alias facilitant grandement les liaisons entre les entités.

Depuis la 2.3.4, deux méthodes ont été rajoutés pour le cas des jointures :

• addJoin(Class entityClass, String alias, boolean fetch) : utilise un inner join pour lier une entité à celle de la requête. Concrètement l'opérateur JOIN Hql sera utilisé : 'FROM Contact C JOIN C.boat' ::

  TopiaContext transaction = rootContext.beginTransaction(); ContactDAO dao = ModelDAOHelper.getBoatDAO(transaction); TopiaQuery query = dao.createQuery("C").addJoin("C.boat", null, false);

• addLeftJoin(Class entityClass, String alias, boolean fetch) : même chose que le addJoin sauf que l'opérateur LEFT JOIN Hql sera utilisé.

Voir le `Chargement des donnees` pour l'utilisation du fetch.

Ajout d'élément au SELECT

Deux méthodes sont disponibles pour le cas du SELECT, une méthode addSelect qui se chargera d'ajouter une propriété au SELECT, et une méthode setSelect qui définira directement quel est le SELECT souhaité. Pour le cas du addSelect, la méthode gère automatiquement l'entité principale utilisé pour instancier la requête, il n'est donc pas nécessaire de l'ajouter manuellement.

TODO : find an example

Le setSelect quant à lui est utilisé pour les aggregations par exemple ou pour récupérer des parties précises du résultat :

   TopiaContext transaction = rootContext.beginTransaction();
   BoatDAO dao = ModelDAOHelper.getBoatDAO(transaction);
   // On souhaite connaître le nombre de résultats uniquement
   TopiaQuery query = dao.createQuery().
                       addNotNull(Boat.NAME).
                       setSelect("COUNT(*)");

autre exemple :

   // On souhaite récupérer uniquement les noms des navires
   TopiaQuery query = dao.createQuery().
                       addNotNull(Boat.NAME).
                       setSelect(Boat.NAME);

Note

Pour l'ajout d'une contrainte sur l'unicité des résultats, vous pouvez utiliser la méthode addDistinct() qui permet l'ajout du mot clé DISTINCT sur le SELECT de la requête.

Ajout d'élément au GROUP BY

Dans certains cas, il peut être nécessaire d'utiliser un GROUP BY pour les aggregations :

   TopiaContext transaction = rootContext.beginTransaction();
   ContactDAO dao = ModelDAOHelper.getContactDAO(transaction);
   // On souhaite connaître le nombre de contacts par navire
   TopiaQuery query = dao.createQuery().
                       setSelect("COUNT(*)").
                       addGroup(Contact.BOAT);

Ajout d'élément au ORDER BY

Il est possible également d'ajouter un ordre aux résultats :

   TopiaContext transaction = rootContext.beginTransaction();
   BoatDAO dao = ModelDAOHelper.getBoatDAO(transaction);
   // Tous les noms des navires triés
   TopiaQuery query = dao.createQuery().
                       addNotNull(Boat.NAME).
                       setSelect(Boat.NAME).
                       addOrder(Boat.NAME);

Une autre méthode est disponible pour l'ordre descendant : addOrderDesc. Cependant rien ne vous interdit la syntaxe suivante :

   addOrder(Boat.NAME, Boat.BUILD_YEAR + " desc");

Limitation des résultats

Il est possible de limiter le nombre de résultats lors de l'exécution pour optimiser la requête dans le cas d'une pagination par exemple. Pour ce faire il faut utiliser les méthodes setLimit(int start, int end) et/ou setMaxResults(int max) :

   // 18 premiers résultats
   query.setLimit(0, 17);
   // équivalent à
   query.setMaxResults(18);
   // résultats du 50ème au 60ème
   query.setLimit(49, 59);

// depuis 2.3.4

Pour éviter d'embarquer ces paramètres à chaque fois qu'ils sont nécessaires lors d'un filtrage paginée, un bean, EntityFilter est disponible. Il contient les attributs suivants :

• startIndex : index de début des résultats.

• endIndex : index de fin des résultats.

• orderBy : propriétés à ordonner (l'ajout des mots clés 'asc' et 'desc' est possible).

• referenceId : identifiant d'une référence utile à la requête.

• referenceProperty : nom de la propriété correspondant à la valeur du referenceId.

Exemple : Nous souhaitons les contacts 30 à 60 triés par 'creationDate' décroissant et 'personName' croissant pour un navire donné par son topiaId :

   EntityFilter filter = new EntityFilter();
   filter.setStartIndex(30);
   filter.setEndIndex(60);
   filter.setOrderBy("creationDate desc, personName");
   filter.setReferenceId(boat.getTopiaId());
   // ou filter.setReference(boat);
   filter.setReferenceProperty("boat");

   TopiaQuery query = contactDAO.createQuery().addFilter(filter);

L'intérêt de l'EntityFilter est de pouvoir l'instancier et le manipuler directement depuis votre interface (Swing, Web, ...) et de l'utiliser sur une requête métier. La méthode addFilter(EntityFilter filter) permettra d'injecter les paramètres s'ils possèdent une valeur.

Note

L'ordre définit par défaut est celui de création par ordre décroissant : topiaCreateDate desc.

Utilisation des DAO

Les DAO fournissent également quelques méthodes permettant de récupérer plus facilement les résultats avec le type souhaité :

• countByQuery(TopiaQuery query) : compte le nombre de résultats de la requête.

• existByQuery(TopiaQuery query) : renvoie vrai si la requête à retourner au moins 1 résultat.

• findByQuery(TopiaQuery query) : renvoie une entité (un seul résultat)

• findAllByQuery(TopiaQuery query) : renvoie une liste d'entités

• findAllMappedByQuery(TopiaQuery query) : renvoie une map d'entités avec pour clé le topiaId de l'entité.

• findAllMappedByQuery(TopiaQuery query, Class keyClass, String keyProperty) : renvoie une map d'entités avec pour clé la propriété passée en argument.

Exemple :

   TopiaContext transaction = rootContext.beginTransaction();
   BoatDAO dao = ModelDAOHelper.getBoatDAO(transaction);
   TopiaQuery query = dao.createQuery();
   ...
   // pour vérifier l'existance de résultat
   boolean hasResult = dao.existByQuery(query);

   // pour savoir le nombre de résultats
   int count = dao.countByQuery(query);

   // pour récupérer les résultats
   Map<String, Boat> boatMap = dao.findAllMappedByQuery(query);
   // ou
   List<Boat> boatList = dao.findAllByQuery(query);
   // ou juste le premier résultat
   Boat boat = dao.findByQuery(query);
   // ou avec pour clé l'immatriculation du navire (unique)
   Map<Integer, Boat> boatMapImma = dao.findAllMappedByQuery(query,
           Integer.class, Boat.IMMATRICULATION);

Résultats complexes

Certains cas de requête peuvent avoir des résultats plus complexes, notamment lorsqu'il s'agit de propriétés de différentes entités ou avec l'utilisation d' aggrégats (AVG, SUM, COUNT). Dans ce cas il faut utiliser la méthode de base findByQuery(TopiaQuery query) depuis une transaction qui renverra une liste non typée. Lorsqu'il y a plus d'un élément dans le select la liste renvoyée est une List<Object[]>, le tableau pour chaque ligne correspondant aux valeurs des résultats. Exemple :

   TopiaContext transaction = rootContext.beginTransaction();
   ContactDAO dao = ModelDAOHelper.getContactDAO(transaction);
   String boatImma = Contact.BOAT + "." + Boat.IMMATRICULATION;
   // On souhaite le nombre de contacts par navire
   TopiaQuery query = dao.createQuery().
                   setSelect(boatImma, "COUNT(*)").addGroup(boatImma);

   List<Object[]> results = transaction.findByQuery(query);
   // Parcours des résultats
   for (Object[] result : results) {
       Integer immatriculation = (Integer)result[0];
       Long count = (Long)result[1];
   }

Note

Les aggrégats renvoient principalement un type Long et non Integer.

Chargement automatique

Hibernate permet de déclarer explicitement que certaines relations doivent se charger dès la récupération des entités. Il faut pour cela utiliser le tagValue lazy dans le fichier de properties du modèle. Par exemple pour charger le navire associé à chaque contact récupéré via une requête, il faut préciser :

   myapp.entity.Contact.attribute.boat.tagvalue.lazy=false

(myapp.entity.Contact étant le nom qualifié de la classe Contact)

Ainsi chaque contact récupéré aura automatiquement son navire associé de chargé.

Attention cependant, il ne faut pas abuser du tagvalue lazy car sinon Hibernate risque de charger une bonne partie de votre base de données à chaque fois, ce qui peut s'avérer extrêment coûteux. Cette utilisation doit être limitée au cas d'une simple association comme c'est ici le cas, le Boat chargé étant indispensable à l'utilisation du Contact.

Chargement manuel

La TopiaQuery fournit deux méthodes intéressantes pour le chargement manuelle :

• addLoad(String...) : permet de charger les relations une fois la requête exécutée.

• addFetch(String...) : permet de charger les relations directement au moment de la requête en utilisant une jointure et le mot clé 'FETCH' Hql.

Le addLoad est pour le moment limité à des relations unitaires (autant que votre modèle vous le permet, ex : entityA.entityB.entityC) ou à une seule relation multiple directe ou indirecte (entityA.entitiesB). Si nous prenons le cas du modèle d'exemple, il est possible de charger le navire associé aux contacts en utilisant : queryContact.addLoad(Contact.BOAT);

Dans le cas du addLoad, plusieurs requêtes seront exécutées suivant le nombre de Contact résultats. Il est dans ce cas plus judicieux d'utiliser le addFetch qui chargera directement les Boat au moment de la récupération des Contact : queryContact.addFetch(Contact.BOAT); L'alias peut s'avérer indispensable pour l'utilisation du addFetch, voir la javadoc pour l'utilisation des arguments.

Note

Les méthodes de jointures permettent de faire un fetch directement : addJoin(String property, String alias, boolean fetch); Voir la partie de la documentation concernant le FROM de la requête.

Attention

Hibernate ne supporte pas plus de 3 ou 4 jointures suivant leurs complexités ! Il est donc important de limiter l'utilisation des fetch aux cas simples.

Que choisir ?

• Relation unitaire (N-1) obligatoire : utiliser le tagValue lazy

• Requête relativement simple (moins de deux jointures) : utiliser le addFetch

• Requête complexe : utiliser le addLoad

• Si addLoad non utilisable (trop de chargement de collections) : effectuer un chargement manuel en parcourant les résultats. Pour le chargement d'une entité simple, il suffit d'utiliser le getter correspondant pour la charger, tandis que pour une collection, l'appel à la méthode size associée permet de charger l'intégralité des éléments.