Hibernate.org Community Documentation

- Précédent
- Suivant

## Chapitre 22. Guide de la boîte à outils

Des outils en ligne de commande, des plugins Eclipse ainsi que des tâches Ant permettent de gérer le développement complet de projets à travers Hibernate.

Les outils Hibernate 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 :

- Mapping Editor : un éditeur pour les fichiers de mappage XML Hibernate, supportant l'auto-finalisation et la mise en valeur de la syntaxe. Il supporte aussi la sémantique d'auto-finalisation pour les noms de classes et les noms de propriété/champs, le rendant beaucoup plus polyvalent qu'un éditeur XML ordinaire.

- Console : 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.

- Development Wizards : plusieurs assistants sont fournis avec les outils de Hibernate pour Eclipse ; vous pouvez utiliser un assistant pour générer rapidement les fichiers de configuration Hibernate (cfg.xml), ou vous pouvez même complètement générer les fichiers de mappage 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.

Veuillez-vous référer au paquetage Outils Hibernate et à sa documentation pour plus d'informations.

Cependant, le paquetage principal de Hibernate arrive avec un ensemble d'outils intégrés (il peut même être utilisé de "l'intérieur" de Hibernate à la volée) : SchemaExport aussi connu comme `hbm2ddl`.

## 22.1. Génération automatique du schéma

La DDL peut être générée à partir de vos fichiers de mappage par un utilitaire 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'identifiants mappés.

Vous devez spécifier un `Dialect` SQL via la propriété `hibernate.dialect` lors de l'utilisation de cet outil, puisque la DDL est fortement dépendante du vendeur spécifique.

D'abord, personnalisez vos fichiers de mappage pour améliorer le schéma généré.

### 22.1.1. Personnaliser le schéma

Plusieurs éléments du mappage Hibernate définissent des attributs optionnels nommés `length`, `precision` et `scale`. Vous pouvez paramétrer la taille, la précision, et l'échelle d'une colonne avec cet attribut.

    <property name="zip" length="5"/>

    <property name="balance" precision="12" scale="2"/>

Certaines balises acceptent aussi un attribut `not-null` utilisé pour générer les contraintes de colonnes `NOT NULL` et un attribut `unique` pour générer une contrainte `UNIQUE` de colonnes de table.

    <many-to-one name="bar" column="barId" not-null="true"/>

    <element column="serialNumber" type="long" not-null="true" unique="true"/>

Un attribut `unique-key` peut être utilisé pour grouper les colonnes en une seule contrainte d'unicité. Actuellement, la valeur spécifiée par l'attribut `unique-key` n'est pas utilisée pour nommer la contrainte dans la DDL générée, elle sert juste à grouper les colonnes dans le fichier de mappage.

    <many-to-one name="org" column="orgId" unique-key="OrgEmployeeId"/>

    <property name="employeeId" unique-key="OrgEmployee"/>

Un attribut `index` 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.

    <property name="lastName" index="CustName"/>

    <property name="firstName" index="CustName"/>

Un attribut `foreign-key` peut être utilisé pour surcharger le nom des clés étrangères générées.

    <many-to-one name="bar" column="barId" foreign-key="FKFooBar"/>

Plusieurs éléments de mappage acceptent aussi un élément fils `<column>`. Ceci est particulièrement utile pour les type multi-colonnes :

    <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

    >

L'attribut `default` vous laisse spécifier une valeur par défaut pour une colonne. Vous devez assigner la même valeur à la propriété mappée avant de sauvegarder une nouvelle instance de la classe mappée.

    <property name="credits" type="integer" insert="false">

        <column name="credits" default="10"/>

    </property

    >

    <version name="version" type="integer" insert="false">

        <column name="version" default="0"/>

    </property

    >

L'attribut `sql-type` permet à l'utilisateur de surcharger le mappage par défaut d'un type Hibernate vers un type de données SQL.

    <property name="balance" type="float">

        <column name="balance" sql-type="decimal(13,3)"/>

    </property

    >

L'attribut `check` permet de spécifier une contrainte de vérification.

    <property name="foo" type="integer">

        <column name="foo" check="foo

    > 10"/>

    </property

    >

    <class name="Foo" table="foos" check="bar < 100.0">

        ...

        <property name="bar" type="float"/>

    </class

    >

Le tableau suivant dresse la liste des attributs en option.

Tableau 22.1. Résumé

Attribut | Valeurs | Interprétation
--- | --- | ---
`length` | numérique | taille d'une colonne
`precision` | numérique | précision décimale de la colonne
`scale` | numérique | échelle décimale de la colonne
`not-null` | `true|false` | spécifie que la colonne doit être non-nulle
`unique` | `true|false` | spécifie que la colonne doit avoir une contrainte d'unicité
`index` | `index_name` | spécifie le nom d'un index (multi-colonnes)
`unique-key` | `unique_key_name` | spécifie le nom d'une contrainte d'unicité multi-colonnes
`foreign-key` | `foreign_key_name` | spécifie le nom de la contrainte de clé étrangère générée par une association, pour un élément de mappage `<one-to-one>`, `<many-to-one>`, `<key>`, ou `<many-to-many>`. Notez que les côtés `inverse="true"` ne seront pas pris en considération par le `SchemaExport`.
`sql-type` | `SQL column type` | surcharge le type par défaut (attribut de l'élément `<column>` uniquement)
`default` | Expression SQL | spécifie une valeur par défaut pour la colonne
`check` | Expression SQL | crée une contrainte de vérification sur la table ou la colonne

L'élément `<comment>` vous permet de spécifier des commentaires pour le schéma généré.

    <class name="Customer" table="CurCust">

        <comment

    >Current customers only</comment>

        ...

    </class

    >

    <property name="balance">

        <column name="bal">

            <comment

    >Balance in USD</comment>

        </column>

    </property

    >

Ceci a pour résultat une expression `comment on table` ou `comment on column` dans la DDL générée (là où elle est supportée).

### 22.1.2. Exécuter l'outil

L'outil `SchemaExport` génère un script DDL vers la sortie standard et/ou exécute les ordres DDL.

Le tableau suivant affiche les options de ligne de commande du `SchemaExport`

`java -cp` hibernate_classpaths `org.hibernate.tool.hbm2ddl.SchemaExport` options mapping_files

Tableau 22.2. `SchemaExport` Options de la ligne de commande

Option | Description
--- | ---
`--quiet` | ne pas écrire le script vers la sortie standard stdout
`--drop` | supprime uniquement les tables
`--create` | ne crée que les tables
`--text` | n'exporte pas vers la base de données
`--output=my_schema.ddl` | écrit le script ddl vers un fichier
`--naming=eg.MyNamingStrategy` | sélectionne une `NamingStrategy`
`--config=hibernate.cfg.xml` | lit la configuration Hibernate à partir d'un fichier XML
`--properties=hibernate.properties` | lit les propriétés de la base de données à partir d'un fichier
`--format` | formatte proprement le SQL généré dans le script
`--delimiter=;` | paramètre un délimiteur de fin de ligne pour le script

Vous pouvez même intégrer `SchemaExport` dans votre application :

    Configuration cfg = ....;

    new SchemaExport(cfg).create(false, true);

### 22.1.3. Propriétés

Les propriétés de la base de données peuvent être spécifiées :

- comme propriétés système avec `-D`<property>

- dans `hibernate.properties`

- dans un fichier de propriétés déclaré avec `--properties`

Les propriétés nécessaires sont :

Tableau 22.3. Les propriétés de connexion SchemaExport

Nom de la propriété | Description
--- | ---
`hibernate.connection.driver_class` | classe du driver JDBC
`hibernate.connection.url` | URL JDBC
`hibernate.connection.username` | utilisateur de la base de données
`hibernate.connection.password` | mot de passe de l'utilisateur
`hibernate.dialect` | dialecte

### 22.1.4. Utiliser Ant

Vous pouvez appeler `SchemaExport` depuis votre script de construction Ant :

    <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

    >

### 22.1.5. Mises à jour incrémentales du schéma

L'outil `SchemaUpdate` mettra à jour un schéma existant en effectuant les changements par "incrément". Notez que `SchemaUpdate` dépend fortement de l'API des métadonnées JDBC, par conséquent il ne fonctionne pas avec tous les drivers JDBC.

`java -cp` hibernate_classpaths `org.hibernate.tool.hbm2ddl.SchemaUpdate` options mapping_files

Tableau 22.4. `SchemaUpdate` Options de ligne de commande

Option | Description
--- | ---
`--quiet` | ne pas écrire le script vers la sortie standard stdout
`--text` | ne pas exporter vers la base de données
`--naming=eg.MyNamingStrategy` | sélectionne une `NamingStrategy`
`--properties=hibernate.properties` | lit les propriétés de la base de données à partir d'un fichier
`--config=hibernate.cfg.xml` | spécifier un fichier `.cfg.xml`

Vous pouvez intégrer `SchemaUpdate` dans votre application :

    Configuration cfg = ....;

    new SchemaUpdate(cfg).execute(false);

### 22.1.6. Utiliser Ant pour des mises à jour de schéma par incrément

Vous pouvez appeler `SchemaUpdate` depuis le script Ant :

    <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

    >

### 22.1.7. Validation du schéma

L'outil `SchemaValidator` confirmera que le schéma existant correspond à vos documents de mappage. Notez que le `SchemaValidator` dépend de l'API des métadonnées de JDBC, il ne fonctionne donc pas avec tous les drivers JDBC. Cet outil est extrêmement utile pour les tests.

`java -cp` hibernate_classpaths `org.hibernate.tool.hbm2ddl.SchemaValidator` options mapping_files

Le tableau suivant affiche les options de ligne de commande du `SchemaValidator`

Tableau 22.5. `SchemaValidator` Options de ligne de commande

Option | Description
--- | ---
`--naming=eg.MyNamingStrategy` | sélectionne une `NamingStrategy`
`--properties=hibernate.properties` | lit les propriétés de la base de données à partir d'un fichier
`--config=hibernate.cfg.xml` | spécifier un fichier `.cfg.xml`

Vous pouvez inclure `SchemaValidator` dans votre application :

    Configuration cfg = ....;

    new SchemaValidator(cfg).validate();

### 22.1.8. Utiliser Ant pour la validation du Schéma

Vous pouvez appeler `SchemaValidator` depuis le script Ant:

    <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>

        </schemavalidator>

    </target

    >

Copyright © 2004 Red Hat, Inc.

- PrécédentChapitre 21. Améliorer les performances
- Niveau supérieur
- Sommaire
- SuivantChapitre 23. Additional modules