Hibernate.orgCommunity Documentation
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.
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é.
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 21.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).
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_classpathsorg.hibernate.tool.hbm2ddl.SchemaExportoptions mapping_files
Tableau 21.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);
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 21.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 |
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
>
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 21.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);
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
>
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 21.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();
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.