hibernate-orm/doc/reference/fr/modules/query_sql.xml

751 lines
31 KiB
XML

<?xml version="1.0" encoding="ISO-8859-1"?>
<chapter id="querysql" revision="2">
<title>SQL natif</title>
<para>
Vous pouvez aussi écrire vos requêtes dans le dialecte SQL natif de votre base de données.
Ceci est utile si vous souhaitez utiliser les fonctionnalités spécifiques de votre base de
données comme le mot clé <literal>CONNECT</literal> d'Oracle. Cette fonctionnalité offre par ailleurs un moyen
de migration plus propre et doux d'une application basée sur SQL/JDBC vers
une application Hibernate.
</para>
<para>Hibernate3 vous permet de spécifier du SQL écrit à la main (incluant les procédures stockées)
pour toutes les opérations de création, mise à jour, suppression et chargement.</para>
<sect1 id="querysql-creating" revision="4">
<title>Utiliser une <literal>SQLQuery</literal></title>
<para>L'exécution des requêtes en SQL natif est contrôlée par l'interface <literal>SQLQuery</literal>,
laquelle est obtenue en appelant <literal>Session.createSQLQuery()</literal>.
Dans des cas extrêmement simples, nous pouvons utiliser la forme suivante :
</para>
<sect2>
<title>Requêtes scalaires</title>
<para>La requête SQL la plus basique permet de récupérer une liste de (valeurs) scalaires.</para>
<programlisting><![CDATA[sess.createSQLQuery("SELECT * FROM CATS").list();
sess.createSQLQuery("SELECT ID, NAME, BIRTHDATE FROM CATS").list();
]]></programlisting>
<para>Ces deux requêtes retourneront un tableau d'objets (Object[]) avec
les valeurs scalaires de chacune des colonnes de la table CATS.
Hibernate utilisera le ResultSetMetadata pour déduire l'ordre et le type
des valeurs scalaires retournées.</para>
<para>Pour éviter l'overhead lié à <literal>ResultSetMetadata</literal> ou simplement pour
être plus explicite dans ce qui est retourné, vous pouvez utiliser <literal>addScalar()</literal>.</para>
<programlisting><![CDATA[sess.createSQLQuery("SELECT * FROM CATS")
.addScalar("ID", Hibernate.LONG)
.addScalar("NAME", Hibernate.STRING)
.addScalar("BIRTHDATE", Hibernate.DATE)
]]></programlisting>
<para>Cette requête spécifie:</para>
<itemizedlist>
<listitem>
<para>la chaîne de caractère SQL</para>
</listitem>
<listitem>
<para>les colonnes et les types retournés</para>
</listitem>
</itemizedlist>
<para>Cela retournera toujours un tableau d'objets, mais sans utiliser le
<literal>ResultSetMetdata</literal>, mais récupèrera explicitement les colonnes
ID, NAME and BIRTHDATE column étant de respectivement de type Long, String et Short,
depuis le resultset sous jacent. Cela signifie aussi que seules ces colonnes seront
retournées même si la requête utilise <literal>*</literal>
et aurait pu retourner plus que les trois colonnes listées.</para>
<para>Il est possible de ne pas définir l'information sur le type pour toutes ou partie
des calaires.</para>
<programlisting><![CDATA[sess.createSQLQuery("SELECT * FROM CATS")
.addScalar("ID", Hibernate.LONG)
.addScalar("NAME")
.addScalar("BIRTHDATE")
]]></programlisting>
<para>Il s'agit essentiellement de la même requête que précédemment, mais
le <literal>ResultSetMetaData</literal> est utilisé pour décider des types de NAME
et BIRTHDATE alors que le type de ID est explicitement spécifié.</para>
<para>Les java.sql.Types retournés par le ResultSetMetaData sont mappés aux type Hibernate
via le Dialect. Si un type spécifique n'est pas mappé ou est mappé à un type non souhaité, il
est possible de personnaliser en invoquant <literal>registerHibernateType</literal> dans
le Dialect.</para>
</sect2>
<sect2>
<title>Requêtes d'entités</title>
<para>Les requêtes précédentes ne retournaient que des valeurs scalaires,
retournant basiquement que les valeurs brutes du resultset. Ce qui suit montre
comment récupérer des entités depuis une requête native SQL, grâce à
<literal>addEntity()</literal>.</para>
<programlisting><![CDATA[sess.createSQLQuery("SELECT * FROM CATS").addEntity(Cat.class);
sess.createSQLQuery("SELECT ID, NAME, BIRTHDATE FROM CATS").addEntity(Cat.class);
]]></programlisting>
<para>Cette requête spécifie:</para>
<itemizedlist>
<listitem>
<para>La chaîne de caractère de requête SQL</para>
</listitem>
<listitem>
<para>L'entité retournée par la requête</para>
</listitem>
</itemizedlist>
<para>Avec Cat mappé comme classe avec les colonnes ID, NAME
et BIRTHDATE, les requêtes précédentes retournent toutes deux une liste
où chaque élément est une entité Cat.</para>
<para>Si l'entité est mappée avec un <literal>many-to-one</literal> vers
une autre entité, il est requis de retourner aussi cette entité en exécutant
la requête native, sinon une erreur "column not found" spécifique à la base de
données sera soulevée. Les colonnes additionnelles seront automatiquement
retournées en utilisant la notation *, mais nous préférons être explicites
comme dans l'exemple suivant avec le <literal>many-to-one</literal> vers
<literal>Dog</literal>:</para>
<programlisting><![CDATA[sess.createSQLQuery("SELECT ID, NAME, BIRTHDATE, DOG_ID FROM CATS").addEntity(Cat.class);
]]></programlisting>
<para>Ceci permet à cat.getDog() de fonctionner normalement.</para>
</sect2>
<sect2>
<title>Gérer les associations et collections</title>
<para>Il est possible de charger agressivement <literal>Dog</literal> pour
éviter le chargement de proxy qui signifie aller retour supplémentaire vers
la base de données. Ceci est faisable via la méthode <literal>addJoin()</literal>,
qui vous permet de joindre une association ou collection.</para>
<programlisting><![CDATA[sess.createSQLQuery("SELECT c.ID, NAME, BIRTHDATE, DOG_ID, D_ID, D_NAME FROM CATS c, DOGS d WHERE c.DOG_ID = d.D_ID")
.addEntity("cat", Cat.class)
.addJoin("cat.dog");
]]></programlisting>
<para>Dans cet exemple, les <literal>Cat</literal> retournés auront leur
propriété <literal>dog</literal> entièrement initialisées sans aucun aller/retour
supplémentaire vers la base de données. Notez que nous avons ajouté un alias
("cat") pour être capable de spécifier la propriété cible de la jointure.
Il est possible de faire la même jointure aggressive pour les collections, e.g. si le
<literal>Cat</literal> a un one-to-many vers <literal>Dog</literal>.</para>
<programlisting><![CDATA[sess.createSQLQuery("SELECT ID, NAME, BIRTHDATE, D_ID, D_NAME, CAT_ID FROM CATS c, DOGS d WHERE c.ID = d.CAT_ID")
.addEntity("cat", Cat.class)
.addJoin("cat.dogs");
]]></programlisting>
<p>Nous arrivons aux limites de ce qui est possible avec les requêtes natives
sans les modifier pour les rendre utilisables par Hibernate; les problèmes
surviennent lorsque nous essayons de retourner des entités du même type ou
lorsque les alias/colonnes par défaut ne sont plus suffisants..</p>
</sect2>
<sect2>
<title>Retour d'entités multiples</title>
<para>Jusqu'à présent, les colonnes du resultset sont supposées être les mêmes
que les colonnes spécifiées dans les fichiers de mapping. Ceci peut
être problématique pour les requêtes SQL qui effectuent de multiples
jointures vers différentes tables, puisque les mêmes colonnes peuvent
apparaître dans plus d'une table.</para>
<para>L'injection d'alias de colonne est requis pour la requête suivante
(qui risque de ne pas fonctionner):</para>
<programlisting><![CDATA[sess.createSQLQuery("SELECT c.*, m.* FROM CATS c, CATS m WHERE c.MOTHER_ID = c.ID")
.addEntity("cat", Cat.class)
.addEntity("mother", Cat.class)
]]></programlisting>
<para>Le but de cette requête est de retourner deux instances de Cat par ligne,
un chat et sa mère. Cela échouera puisqu'il y a conflit de nom puisqu'ils sont
mappés au même nom de colonne et que sur certaines base de données, les alias
de colonnes retournés seront plutôt de la forme
"c.ID", "c.NAME", etc. qui ne sont pas égaux aux colonnes spécifiées dans les
mappings ("ID" and "NAME").</para>
<para>La forme suivante n'est pas vulnérable à la duplication des noms de colonnes:</para>
<programlisting><![CDATA[sess.createSQLQuery("SELECT {cat.*}, {mother.*} FROM CATS c, CATS m WHERE c.MOTHER_ID = c.ID")
.addEntity("cat", Cat.class)
.addEntity("mother", Cat.class)
]]></programlisting>
<para>Cette requête spécifie:</para>
<itemizedlist>
<listitem>
<para>la requête SQL, avec des réceptacles pour qu'Hibernate injecte les alias de colonnes</para>
</listitem>
<listitem>
<para>les entités retournés par la requête</para>
</listitem>
</itemizedlist>
<para>Les notations {cat.*} et {mother.*} utilisées sont un équivalent à 'toutes les propriétés'.
Alternativement, vous pouvez lister les colonnes explicitement, mais même pour ce cas, nous
laissons Hibernate injecter les alias de colonne pour chaque propriété.
Le réceptable pour un alias de colonne est simplement le nom de la propriété
qualifié par l'alias de la table. Dans l'exemple suivant, nous récupérons
les chats et leur mère depuis une table différentes (cat_log) de celle déclarée
dans les mappings. Notez que nous pouvons aussi utiliser les alias de propriété
dans la clause where si nous le voulons.</para>
<programlisting><![CDATA[String sql = "SELECT ID as {c.id}, NAME as {c.name}, " +
"BIRTHDATE as {c.birthDate}, MOTHER_ID as {c.mother}, {mother.*} " +
"FROM CAT_LOG c, CAT_LOG m WHERE {c.mother} = c.ID";
List loggedCats = sess.createSQLQuery(sql)
.addEntity("cat", Cat.class)
.addEntity("mother", Cat.class).list()
]]></programlisting>
<sect3 id="querysql-aliasreferences" revision="2">
<title>Références d'alias et de propriété</title>
<para>Pour la plupart des cas précédents, l'injection d'alias est requis,
mais pour les requêtes relatives à des mappings plus complexes, comme
les propriétés composite, les discriminants d'héritage, les collections etc., il
y a des alias spécifiques à utiliser pour permettre à Hibernate l'injection
des bons alias.</para>
<para>Le tableau suivant montre les diverses possiblités d'utilisation
d'injection d'alias. Note: les noms d'alias dans le résultat sont des
exemples, chaque alias aura un nom unique et probablement différent lorsqu'ils
seront utilisés.</para>
<table frame="topbot" id="aliasinjection-summary">
<title>Nom d'injection d'alias</title>
<tgroup cols="3">
<colspec colwidth="1*" />
<colspec colwidth="1*" />
<colspec colwidth="2.5*" />
<thead>
<row>
<entry>Description</entry>
<entry>Syntaxe</entry>
<entry>Exemple</entry>
</row>
</thead>
<tbody>
<row>
<entry>Une propriété simple</entry>
<entry><literal>{[aliasname].[propertyname]</literal></entry>
<entry><literal>A_NAME as {item.name}</literal></entry>
</row>
<row>
<entry>Une propriété composite</entry>
<entry><literal>{[aliasname].[componentname].[propertyname]}</literal></entry>
<entry><literal>CURRENCY as {item.amount.currency}, VALUE as
{item.amount.value}</literal></entry>
</row>
<row>
<entry>Discriminateur d'une entité</entry>
<entry><literal>{[aliasname].class}</literal></entry>
<entry><literal>DISC as {item.class}</literal></entry>
</row>
<row>
<entry>Toutes les propriétés d'une entité</entry>
<entry><literal>{[aliasname].*}</literal></entry>
<entry><literal>{item.*}</literal></entry>
</row>
<row>
<entry>La clé d'une collection</entry>
<entry><literal>{[aliasname].key}</literal></entry>
<entry><literal>ORGID as {coll.key}</literal></entry>
</row>
<row>
<entry>L'id d'une collection</entry>
<entry><literal>{[aliasname].id}</literal></entry>
<entry><literal>EMPID as {coll.id}</literal></entry>
</row>
<row>
<entry>L'élément d'une collection</entry>
<entry><literal>{[aliasname].element}</literal></entry>
<entry><literal>XID as {coll.element}</literal></entry>
</row>
<row>
<entry>Propriété d'un élément de collection</entry>
<entry><literal>{[aliasname].element.[propertyname]}</literal></entry>
<entry><literal>NAME as {coll.element.name}</literal></entry>
</row>
<row>
<entry>Toutes les propriétés d'un élément de collection</entry>
<entry><literal>{[aliasname].element.*}</literal></entry>
<entry><literal>{coll.element.*}</literal></entry>
</row>
<row>
<entry>Toutes les propriétés d'une collection</entry>
<entry><literal>{[aliasname].*}</literal></entry>
<entry><literal>{coll.*}</literal></entry>
</row>
</tbody>
</tgroup>
</table>
</sect3>
</sect2>
<sect2>
<title>Retour d'objet n'étant pas des entités</title>
<para>Il est possible d'appliquer un ResultTransformer à une requête native SQL. Ce qui permet, par exemple, de
retourner des entités non gérées.</para>
<programlisting><![CDATA[sess.createSQLQuery("SELECT NAME, BIRTHDATE FROM CATS")
.setResultTransformer(Transformers.aliasToBean(CatDTO.class))]]></programlisting>
<para>Cette requête spécifie:</para>
<itemizedlist>
<listitem>
<para>une requête SQL</para>
</listitem>
<listitem>
<para>un transformateur de résultat</para>
</listitem>
</itemizedlist>
<para>
La requête précédente retournera une liste de <literal>CatDTO</literal> qui auront été instanciés
et dans lesquelles les valeurs de NAME et BIRTHNAME auront été injectées dans les propriétés ou champs
correspondants.
</para>
</sect2>
<sect2>
<title>Gérer l'héritage</title>
<para>Les requêtes natives SQL pour les entités prenant part à un héritage
doivent inclure toutes les propriétés de la classe de base et de toutes
ses sous classes.</para>
</sect2>
<sect2>
<title>Paramètres</title>
<para>Les requêtes natives SQL supportent aussi les paramètres nommés:</para>
<programlisting><![CDATA[Query query = sess.createSQLQuery("SELECT * FROM CATS WHERE NAME like ?").addEntity(Cat.class);
List pusList = query.setString(0, "Pus%").list();
query = sess.createSQLQuery("SELECT * FROM CATS WHERE NAME like :name").addEntity(Cat.class);
List pusList = query.setString("name", "Pus%").list(); ]]></programlisting>
</sect2>
</sect1>
<sect1 id="querysql-namedqueries" revision="3">
<title>Requêtes SQL nommées</title>
<para>
Les requêtes SQL nommées peuvent être définies dans le document de mapping
et appelées exactement de la même manière qu'un requête HQL nommée. Dans ce
cas, nous <emphasis>n'avons pas besoin</emphasis> d'appeler <literal>addEntity()</literal>.
</para>
<programlisting>&lt;sql-query name="persons"&gt;
&lt;return alias="person" class="eg.Person"/&gt;
SELECT person.NAME AS {person.name},
person.AGE AS {person.age},
person.SEX AS {person.sex}
FROM PERSON person
WHERE person.NAME LIKE :namePattern
&lt;/sql-query&gt;</programlisting>
<programlisting>List people = sess.getNamedQuery("persons")
.setString("namePattern", namePattern)
.setMaxResults(50)
.list();</programlisting>
<para>
Les éléments <literal>&lt;return-join&gt;</literal> et
<literal>&lt;load-collection&gt;</literal> sont respectivement utilisés pour lier
des associations et définir des requêtes qui initialisent des collections.
</para>
<programlisting>&lt;sql-query name="personsWith"&gt;
&lt;return alias="person" class="eg.Person"/&gt;
&lt;return-join alias="address" property="person.mailingAddress"/&gt;
SELECT person.NAME AS {person.name},
person.AGE AS {person.age},
person.SEX AS {person.sex},
adddress.STREET AS {address.street},
adddress.CITY AS {address.city},
adddress.STATE AS {address.state},
adddress.ZIP AS {address.zip}
FROM PERSON person
JOIN ADDRESS adddress
ON person.ID = address.PERSON_ID AND address.TYPE='MAILING'
WHERE person.NAME LIKE :namePattern
&lt;/sql-query&gt;</programlisting>
<para>
Une requête SQL nommée peut retourner une valeur scalaire. Vous devez
spécifier l'alias de colonne et le type Hibernate utilisant l'élément
<literal>&lt;return-scalar&gt;</literal> :</para>
<programlisting>&lt;sql-query name="mySqlQuery"&gt;
&lt;return-scalar column="name" type="string"/&gt;
&lt;return-scalar column="age" type="long"/&gt;
SELECT p.NAME AS name,
p.AGE AS age,
FROM PERSON p WHERE p.NAME LIKE 'Hiber%'
&lt;/sql-query&gt;</programlisting>
<para>
Vous pouvez externaliser les informations de mapping des résultats dans un
élément <literal>&lt;resultset&gt;</literal> pour soit les réutiliser
dans différentes requêtes nommées, soit à travers l'API
<literal>setResultSetMapping()</literal>.
</para>
<programlisting>&lt;resultset name="personAddress"&gt;
&lt;return alias="person" class="eg.Person"/&gt;
&lt;return-join alias="address" property="person.mailingAddress"/&gt;
&lt;/resultset&gt;
&lt;sql-query name="personsWith" resultset-ref="personAddress"&gt;
SELECT person.NAME AS {person.name},
person.AGE AS {person.age},
person.SEX AS {person.sex},
adddress.STREET AS {address.street},
adddress.CITY AS {address.city},
adddress.STATE AS {address.state},
adddress.ZIP AS {address.zip}
FROM PERSON person
JOIN ADDRESS adddress
ON person.ID = address.PERSON_ID AND address.TYPE='MAILING'
WHERE person.NAME LIKE :namePattern
&lt;/sql-query&gt;</programlisting>
<sect2 id="propertyresults">
<title>Utilisation de return-property pour spécifier explicitement les noms des colonnes/alias</title>
<para>
Avec <literal>&lt;return-property&gt;</literal> vous pouvez explicitement dire
à Hibernate quels alias de colonne utiliser, plutot que d'employer la syntaxe
<literal>{}</literal> pour laisser Hibernate injecter ses propres alias.
</para>
<programlisting>&lt;sql-query name="mySqlQuery"&gt;
&lt;return alias="person" class="eg.Person"&gt;
&lt;return-property name="name" column="myName"/&gt;
&lt;return-property name="age" column="myAge"/&gt;
&lt;return-property name="sex" column="mySex"/&gt;
&lt;/return&gt;
SELECT person.NAME AS myName,
person.AGE AS myAge,
person.SEX AS mySex,
FROM PERSON person WHERE person.NAME LIKE :name
&lt;/sql-query&gt;
</programlisting>
<para>
<literal>&lt;return-property&gt;</literal> fonctionne aussi avec de
multiple colonnes. Cela résout une limitation de la syntaxe <literal>{}</literal>
qui ne peut pas permettre une bonne granularité des propriétés multi-colonnes.
</para>
<programlisting>&lt;sql-query name="organizationCurrentEmployments"&gt;
&lt;return alias="emp" class="Employment"&gt;
&lt;return-property name="salary"&gt;
&lt;return-column name="VALUE"/&gt;
&lt;return-column name="CURRENCY"/&gt;
&lt;/return-property&gt;
&lt;return-property name="endDate" column="myEndDate"/&gt;
&lt;/return&gt;
SELECT EMPLOYEE AS {emp.employee}, EMPLOYER AS {emp.employer},
STARTDATE AS {emp.startDate}, ENDDATE AS {emp.endDate},
REGIONCODE as {emp.regionCode}, EID AS {emp.id}, VALUE, CURRENCY
FROM EMPLOYMENT
WHERE EMPLOYER = :id AND ENDDATE IS NULL
ORDER BY STARTDATE ASC
&lt;/sql-query&gt;</programlisting>
<para>
Notez que dans cet exemple nous avons utilisé <literal>&lt;return-property&gt;</literal>
en combinaison avec la syntaxe <literal>{}</literal> pour l'injection. Cela autorise les
utilisateurs à choisir comment ils veulent référencer les colonnes et les propriétés.
</para>
<para>
Si votre mapping a un discriminant vous devez utiliser
<literal>&lt;return-discriminator&gt;</literal> pour spécifier la colonne
discriminante.
</para>
</sect2>
<sect2 id="sp_query" revision="1">
<title>Utilisation de procédures stockées pour les requêtes</title>
<para>
Hibernate 3 introduit le support des requêtes via procédures stockées et les fonctions.
La documentation suivante est valable pour les deux.
Les procédures stockées/fonctions doivent retourner l'ensemble de résultats en tant que
premier paramètre sortant (NdT: "out-parameter") pour être capable de fonctionner
avec Hibernate. Un exemple d'une telle procédure stockée en Oracle 9 et
version supérieure :
</para>
<programlisting>CREATE OR REPLACE FUNCTION selectAllEmployments
RETURN SYS_REFCURSOR
AS
st_cursor SYS_REFCURSOR;
BEGIN
OPEN st_cursor FOR
SELECT EMPLOYEE, EMPLOYER,
STARTDATE, ENDDATE,
REGIONCODE, EID, VALUE, CURRENCY
FROM EMPLOYMENT;
RETURN st_cursor;
END;</programlisting>
<para>Pour utiliser cette requête dans Hibernate vous avez besoin de la mapper via une requête nommée.</para>
<programlisting>&lt;sql-query name="selectAllEmployees_SP" callable="true"&gt;
&lt;return alias="emp" class="Employment"&gt;
&lt;return-property name="employee" column="EMPLOYEE"/&gt;
&lt;return-property name="employer" column="EMPLOYER"/&gt;
&lt;return-property name="startDate" column="STARTDATE"/&gt;
&lt;return-property name="endDate" column="ENDDATE"/&gt;
&lt;return-property name="regionCode" column="REGIONCODE"/&gt;
&lt;return-property name="id" column="EID"/&gt;
&lt;return-property name="salary"&gt;
&lt;return-column name="VALUE"/&gt;
&lt;return-column name="CURRENCY"/&gt;
&lt;/return-property&gt;
&lt;/return&gt;
{ ? = call selectAllEmployments() }
&lt;/sql-query&gt;</programlisting>
<para>
Notez que les procédures stockées retournent, pour le moment, seulement des
scalaires et des entités. <literal>&lt;return-join&gt;</literal> et
<literal>&lt;load-collection&gt;</literal> ne sont pas supportés.
</para>
<sect3 id="querysql-limits-storedprocedures" revision="1">
<title>Règles/limitations lors de l'utilisation des procédures stockées</title>
<para>
Pur utiliser des procédures stockées avec Hibernate, les procédures doivent
suivre certaines règles. Si elles ne suivent pas ces règles, elles ne sont pas
utilisables avec Hibernate. Si vous voulez encore utiliser ces procédures vous
devez les exécuter via <literal>session.connection()</literal>. Les règles
sont différentes pour chaque base de données, puisque les vendeurs de base
de données ont des sémantiques/syntaxes différentes pour les procédures stockées.
</para>
<para>Les requêtes de procédures stockées ne peuvent pas être paginées avec
<literal>setFirstResult()/setMaxResults()</literal>.</para>
<para>Pour Oracle les règles suivantes s'appliquent :</para>
<itemizedlist spacing="compact">
<listitem>
<para>
La procédure doit retourner un ensemble de résultats. Le
prmeier paramètre d'une procédure doit être un <literal>OUT</literal>
qui retourne un ensemble de résultats. Ceci est fait en
retournant un <literal>SYS_REFCURSOR</literal> dans Oracle 9 ou 10. Dans
Oracle vous avez besoin de définir un type <literal>REF CURSOR</literal>.</para>
</listitem>
</itemizedlist>
<para>Pour Sybase ou MS SQL server les règles suivantes s'appliquent :</para>
<itemizedlist spacing="compact">
<listitem>
<para>La procédure doit retourner un ensemble de résultats. Notez que comme
ces serveurs peuvent retourner de multiples ensembles de résultats et mettre à jour
des compteurs, Hibernate itérera les résultats et prendra le premier résultat qui est
un ensemble de résultat comme valeur de retour. Tout le reste sera ignoré.</para>
</listitem>
<listitem>
<para>Si vous pouvez activer <literal>SET NOCOUNT ON</literal> dans votre procédure,
elle sera probablement plus efficace, mais ce n'est pas une obligation.</para>
</listitem>
</itemizedlist>
</sect3>
</sect2>
</sect1>
<sect1 id="querysql-cud">
<title>SQL personnalisé pour créer, mettre à jour et effacer</title>
<para>
Hibernate3 peut utiliser des expression SQL personnalisées pour des opérations de création,
de mise à jour, et de suppression. Les objets persistants les classes et les collections
dans Hibernate contiennent déjà un ensemble de chaînes de caractères générées lors de la
configuration (insertsql, deletesql, updatesql, etc). Les tages de mapping
<literal>&lt;sql-insert&gt;</literal>,
<literal>&lt;sql-delete&gt;</literal>, et
<literal>&lt;sql-update&gt;</literal> surchargent ces chaînes de caractères :</para>
<programlisting>&lt;class name="Person"&gt;
&lt;id name="id"&gt;
&lt;generator class="increment"/&gt;
&lt;/id&gt;
&lt;property name="name" not-null="true"/&gt;
&lt;sql-insert&gt;INSERT INTO PERSON (NAME, ID) VALUES ( UPPER(?), ? )&lt;/sql-insert&gt;
&lt;sql-update&gt;UPDATE PERSON SET NAME=UPPER(?) WHERE ID=?&lt;/sql-update&gt;
&lt;sql-delete&gt;DELETE FROM PERSON WHERE ID=?&lt;/sql-delete&gt;
&lt;/class&gt;</programlisting>
<para>Le SQL est directement exécuté dans votre base de données, donc vous êtes libre d'utiliser
le dialecte que vous souhaitez. Cela réduira bien sûr la portabilité de votre mapping si vous
utilisez du SQL spécifique à votre base de données.</para>
<para>Les procédures stockées sont supportées si l'attribut <literal>callable</literal> est paramétré :</para>
<programlisting>&lt;class name="Person"&gt;
&lt;id name="id"&gt;
&lt;generator class="increment"/&gt;
&lt;/id&gt;
&lt;property name="name" not-null="true"/&gt;
&lt;sql-insert callable="true"&gt;{call createPerson (?, ?)}&lt;/sql-insert&gt;
&lt;sql-delete callable="true"&gt;{? = call deletePerson (?)}&lt;/sql-delete&gt;
&lt;sql-update callable="true"&gt;{? = call updatePerson (?, ?)}&lt;/sql-update&gt;
&lt;/class&gt;</programlisting>
<para>L'ordre des paramètres positionnels est actuellement vital, car ils doivent être dans la
même séquence qu'Hibernate les attend.</para>
<para>
Vous pouvez voir l'ordre attendu en activant les journaux de debug pour le
niveau <literal>org.hibernate.persister.entity</literal> level. Avec ce niveau activé,
Hibernate imprimera le SQL statique qui est utilisé pour créer, mettre à jour,
supprimer, etc. des entités. (Pour voir la séquence attendue, rappelez-vous de ne pas
inclure votre SQL personnalisé dans les fichiers de mapping de manière à surcharger le
SQL statique généré par Hibernate.)</para>
<para>Les procédures stockées sont dans la plupart des cas (lire : il vaut mieux le faire)
requises pour retourner le nombre de lignes insérées/mises à jour/supprimées, puisque
Hibernate fait quelques vérifications de succès lors de l'exécution de l'expression.
Hibernate inscrit toujours la première expression comme un paramètre de sortie numérique pour les
opérations CUD :</para>
<programlisting>CREATE OR REPLACE FUNCTION updatePerson (uid IN NUMBER, uname IN VARCHAR2)
RETURN NUMBER IS
BEGIN
update PERSON
set
NAME = uname,
where
ID = uid;
return SQL%ROWCOUNT;
END updatePerson;</programlisting>
</sect1>
<sect1 id="querysql-load">
<title>SQL personnalisé pour le chargement</title>
<para>Vous pouvez aussi déclarer vos propres requêtes SQL (ou HQL) pour le chargement d'entité :</para>
<programlisting>&lt;sql-query name="person"&gt;
&lt;return alias="pers" class="Person" lock-mode="upgrade"/&gt;
SELECT NAME AS {pers.name}, ID AS {pers.id}
FROM PERSON
WHERE ID=?
FOR UPDATE
&lt;/sql-query&gt;</programlisting>
<para>Ceci est juste une déclaration de requête nommée, comme vu plus tôt. Vous pouvez référencer
cette requête nommée dans un mapping de classe :</para>
<programlisting>&lt;class name="Person"&gt;
&lt;id name="id"&gt;
&lt;generator class="increment"/&gt;
&lt;/id&gt;
&lt;property name="name" not-null="true"/&gt;
&lt;loader query-ref="person"/&gt;
&lt;/class&gt;</programlisting>
<para>Ceci fonctionne même avec des procédures stockées.</para>
<para>Vous pouvez même définir une requête pour le chargement d'une collection :</para>
<programlisting>&lt;set name="employments" inverse="true"&gt;
&lt;key/&gt;
&lt;one-to-many class="Employment"/&gt;
&lt;loader query-ref="employments"/&gt;
&lt;/set&gt;</programlisting>
<programlisting>&lt;sql-query name="employments"&gt;
&lt;load-collection alias="emp" role="Person.employments"/&gt;
SELECT {emp.*}
FROM EMPLOYMENT emp
WHERE EMPLOYER = :id
ORDER BY STARTDATE ASC, EMPLOYEE ASC
&lt;/sql-query&gt;</programlisting>
<para>Vous pourriez même définir un chargeur d'entité qui charge une collection par jointure :</para>
<programlisting>&lt;sql-query name="person"&gt;
&lt;return alias="pers" class="Person"/&gt;
&lt;return-join alias="emp" property="pers.employments"/&gt;
SELECT NAME AS {pers.*}, {emp.*}
FROM PERSON pers
LEFT OUTER JOIN EMPLOYMENT emp
ON pers.ID = emp.PERSON_ID
WHERE ID=?
&lt;/sql-query&gt;</programlisting>
</sect1>
</chapter>