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

595 lines
26 KiB
XML

<?xml version="1.0" encoding="iso-8859-1"?>
<chapter id="toolsetguide" revision="2">
<title>Guide des outils</title>
<para>
Des outils en ligne de commande, des plugins Eclipse ainsu que des tâches Ant permettent de gérer de cycles de développement complet
de projets utilisant Hibernate.
</para>
<para>
Les <emphasis>outils Hibernate</emphasis> actuels incluent des plugins pour l'IDE Eclipse ainsi que des tâches Ant pour l'ingénierie
inverse de bases de données existantes :
</para>
<itemizedlist>
<listitem><para>
<emphasis>Mapping Editor :</emphasis> un éditeur pour les fichiers de mapping XML Hibernate, supportant l'auto-complétion et la mise en valeur de la syntaxe.
Il supporte aussi l'auto-complétion automatique pour les noms de classes et les noms de propriété/champ,
le rendant beaucoup plus polyvalent qu'un éditeurXML normal.
</para></listitem>
<listitem><para>
<emphasis>Console :</emphasis> la console est une nouvelle vue d'Eclipse. En plus de la vue d'ensemble
arborescente de vos configurations de console, vous obtenez aussi une vue interactive de vos classes persistantes et de leurs relations.
La console vous permet d'exécuter des requête HQL dans votre base de données et de parcourir les résultats directement dans Eclipse.
</para></listitem>
<listitem><para>
<emphasis>Development Wizards :</emphasis> plusieurs assistants sont fournis avec les outils d'Hibernate
pour Eclipse ; vous pouvez utiliser un assistant pour générer rapidement les fichiers de configuration d'Hibernate (cfg.xml),
ou vous pouvez même complètement générer les fichiers de mapping Hibernate et les sources des POJOs à partir d'un schéma de base de données existant.
L'assistant d'ingénierie inverse supporte les modèles utilisateur.
</para></listitem>
<listitem><para>
<emphasis>Tâches Ant :</emphasis>
</para></listitem>
</itemizedlist>
<para>
Veuillez-vous référer au paquet <emphasis>outils Hibernate</emphasis> et sa documentation pour plus d'informations.
</para>
<para>
Pourtant, le paquet principal d'Hibernate arrive avec un lot d'outils intégrés (il peut même être utilisé de "l'intérieur" d'Hibernate à la volée) :
<emphasis>SchemaExport</emphasis> aussi connu comme
<literal>hbm2ddl</literal>.
</para>
<sect1 id="toolsetguide-s1" revision="2">
<title>Génération automatique du schéma</title>
<para>
La DDL peut être générée à partir de vos fichiers de mapping par un utilitaire d'Hibernate. Le schéma généré
inclut les contraintes d'intégrité référentielle (clefs primaires et étrangères) pour les tables d'entités
et de collections. Les tables et les séquences sont aussi créées pour les générateurs d'identifiant mappés.
</para>
<para>
Vous <emphasis>devez</emphasis> spécifier un <literal>Dialect</literal> SQL via la propriété
<literal>hibernate.dialect</literal> lors de l'utilisation de cet outils, puisque la DDL est
fortement dépendante de la base de données.
</para>
<para>
D'abord, personnalisez vos fichiers de mapping pour améliorer le schéma généré.
</para>
<sect2 id="toolsetguide-s1-2" revision="3">
<title>Personnaliser le schéma</title>
<para>
Plusieurs éléments du mapping hibernate définissent des attributs optionnels
nommés <literal>length</literal>, <literal>precision</literal> et <literal>scale</literal>.
Vous pouvez paramétrer la longueur, la précision,... d'une colonne avec ces attributs.
</para>
<programlisting><![CDATA[<property name="zip" length="5"/>]]></programlisting>
<programlisting><![CDATA[<property name="balance" precision="12" scale="2"/>]]></programlisting>
<para>
Certains éléments acceptent aussi un attribut <literal>not-null</literal>
(utilisé pour générer les contraintes de colonnes <literal>NOT NULL</literal>) et
un attribut <literal>unique</literal> (pour générer une contrainte de colonne
<literal>UNIQUE</literal>).
</para>
<programlisting><![CDATA[<many-to-one name="bar" column="barId" not-null="true"/>]]></programlisting>
<programlisting><![CDATA[<element column="serialNumber" type="long" not-null="true" unique="true"/>]]></programlisting>
<para>
Un attribut <literal>unique-key</literal> peut être utilisé pour grouper les colonnes
en une seule contrainte d'unicité. Actuellement, la valeur spécifiée par
l'attribut <literal>unique-key</literal> n'est <emphasis>pas</emphasis> utilisée pour
nommer la contrainte dans le DDL généré, elle sert juste à grouper les colonnes
dans le fichier de mapping.
</para>
<programlisting><![CDATA[<many-to-one name="org" column="orgId" unique-key="OrgEmployeeId"/>
<property name="employeeId" unique-key="OrgEmployee"/>]]></programlisting>
<para>
Un attribut <literal>index</literal> indique le nom d'un index qui sera
créé en utilisant la ou les colonnes mappées. Plusieurs colonnes
peuvent être groupées dans un même index, en spécifiant le même
nom d'index.
</para>
<programlisting><![CDATA[<property name="lastName" index="CustName"/>
<property name="firstName" index="CustName"/>]]></programlisting>
<para>
Un attribut <literal>foreign-key</literal> peut être utilisé pour surcharger le nom
des clés étrangères générées.
</para>
<programlisting><![CDATA[<many-to-one name="bar" column="barId" foreign-key="FKFooBar"/>]]></programlisting>
<para>
Plusieurs éléments de mapping acceptent aussi un élément fils <literal>&lt;column&gt;</literal>.
Ceci est utile pour les type multi-colonnes:
</para>
<programlisting><![CDATA[<property name="name" type="my.customtypes.Name"/>
<column name="last" not-null="true" index="bar_idx" length="30"/>
<column name="first" not-null="true" index="bar_idx" length="20"/>
<column name="initial"/>
</property>]]></programlisting>
<para>
L'attribut <literal>default</literal> vous laisse spécifier une valeur par défaut pour
une colonnes (vous devriez assigner la même valeur à la propriété mappée avant de sauvegarder une nouvelle instance
de la classe mappée).
</para>
<programlisting><![CDATA[<property name="credits" type="integer" insert="false">
<column name="credits" default="10"/>
</property>]]></programlisting>
<programlisting><![CDATA[<version name="version" type="integer" insert="false">
<column name="version" default="0"/>
</property>]]></programlisting>
<para>
L'attribut <literal>sql-type</literal> laisse l'utilisateur surcharger le mapping
par défaut du type Hibernate vers un type SQL.
</para>
<programlisting><![CDATA[<property name="balance" type="float">
<column name="balance" sql-type="decimal(13,3)"/>
</property>]]></programlisting>
<para>
L'attribut <literal>check</literal> permet de spécifier une contrainte de vérification.
</para>
<programlisting><![CDATA[<property name="foo" type="integer">
<column name="foo" check="foo > 10"/>
</property>]]></programlisting>
<programlisting><![CDATA[<class name="Foo" table="foos" check="bar < 100.0">
...
<property name="bar" type="float"/>
</class>]]></programlisting>
<table frame="topbot" id="schemattributes-summary" revision="2">
<title>Summary</title>
<tgroup cols="3">
<colspec colwidth="1*"/>
<colspec colwidth="1*"/>
<colspec colwidth="2.5*"/>
<thead>
<row>
<entry>Attribut</entry>
<entry>Valeur</entry>
<entry>Interprétation</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>length</literal></entry>
<entry>numérique</entry>
<entry>taille d'une colonne</entry>
</row>
<row>
<entry><literal>precision</literal></entry>
<entry>numérique</entry>
<entry>précision décimale de la colonne</entry>
</row>
<row>
<entry><literal>scale</literal></entry>
<entry>numérique</entry>
<entry>scale décimale de la colonne</entry>
</row>
<row>
<entry><literal>not-null</literal></entry>
<entry><literal>true|false</literal></entry>
<entry>spécifie que la colonne doit être non-nulle</entry>
</row>
<row>
<entry><literal>unique</literal></entry>
<entry><literal>true|false</literal></entry>
<entry>spécifie que la colonne doit avoir une contrainte d'unicité</entry>
</row>
<row>
<entry><literal>index</literal></entry>
<entry><literal>index_name</literal></entry>
<entry>spécifie le nom d'un index (multi-colonnes)</entry>
</row>
<row>
<entry><literal>unique-key</literal></entry>
<entry><literal>unique_key_name</literal></entry>
<entry>spécifie le nom d'une contrainte d'unicité multi-colonnes</entry>
</row>
<row>
<entry><literal>foreign-key</literal></entry>
<entry><literal>foreign_key_name</literal></entry>
<entry>
spécifie le nom d'une contrainte de clé étrangère générée pour
une association, utilisez-la avec les éléments de mapping
&lt;one-to-one&gt;, &lt;many-to-one&gt;, &lt;key&gt;, et &lt;many-to-many&gt;
Notez que les extrêmités <literal>inverse="true"</literal>
se seront pas prises en compte par <literal>SchemaExport</literal>.
</entry>
</row>
<row>
<entry><literal>sql-type</literal></entry>
<entry><literal>SQL column_type</literal></entry>
<entry>
surcharge le type par défaut (attribut de
l'élément <literal>&lt;column&gt;</literal> uniquement)
</entry>
</row>
<row>
<entry><literal>default</literal></entry>
<entry>expression SQL</entry>
<entry>
spécifie une valeur par défaut pour la colonne
</entry>
</row>
<row>
<entry><literal>check</literal></entry>
<entry>SQL expression</entry>
<entry>
crée une contrainte de vérification sur la table ou la colonne
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>
L'élément <literal>&lt;comment&gt;</literal> vous permet de spécifier un commentaire pour le schéma généré.
</para>
<programlisting><![CDATA[<class name="Customer" table="CurCust">
<comment>Current customers only</comment>
...
</class>]]></programlisting>
<programlisting><![CDATA[<property name="balance">
<column name="bal">
<comment>Balance in USD</comment>
</column>
</property>]]></programlisting>
<para>
Ceci a pour résultat une expression
<literal>comment on table</literal> ou
<literal>comment on column</literal> dans la DDL générée (où supportée).
</para>
</sect2>
<sect2 id="toolsetguide-s1-3" revision="2">
<title>Exécuter l'outil</title>
<para>
L'outil <literal>SchemaExport</literal> génère un script DDL vers
la sortie standard et/ou exécute les ordres DDL.
</para>
<para>
<literal>java -cp </literal><emphasis>classpath_hibernate</emphasis>
<literal>net.sf.hibernate.tool.hbm2ddl.SchemaExport</literal> <emphasis>options fichiers_de_mapping</emphasis>
</para>
<table frame="topbot">
<title><literal>SchemaExport</literal> Options de la ligne de commande</title>
<tgroup cols="2">
<colspec colwidth="1.5*"/>
<colspec colwidth="2*"/>
<thead>
<row>
<entry>Option</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>--quiet</literal></entry>
<entry>ne pas écrire le script vers la sortie standard</entry>
</row>
<row>
<entry><literal>--drop</literal></entry>
<entry>supprime seuleument les tables</entry>
</row>
<row>
<entry><literal>--create</literal></entry>
<entry>ne créé que les tables</entry>
</row>
<row>
<entry><literal>--text</literal></entry>
<entry>ne pas exécuter sur la base de données</entry>
</row>
<row>
<entry><literal>--output=my_schema.ddl</literal></entry>
<entry>écrit le script ddl vers un fichier</entry>
</row>
<row>
<entry><literal>--naming=eg.MyNamingStrategy</literal></entry>
<entry>sélectionne une <literal>NamingStrategy</literal></entry>
</row>
<row>
<entry><literal>--config=hibernate.cfg.xml</literal></entry>
<entry>lit la configuration Hibernate à partir d'un fichier XML</entry>
</row>
<row>
<entry><literal>--properties=hibernate.properties</literal></entry>
<entry>lit les propriétés de la base de données à partir d'un fichier</entry>
</row>
<row>
<entry><literal>--format</literal></entry>
<entry>formatte proprement le SQL généré dans le script</entry>
</row>
<row>
<entry><literal>--delimiter=x</literal></entry>
<entry>paramètre un délimiteur de fin de ligne pour le script</entry>
</row>
</tbody>
</tgroup>
</table>
<para>
Vous pouvez même intégrer <literal>SchemaExport</literal> dans votre application :
</para>
<programlisting><![CDATA[Configuration cfg = ....;
new SchemaExport(cfg).create(false, true);]]></programlisting>
</sect2>
<sect2 id="toolsetguide-s1-4">
<title>Propriétés</title>
<para>
Les propriétés de la base de données peuvent être spécifiées
</para>
<itemizedlist spacing="compact">
<listitem>
<para>comme propriétés système avec <literal>-D</literal><emphasis>&lt;property&gt;</emphasis></para>
</listitem>
<listitem>
<para>dans <literal>hibernate.properties</literal></para>
</listitem>
<listitem>
<para>dans un fichier de propriétés déclaré avec <literal>--properties</literal></para>
</listitem>
</itemizedlist>
<para>
Les propriétés nécessaires sont :
</para>
<table frame="topbot">
<title>SchemaExport Connection Properties</title>
<tgroup cols="2">
<colspec colwidth="1.5*"/>
<colspec colwidth="2*"/>
<thead>
<row>
<entry>Nom de la propriété</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>hibernate.connection.driver_class</literal></entry>
<entry>classe du driver JDBC</entry>
</row>
<row>
<entry><literal>hibernate.connection.url</literal></entry>
<entry>URL JDBC</entry>
</row>
<row>
<entry><literal>hibernate.connection.username</literal></entry>
<entry>utilisateur de la base de données</entry>
</row>
<row>
<entry><literal>hibernate.connection.password</literal></entry>
<entry>mot de passe de l'utilisateur</entry>
</row>
<row>
<entry><literal>hibernate.dialect</literal></entry>
<entry>dialecte</entry>
</row>
</tbody>
</tgroup>
</table>
</sect2>
<sect2 id="toolsetguide-s1-5">
<title>Utiliser Ant</title>
<para>
Vous pouvez appeler <literal>SchemaExport</literal> depuis votre script
de construction Ant :
</para>
<programlisting><![CDATA[<target name="schemaexport">
<taskdef name="schemaexport"
classname="org.hibernate.tool.hbm2ddl.SchemaExportTask"
classpathref="class.path"/>
<schemaexport
properties="hibernate.properties"
quiet="no"
text="no"
drop="no"
delimiter=";"
output="schema-export.sql">
<fileset dir="src">
<include name="**/*.hbm.xml"/>
</fileset>
</schemaexport>
</target>]]></programlisting>
</sect2>
<sect2 id="toolsetguide-s1-6" revision="2">
<title>Mises à jour incrémentales du schéma</title>
<para>
L'outil <literal>SchemaUpdate</literal> mettra à jour un schéma existant
en effectuant les changement par "incrément".
Notez que <literal>SchemaUpdate</literal> dépends beaucoup de l'API JDBC
metadata, il ne fonctionnera donc pas avec tous les drivers JDBC.
</para>
<para>
<literal>java -cp </literal><emphasis>classpath_hibernate</emphasis>
<literal>net.sf.hibernate.tool.hbm2ddl.SchemaUpdate</literal> <emphasis>options fichiers_de_mapping</emphasis>
</para>
<table frame="topbot">
<title><literal>SchemaUpdate</literal> Options de ligne de commande</title>
<tgroup cols="2">
<colspec colwidth="1.5*"/>
<colspec colwidth="2*"/>
<thead>
<row>
<entry>Option</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>--quiet</literal></entry>
<entry>ne pas écrire vers la sortie standard</entry>
</row>
<row>
<entry><literal>--text</literal></entry>
<entry>ne pas exporter vers la base de données</entry>
</row>
<row>
<entry><literal>--naming=eg.MyNamingStrategy</literal></entry>
<entry>choisit une <literal>NamingStrategy</literal></entry>
</row>
<row>
<entry><literal>--properties=hibernate.properties</literal></entry>
<entry>lire les propriétés de la base de données à partir d'un fichier</entry>
</row>
</tbody>
</tgroup>
</table>
<para>
Vous pouvez intégrer <literal>SchemaUpdate</literal> dans votre application :
</para>
<programlisting><![CDATA[Configuration cfg = ....;
new SchemaUpdate(cfg).execute(false);]]></programlisting>
</sect2>
<sect2 id="toolsetguide-s1-7">
<title>Utiliser Ant pour des mises à jour de schéma par incrément</title>
<para>
Vous pouvez appeler <literal>SchemaUpdate</literal> depuis le script Ant :
</para>
<programlisting><![CDATA[<target name="schemaupdate">
<taskdef name="schemaupdate"
classname="org.hibernate.tool.hbm2ddl.SchemaUpdateTask"
classpathref="class.path"/>
<schemaupdate
properties="hibernate.properties"
quiet="no">
<fileset dir="src">
<include name="**/*.hbm.xml"/>
</fileset>
</schemaupdate>
</target>]]></programlisting>
<sect2 id="toolsetguide-s1-8" revision="1">
<title>Validation du schéma</title>
<para>
L'outil <literal>SchemaValidator</literal> validera que le schéma existant correspond à vos documents de mapping.
Notez que le <literal>SchemaValidator</literal> dépends de l'API metadata de JDBC, il ne fonctionnera
donc pas avec tous les drivers JDBC. Cet outil est extrêmement utile pour tester.
</para>
<para>
<literal>java -cp </literal><emphasis>hibernate_classpaths</emphasis>
<literal>org.hibernate.tool.hbm2ddl.SchemaValidator</literal> <emphasis>options mapping_files</emphasis>
</para>
<table frame="topbot">
<title><literal>SchemaValidator</literal> Options de ligne de commande</title>
<tgroup cols="2">
<colspec colwidth="1.5*"/>
<colspec colwidth="2*"/>
<thead>
<row>
<entry>Option</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>--naming=eg.MyNamingStrategy</literal></entry>
<entry>Indique une <literal>NamingStrategy</literal></entry>
</row>
<row>
<entry><literal>--properties=hibernate.properties</literal></entry>
<entry>lit les propriétés dela base de données depuis un fichier de propriétés</entry>
</row>
<row>
<entry><literal>--config=hibernate.cfg.xml</literal></entry>
<entry>indique un fichier <literal>.cfg.xml</literal></entry>
</row>
</tbody>
</tgroup>
</table>
<para>
Vous pouvez inclure <literal>SchemaValidator</literal> dans votre application:
</para>
<programlisting><![CDATA[Configuration cfg = ....;
new SchemaValidator(cfg).validate();]]></programlisting>
</sect2>
</sect2>
<sect2 id="toolsetguide-s1-9">
<title>Utiliser Ant pour la validation du Schéma</title>
<para>
Vous pouvez appeler <literal>SchemaValidator</literal> depuis le script Ant:
</para>
<programlisting><![CDATA[<target name="schemavalidate">
<taskdef name="schemavalidator"
classname="org.hibernate.tool.hbm2ddl.SchemaValidatorTask"
classpathref="class.path"/>
<schemavalidator
properties="hibernate.properties">
<fileset dir="src">
<include name="**/*.hbm.xml"/>
</fileset>
</schemaupdate>
</target>]]></programlisting>
</sect2>
</sect1>
</chapter>