hibernate-orm/reference/fr/modules/query_criteria.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<chapter id="querycriteria">
    <title>Requ<EFBFBD>tes par crit<69>res</title>

    <para>
        Hibernate offre une API d'interrogation par crit<69>res intuitive et extensible.
    </para>

    <sect1 id="querycriteria-creating">
        <title>Cr<EFBFBD>er une instance de <literal>Criteria</literal></title>

        <para>
            L'interface <literal>net.sf.hibernate.Criteria</literal> repr<70>sente une requ<71>te sur une
            classe persistente donn<6E>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<69>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<70>-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 <20>tre goup<75>es de mani<6E>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<70>-d<>finis (sous classes de <literal>Restriction</literal>),
            mais l'une d'entre elle particuli<6C>rement utile vous permet de sp<73>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<61>e par l'alias de colonne de l'entit<69>
        que l'on souhaite int<6E>rroger.
        </para>

        <para>
            Une autre approche pour obtenir un criterion est de le r<>cup<75>rer d'une instance de <literal>Property</literal>. 
            Vous pouvez cr<63>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<73>cifier des contraintes sur des entit<69>s li<6C>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 <20>l<EFBFBD>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<63>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<72>es par les deux pr<70>c<EFBFBD>dentes requ<71>tes ne sont <emphasis>pas</emphasis> pr<70>-filtr<74>es
            par les crit<69>res ! Si vous souhaitez r<>cup<75>rer uniquement les kittens qui correspondent <20> 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<6E>re dynamique</title>

        <para>
            Vous pouvez sp<73>ficier au moment de l'ex<65>cution le peuplement d'une association en utilisant
            <literal>setFetchMode()</literal> (c'est-<2D>-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<71>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<EFBFBD>tes par l'exemple</title>

        <para>
            La classe <literal>org.hibernate.criterion.Example</literal> vous permet de
            construire un crit<69>re suivant une instance d'objet donn<6E>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<72>t<EFBFBD>s de type version, identifiant et association sont ignor<6F>es.
       Par d<>faut, les valeurs null sont exclues.
        </para>

        <para>
            Vous pouvez ajuster la strat<61>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<69>res sur les objets associ<63>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<67>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<71>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<71>te par crit<69>re.
            Certains types de projection sont d<>finis pour <20>tre des <emphasis>projections
            de regroupement</emphasis>, lesquels apparaissent aussi dans la clause
            <literal>group by</literal> SQL.
        </para>

        <para>
            Un alias peut optionnellement <20>tre assign<67> <20> une projection, ainsi la valeur
            projet<65>e peut <20>tre r<>f<EFBFBD>renc<6E>e dans des restrictions ou des tris. Voici deux fa<66>ons
            diff<66>rentes de faire <20>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<61>e) de <literal>Projection</literal>.
            Comme un raccourci, vous pouvez assignez un alias lorsque vous ajoutez la projection <20> 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<EFBFBD>tes et sous-requ<71>tes d<>tach<63>es</title>
        <para>
            La classe <literal>DetachedCriteria</literal> vous laisse cr<63>er une requ<71>te en dehors de la
            port<72>e de la session, et puis l'ex<65>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 <20>tre utilis<69>e pour exprimer une
            sous-requ<71>te. Des instances de criterion impliquant des sous-requ<71>tes peuvent <20>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<71>tes corr<72>l<EFBFBD>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<EFBFBD>tes par identifiant naturel</title>

        <para>
            Pour la plupart des requ<71>tes, incluant les requ<71>tes par crit<69>re, le cache de requ<71>tes
            n'est pas tr<74>s efficace, parce que l'invalidation du cache de requ<71>tes arrive trop
            souvent. Cependant, il y a une sorte sp<73>ciale de requ<71>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<71>te se produit fr<66>quemment. L'API de
            crit<69>re fournit une provision sp<73>ciale pour ce cas d'utilisation.
        </para>

        <para>
            D'abord vous devriez mapper la clef naturelle de votre entit<69> en utilisant
            <literal>&lt;natural-id&gt;</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<69> n'est pas pr<70>vue pour l'utilisation avec des
            entit<69>s avec des clefs naturelles <emphasis>mutables</emphasis>.
        </para>

        <para>
            Ensuite, activez le cache de requ<71>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>