444 lines
17 KiB
XML
444 lines
17 KiB
XML
<?xml version="1.0" encoding="iso-8859-1"?>
|
|
<chapter id="querycriteria">
|
|
<title>Requêtes par critères</title>
|
|
|
|
<para>
|
|
Hibernate offre une API d'interrogation par critères intuitive et extensible.
|
|
</para>
|
|
|
|
<sect1 id="querycriteria-creating">
|
|
<title>Créer une instance de <literal>Criteria</literal></title>
|
|
|
|
<para>
|
|
L'interface <literal>net.sf.hibernate.Criteria</literal> représente une requête sur une
|
|
classe persistente donnée. La <literal>Session</literal> fournit les instances de
|
|
<literal>Criteria</literal>.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[Criteria crit = sess.createCriteria(Cat.class);
|
|
crit.setMaxResults(50);
|
|
List cats = crit.list();]]></programlisting>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="querycriteria-narrowing">
|
|
<title>Restriction du résultat</title>
|
|
|
|
<para>
|
|
Un criterion (critère de recherche) est une instance de l'interface
|
|
<literal>org.hibernate.criterion.Criterion</literal>. La classe
|
|
<literal>org.hibernate.criterion.Restrictions</literal> définit
|
|
des méthodes pour obtenir des types de <literal>Criterion</literal>
|
|
pré-définis.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[List cats = sess.createCriteria(Cat.class)
|
|
.add( Restrictions.like("name", "Fritz%") )
|
|
.add( Restrictions.between("weight", minWeight, maxWeight) )
|
|
.list();]]></programlisting>
|
|
|
|
<para>
|
|
Les restrictions peuvent être goupées de manière logique.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[List cats = sess.createCriteria(Cat.class)
|
|
.add( Restrictions.like("name", "Fritz%") )
|
|
.add( Restrictions.or(
|
|
Restrictions.eq( "age", new Integer(0) ),
|
|
Restrictions.isNull("age")
|
|
) )
|
|
.list();]]></programlisting>
|
|
|
|
<programlisting><![CDATA[List cats = sess.createCriteria(Cat.class)
|
|
.add( Restrictions.in( "name", new String[] { "Fritz", "Izi", "Pk" } ) )
|
|
.add( Restrictions.disjunction()
|
|
.add( Restrictions.isNull("age") )
|
|
.add( Restrictions.eq("age", new Integer(0) ) )
|
|
.add( Restrictions.eq("age", new Integer(1) ) )
|
|
.add( Restrictions.eq("age", new Integer(2) ) )
|
|
) )
|
|
.list();]]></programlisting>
|
|
|
|
<para>
|
|
Il y a plusieurs types de criterion pré-définis (sous classes de <literal>Restriction</literal>),
|
|
mais l'une d'entre elle particulièrement utile vous permet de spécifier directement
|
|
du SQL.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[List cats = sess.createCriteria(Cat.class)
|
|
.add( Restrictions.sql("lower({alias}.name) like lower(?)", "Fritz%", Hibernate.STRING) )
|
|
.list();]]></programlisting>
|
|
|
|
<para>
|
|
La zone <literal>{alias}</literal> sera remplacée par l'alias de colonne de l'entité
|
|
que l'on souhaite intérroger.
|
|
</para>
|
|
|
|
<para>
|
|
Une autre approche pour obtenir un criterion est de le récupérer d'une instance de <literal>Property</literal>.
|
|
Vous pouvez créer une <literal>Property</literal> en appelant <literal>Property.forName()</literal>.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[
|
|
Property age = Property.forName("age");
|
|
List cats = sess.createCriteria(Cat.class)
|
|
.add( Restrictions.disjunction()
|
|
.add( age.isNull() )
|
|
.add( age.eq( new Integer(0) ) )
|
|
.add( age.eq( new Integer(1) ) )
|
|
.add( age.eq( new Integer(2) ) )
|
|
) )
|
|
.add( Property.forName("name").in( new String[] { "Fritz", "Izi", "Pk" } ) )
|
|
.list();]]></programlisting>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="querycriteria-ordering">
|
|
<title>Trier les résultats</title>
|
|
|
|
<para>
|
|
Vous pouvez trier les résultats en utilisant <literal>org.hibernate.criterion.Order</literal>.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[List cats = sess.createCriteria(Cat.class)
|
|
.add( Restrictions.like("name", "F%")
|
|
.addOrder( Order.asc("name") )
|
|
.addOrder( Order.desc("age") )
|
|
.setMaxResults(50)
|
|
.list();]]></programlisting>
|
|
|
|
<programlisting><![CDATA[List cats = sess.createCriteria(Cat.class)
|
|
.add( Property.forName("name").like("F%") )
|
|
.addOrder( Property.forName("name").asc() )
|
|
.addOrder( Property.forName("age").desc() )
|
|
.setMaxResults(50)
|
|
.list();]]></programlisting>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="querycriteria-associations" revision="2">
|
|
<title>Associations</title>
|
|
|
|
<para>
|
|
Vous pouvez facilement spécifier des contraintes sur des entités liées,
|
|
par des associations en utilisant <literal>createCriteria()</literal>.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[List cats = sess.createCriteria(Cat.class)
|
|
.add( Restrictions.like("name", "F%")
|
|
.createCriteria("kittens")
|
|
.add( Restrictions.like("name", "F%")
|
|
.list();]]></programlisting>
|
|
|
|
<para>
|
|
Notez que la seconde <literal>createCriteria()</literal> retourne une nouvelle
|
|
instance de <literal>Criteria</literal>, qui se rapporte aux éléments de la
|
|
collection <literal>kittens</literal>.
|
|
</para>
|
|
|
|
<para>
|
|
La forme alternative suivante est utile dans certains cas.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[List cats = sess.createCriteria(Cat.class)
|
|
.createAlias("kittens", "kt")
|
|
.createAlias("mate", "mt")
|
|
.add( Restrictions.eqProperty("kt.name", "mt.name") )
|
|
.list();]]></programlisting>
|
|
|
|
<para>
|
|
(<literal>createAlias()</literal> ne crée pas de nouvelle instance de
|
|
<literal>Criteria</literal>.)
|
|
</para>
|
|
|
|
<para>
|
|
Notez que les collections kittens contenues dans les instances de <literal>Cat</literal>
|
|
retournées par les deux précédentes requêtes ne sont <emphasis>pas</emphasis> pré-filtrées
|
|
par les critères ! Si vous souhaitez récupérer uniquement les kittens qui correspondent à la
|
|
criteria, vous devez utiliser <literal>ResultTransformer</literal>.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[List cats = sess.createCriteria(Cat.class)
|
|
.createCriteria("kittens", "kt")
|
|
.add( Restrictions.eq("name", "F%") )
|
|
.setResultTransformer(Criteria.ALIAS_TO_ENTITY_MAP)
|
|
.list();
|
|
Iterator iter = cats.iterator();
|
|
while ( iter.hasNext() ) {
|
|
Map map = (Map) iter.next();
|
|
Cat cat = (Cat) map.get(Criteria.ROOT_ALIAS);
|
|
Cat kitten = (Cat) map.get("kt");
|
|
}]]></programlisting>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="querycriteria-dynamicfetching" revision="1">
|
|
<title>Peuplement d'associations de manière dynamique</title>
|
|
|
|
<para>
|
|
Vous pouvez spéficier au moment de l'exécution le peuplement d'une association en utilisant
|
|
<literal>setFetchMode()</literal> (c'est-à-dire le chargement de celle-ci).
|
|
Cela permet de surcharger les valeurs
|
|
"lazy" et "outer-join" du mapping.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[List cats = sess.createCriteria(Cat.class)
|
|
.add( Restrictions.like("name", "Fritz%") )
|
|
.setFetchMode("mate", FetchMode.EAGER)
|
|
.setFetchMode("kittens", FetchMode.EAGER)
|
|
.list();]]></programlisting>
|
|
|
|
<para>
|
|
Cette requête recherchera <literal>mate</literal> et <literal>kittens</literal>
|
|
via les jointures externes. Voir <xref linkend="performance-fetching"/> pour plus d'informations.
|
|
</para>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="querycriteria-examples">
|
|
<title>Requêtes par l'exemple</title>
|
|
|
|
<para>
|
|
La classe <literal>org.hibernate.criterion.Example</literal> vous permet de
|
|
construire un critère suivant une instance d'objet donnée.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[Cat cat = new Cat();
|
|
cat.setSex('F');
|
|
cat.setColor(Color.BLACK);
|
|
List results = session.createCriteria(Cat.class)
|
|
.add( Example.create(cat) )
|
|
.list();]]></programlisting>
|
|
|
|
<para>
|
|
Les propriétés de type version, identifiant et association sont ignorées.
|
|
Par défaut, les valeurs null sont exclues.
|
|
</para>
|
|
|
|
<para>
|
|
Vous pouvez ajuster la stratégie d'utilisation de valeurs de
|
|
l'<literal>Exemple</literal>.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[Example example = Example.create(cat)
|
|
.excludeZeroes() //exclude zero valued properties
|
|
.excludeProperty("color") //exclude the property named "color"
|
|
.ignoreCase() //perform case insensitive string comparisons
|
|
.enableLike(); //use like for string comparisons
|
|
List results = session.createCriteria(Cat.class)
|
|
.add(example)
|
|
.list();]]></programlisting>
|
|
|
|
<para>
|
|
Vous pouvez utiliser les "exemples" pour des critères sur les objets associés.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[List results = session.createCriteria(Cat.class)
|
|
.add( Example.create(cat) )
|
|
.createCriteria("mate")
|
|
.add( Example.create( cat.getMate() ) )
|
|
.list();]]></programlisting>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="querycriteria-projection">
|
|
<title>Projections, agrégation et regroupement</title>
|
|
<para>
|
|
La classe <literal>org.hibernate.criterion.Projections</literal> est une
|
|
fabrique d'instances de <literal>Projection</literal>. Nous appliquons une
|
|
projection sur une requête en appelant <literal>setProjection()</literal>.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[List results = session.createCriteria(Cat.class)
|
|
.setProjection( Projections.rowCount() )
|
|
.add( Restrictions.eq("color", Color.BLACK) )
|
|
.list();]]></programlisting>
|
|
|
|
<programlisting><![CDATA[List results = session.createCriteria(Cat.class)
|
|
.setProjection( Projections.projectionList()
|
|
.add( Projections.rowCount() )
|
|
.add( Projections.avg("weight") )
|
|
.add( Projections.max("weight") )
|
|
.add( Projections.groupProperty("color") )
|
|
)
|
|
.list();]]></programlisting>
|
|
|
|
<para>
|
|
Il n'y a pas besoin de "group by" explicite dans une requête par critère.
|
|
Certains types de projection sont définis pour être des <emphasis>projections
|
|
de regroupement</emphasis>, lesquels apparaissent aussi dans la clause
|
|
<literal>group by</literal> SQL.
|
|
</para>
|
|
|
|
<para>
|
|
Un alias peut optionnellement être assigné à une projection, ainsi la valeur
|
|
projetée peut être référencée dans des restrictions ou des tris. Voici deux façons
|
|
différentes de faire ça :
|
|
</para>
|
|
|
|
<programlisting><![CDATA[List results = session.createCriteria(Cat.class)
|
|
.setProjection( Projections.alias( Projections.groupProperty("color"), "colr" ) )
|
|
.addOrder( Order.asc("colr") )
|
|
.list();]]></programlisting>
|
|
|
|
<programlisting><![CDATA[List results = session.createCriteria(Cat.class)
|
|
.setProjection( Projections.groupProperty("color").as("colr") )
|
|
.addOrder( Order.asc("colr") )
|
|
.list();]]></programlisting>
|
|
|
|
<para>
|
|
Les méthodes <literal>alias()</literal> et <literal>as()</literal> enveloppe simplement
|
|
une instance de projection dans une autre instance (aliasée) de <literal>Projection</literal>.
|
|
Comme un raccourci, vous pouvez assignez un alias lorsque vous ajoutez la projection à la
|
|
liste de projections :
|
|
</para>
|
|
|
|
<programlisting><![CDATA[List results = session.createCriteria(Cat.class)
|
|
.setProjection( Projections.projectionList()
|
|
.add( Projections.rowCount(), "catCountByColor" )
|
|
.add( Projections.avg("weight"), "avgWeight" )
|
|
.add( Projections.max("weight"), "maxWeight" )
|
|
.add( Projections.groupProperty("color"), "color" )
|
|
)
|
|
.addOrder( Order.desc("catCountByColor") )
|
|
.addOrder( Order.desc("avgWeight") )
|
|
.list();]]></programlisting>
|
|
|
|
<programlisting><![CDATA[List results = session.createCriteria(Domestic.class, "cat")
|
|
.createAlias("kittens", "kit")
|
|
.setProjection( Projections.projectionList()
|
|
.add( Projections.property("cat.name"), "catName" )
|
|
.add( Projections.property("kit.name"), "kitName" )
|
|
)
|
|
.addOrder( Order.asc("catName") )
|
|
.addOrder( Order.asc("kitName") )
|
|
.list();]]></programlisting>
|
|
|
|
<para>
|
|
Vous pouvez aussi utiliser <literal>Property.forName()</literal> pour formuler des projections :
|
|
</para>
|
|
|
|
<programlisting><![CDATA[List results = session.createCriteria(Cat.class)
|
|
.setProjection( Property.forName("name") )
|
|
.add( Property.forName("color").eq(Color.BLACK) )
|
|
.list();]]></programlisting>
|
|
|
|
<programlisting><![CDATA[List results = session.createCriteria(Cat.class)
|
|
.setProjection( Projections.projectionList()
|
|
.add( Projections.rowCount().as("catCountByColor") )
|
|
.add( Property.forName("weight").avg().as("avgWeight") )
|
|
.add( Property.forName("weight").max().as("maxWeight") )
|
|
.add( Property.forName("color").group().as("color" )
|
|
)
|
|
.addOrder( Order.desc("catCountByColor") )
|
|
.addOrder( Order.desc("avgWeight") )
|
|
.list();]]></programlisting>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="querycriteria-detachedqueries">
|
|
<title>Requêtes et sous-requêtes détachées</title>
|
|
<para>
|
|
La classe <literal>DetachedCriteria</literal> vous laisse créer une requête en dehors de la
|
|
portée de la session, et puis l'exécuter plus tard en utilisant n'importe quelle <literal>Session</literal>
|
|
arbitraire.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[DetachedCriteria query = DetachedCriteria.forClass(Cat.class)
|
|
.add( Property.forName("sex").eq('F') );
|
|
|
|
Session session = ....;
|
|
Transaction txn = session.beginTransaction();
|
|
List results = query.getExecutableCriteria(session).setMaxResults(100).list();
|
|
txn.commit();
|
|
session.close();]]></programlisting>
|
|
|
|
<para>
|
|
Une <literal>DetachedCriteria</literal> peut aussi être utilisée pour exprimer une
|
|
sous-requête. Des instances de criterion impliquant des sous-requêtes peuvent être
|
|
obtenues via <literal>Subqueries</literal> ou <literal>Property</literal>.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[DetachedCriteria avgWeight = DetachedCriteria.forClass(Cat.class)
|
|
.setProjection( Property.forName("weight").avg() );
|
|
session.createCriteria(Cat.class)
|
|
.add( Property.forName("weight).gt(avgWeight) )
|
|
.list();]]></programlisting>
|
|
|
|
<programlisting><![CDATA[DetachedCriteria weights = DetachedCriteria.forClass(Cat.class)
|
|
.setProjection( Property.forName("weight") );
|
|
session.createCriteria(Cat.class)
|
|
.add( Subqueries.geAll("weight", weights) )
|
|
.list();]]></programlisting>
|
|
|
|
<para>
|
|
Même des requêtes corrélées sont possibles :
|
|
</para>
|
|
|
|
<programlisting><![CDATA[DetachedCriteria avgWeightForSex = DetachedCriteria.forClass(Cat.class, "cat2")
|
|
.setProjection( Property.forName("weight").avg() )
|
|
.add( Property.forName("cat2.sex").eqProperty("cat.sex") );
|
|
session.createCriteria(Cat.class, "cat")
|
|
.add( Property.forName("weight).gt(avgWeightForSex) )
|
|
.list();]]></programlisting>
|
|
|
|
</sect1>
|
|
|
|
<!--TODO: ResultSetTransformer + aliasing. AliasToBeanTransformer allow returning arbitrary
|
|
user objects - similar to setResultClass in JDO2. General use of ResultTransformer
|
|
could also be explained. -->
|
|
|
|
<sect1 id="query-criteria-naturalid">
|
|
<title>Requêtes par identifiant naturel</title>
|
|
|
|
<para>
|
|
Pour la plupart des requêtes, incluant les requêtes par critère, le cache de requêtes
|
|
n'est pas très efficace, parce que l'invalidation du cache de requêtes arrive trop
|
|
souvent. Cependant, il y a une sorte spéciale de requête où nous pouvons optimiser
|
|
l'algorithme d'invalidation du cache : les recherches sur une clef naturelle constante.
|
|
Dans certaines applications, cette sorte de requête se produit fréquemment. L'API de
|
|
critère fournit une provision spéciale pour ce cas d'utilisation.
|
|
</para>
|
|
|
|
<para>
|
|
D'abord vous devriez mapper la clef naturelle de votre entité en utilisant
|
|
<literal><natural-id></literal>, et activer l'utilisation du cache de second niveau.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[<class name="User">
|
|
<cache usage="read-write"/>
|
|
<id name="id">
|
|
<generator class="increment"/>
|
|
</id>
|
|
<natural-id>
|
|
<property name="name"/>
|
|
<property name="org"/>
|
|
</natural-id>
|
|
<property name="password"/>
|
|
</class>]]></programlisting>
|
|
|
|
<para>
|
|
Notez que cette fonctionnalité n'est pas prévue pour l'utilisation avec des
|
|
entités avec des clefs naturelles <emphasis>mutables</emphasis>.
|
|
</para>
|
|
|
|
<para>
|
|
Ensuite, activez le cache de requête d'Hibernate.
|
|
</para>
|
|
|
|
<para>
|
|
Maintenant <literal>Restrictions.naturalId()</literal> nous permet de rendre
|
|
l'utilisation de l'algorithme de cache plus efficace.
|
|
</para>
|
|
|
|
<programlisting><![CDATA[session.createCriteria(User.class)
|
|
.add( Restrictions.naturalId()
|
|
.set("name", "gavin")
|
|
.set("org", "hb")
|
|
).setCacheable(true)
|
|
.uniqueResult();]]></programlisting>
|
|
|
|
</sect1>
|
|
|
|
</chapter>
|