Hibernate.orgCommunity Documentation

HIBERNATE - Relational Persistence for Idiomatic Java

Hibernate Reference Documentation

3.5.6-Final

Legal Notice

September 15, 2010


Préface
1. Tutoriel
1.1. Section 1 - Première application Hibernate
1.1.1. Configuration
1.1.2. La première classe
1.1.3. Le fichier de mappage
1.1.4. Configuration d'Hibernate
1.1.5. Construction avec Maven
1.1.6. Démarrage et aides
1.1.7. Charger et stocker des objets
1.2. Section 2 - Mapper des associations
1.2.1. Mapper la classe Person
1.2.2. Une association unidirectionnelle basée sur Set
1.2.3. Travailler avec l'association
1.2.4. Collection de valeurs
1.2.5. Associations bidirectionnelles
1.2.6. Travailler avec des liens bidirectionnels
1.3. Section 3 - L'application web EventManager
1.3.1. Écrire la servlet de base
1.3.2. Traiter et interpréter
1.3.3. Déployer et tester
1.4. Résumé
2. Architecture
2.1. Généralités
2.2. Etats des instances
2.3. Intégration JMX
2.4. Support JCA
2.5. Sessions contextuelles
3. Configuration
3.1. Configuration par programmation
3.2. Obtenir une SessionFactory
3.3. Connexions JDBC
3.4. Propriétés de configuration optionnelles
3.4.1. Dialectes SQL
3.4.2. Chargement par jointure externe
3.4.3. Flux binaires
3.4.4. Cache de second niveau et cache de requêtes
3.4.5. Substitution dans le langage de requêtes
3.4.6. Statistiques Hibernate
3.5. Journalisation
3.6. Sélectionne une NamingStrategy (stratégie de nommage)
3.7. Fichier de configuration XML
3.8. Intégration à un serveur d'applications J2EE
3.8.1. Configuration de la stratégie transactionnelle
3.8.2. SessionFactory associée au JNDI
3.8.3. Gestion du contexte de la session courante à JTA
3.8.4. Déploiement JMX
4. Classes persistantes
4.1. Un exemple simple de POJO
4.1.1. Implémenter un constructeur sans argument
4.1.2. Fournir une propriété d'identifiant (optionnel)
4.1.3. Favoriser les classes non finales (optionnel)
4.1.4. Déclarer les accesseurs et mutateurs des attributs persistants (optionnel)
4.2. Implémenter l'héritage
4.3. Implémenter equals() et hashCode()
4.4. Modèles dynamiques
4.5. Tuplizers
4.6. EntityNameResolvers
5. Mappage O/R de base
5.1. Déclaration de mappage
5.1.1. Doctype
5.1.2. Hibernate-mappage
5.1.3. Classe
5.1.4. id
5.1.5. La méthode getter de l'identifiant
5.1.6. Optimisation du générateur d'identifiants
5.1.7. composite-id
5.1.8. Discriminator
5.1.9. Version (optionnel)
5.1.10. Timestamp (optionnel)
5.1.11. Property
5.1.12. Plusieurs-à-un
5.1.13. Un-à-un
5.1.14. Natural-id
5.1.15. Component, dynamic-component
5.1.16. Propriétés
5.1.17. Subclass
5.1.18. Joined-subclass
5.1.19. Union-subclass
5.1.20. Join
5.1.21. Key
5.1.22. Éléments column et formula
5.1.23. Import
5.1.24. Any
5.2. Types Hibernate
5.2.1. Entités et valeurs
5.2.2. Types valeurs de base
5.2.3. Types de valeur personnalisés
5.3. Mapper une classe plus d'une fois
5.4. SQL quoted identifiers
5.5. Métadonnées alternatives
5.5.1. Utilisation de XDoclet
5.5.2. Utilisation des annotations JDK 5.0
5.6. Propriétés générées
5.7. Column read and write expressions
5.8. Objets auxiliaires de la base de données
6. Mapper une collection
6.1. Collections persistantes
6.2. Mapper une collection
6.2.1. Les clés étrangères d'une collection
6.2.2. Les éléments d'une collection
6.2.3. Collections indexées
6.2.4. Collections de valeurs et associations plusieurs-à-plusieurs
6.2.5. Associations un-à-plusieurs
6.3. Mappages de collection avancés
6.3.1. Collections triées
6.3.2. Associations bidirectionnelles
6.3.3. Associations bidirectionnelles avec des collections indexées
6.3.4. Associations ternaires
6.3.5. Using an <idbag>
6.4. Exemples de collections
7. Mapper les associations
7.1. Introduction
7.2. Associations unidirectionnelles
7.2.1. plusieurs-à-un
7.2.2. Un-à-un
7.2.3. un-à-plusieurs
7.3. Associations unidirectionnelles avec tables de jointure
7.3.1. un-à-plusieurs
7.3.2. plusieurs-à-un
7.3.3. Un-à-un
7.3.4. Plusieurs-à-plusieurs
7.4. Associations bidirectionnelles
7.4.1. un-à-plusieurs / plusieurs-à-un
7.4.2. Un-à-un
7.5. Associations bidirectionnelles avec tables de jointure
7.5.1. un-à-plusieurs / plusieurs-à-un
7.5.2. un-à-un
7.5.3. Plusieurs-à-plusieurs
7.6. Des mappages d'associations plus complexes
8. Mappage de composants
8.1. Objets dépendants
8.2. Collection d'objets dépendants
8.3. Les composants en tant qu'indices de Map
8.4. Les composants en tant qu'identifiants composites
8.5. Les composants dynamiques
9. Mapping d'héritage de classe
9.1. Les trois stratégies
9.1.1. Une table par hiérarchie de classe
9.1.2. Une table par classe fille
9.1.3. Une table par classe fille, en utilisant un discriminant
9.1.4. Mélange d'une table par hiérarchie de classe avec une table par classe fille
9.1.5. Une table par classe concrète
9.1.6. Une table par classe concrète, en utilisant le polymorphisme implicite
9.1.7. Mélange du polymorphisme implicite avec d'autres mappages d'héritage
9.2. Limitations
10. Travailler avec des objets
10.1. États des objets Hibernate
10.2. Rendre des objets persistants
10.3. Chargement d'un objet
10.4. Requêtage
10.4.1. Exécution de requêtes
10.4.2. Filtrer des collections
10.4.3. Requêtes par critères
10.4.4. Requêtes en SQL natif
10.5. Modifier des objets persistants
10.6. Modifier des objets détachés
10.7. Détection automatique d'un état
10.8. Suppression d'objets persistants
10.9. Réplication d'objets entre deux entrepôts de données
10.10. Flush de la session
10.11. Persistance transitive
10.12. Utilisation des méta-données
11. Read-only entities
11.1. Making persistent entities read-only
11.1.1. Entities of immutable classes
11.1.2. Loading persistent entities as read-only
11.1.3. Loading read-only entities from an HQL query/criteria
11.1.4. Making a persistent entity read-only
11.2. Read-only affect on property type
11.2.1. Simple properties
11.2.2. Unidirectional associations
11.2.3. Bidirectional associations
12. Transactions et Accès concurrents
12.1. Portées des sessions et des transactions
12.1.1. Unité de travail
12.1.2. Longue conversation
12.1.3. L'identité des objets
12.1.4. Problèmes communs
12.2. Démarcation des transactions de base de données
12.2.1. Environnement non gérés
12.2.2. Utilisation de JTA
12.2.3. Gestion des exceptions
12.2.4. Timeout de transaction
12.3. Contrôle de concurrence optimiste
12.3.1. Vérification du versionnage au niveau applicatif
12.3.2. Les sessions longues et le versionnage automatique.
12.3.3. Les objets détachés et le versionnage automatique
12.3.4. Personnaliser le versionnage automatique
12.4. Verrouillage pessimiste
12.5. Modes de libération de connexion
13. Intercepteurs et événements
13.1. Intercepteurs
13.2. Système d'événements
13.3. Sécurité déclarative de Hibernate
14. Traitement par lot
14.1. Insertions en lot
14.2. Mise à jour des lots
14.3. L'interface StatelessSession
14.4. Opérations de style DML
15. HQL : langage d'interrogation d'Hibernate
15.1. Sensibilité à la casse
15.2. La clause from
15.3. Associations et jointures
15.4. Formes de syntaxes pour les jointures
15.5. Faire référence à la propriété identifiant
15.6. La clause select
15.7. Fonctions d'agrégation
15.8. Requêtes polymorphiques
15.9. La clause where
15.10. Expressions
15.11. La clause order by
15.12. La clause group by
15.13. Sous-requêtes
15.14. Exemples HQL
15.15. Nombreuses mises à jour et suppressions
15.16. Trucs & Astuces
15.17. Composants
15.18. Syntaxe des constructeurs de valeur de ligne
16. Requêtes par critères
16.1. Créer une instance de Criteria
16.2. Restriction du résultat
16.3. Trier les résultats
16.4. Associations
16.5. Peuplement d'associations de manière dynamique
16.6. Requêtes par l'exemple
16.7. Projections, agrégation et regroupement
16.8. Requêtes et sous-requêtes détachées
16.9. Requêtes par identifiant naturel
17. SQL natif
17.1. Utiliser une requête SQLQuery
17.1.1. Requêtes scalaires
17.1.2. Requêtes d'entités
17.1.3. Gérer les associations et collections
17.1.4. Retour d'entités multiples
17.1.5. Retour d'entités non gérées
17.1.6. Gérer l'héritage
17.1.7. Paramètres
17.2. Requêtes SQL nommées
17.2.1. Utilisation de return-property pour spécifier explicitement les noms des colonnes/alias
17.2.2. Utilisation de procédures stockées pour les requêtes
17.3. SQL personnalisé pour créer, mettre à jour et effacer
17.4. SQL personnalisé pour le chargement
18. Filtrer les données
18.1. Filtres Hibernate
19. Mappage XML
19.1. Travailler avec des données XML
19.1.1. Spécifier le mappage XML et le mappage d'une classe ensemble
19.1.2. Spécifier seulement un mappage XML
19.2. Métadonnées du mappage XML
19.3. Manipuler des données XML
20. Améliorer les performances
20.1. Stratégies de chargement
20.1.1. Travailler avec des associations chargées en différé
20.1.2. Personnalisation des stratégies de chargement
20.1.3. Proxies pour des associations vers un seul objet
20.1.4. Initialisation des collections et des proxies
20.1.5. Utiliser le chargement par lot
20.1.6. Utilisation du chargement par sous select
20.1.7. Fetch profiles
20.1.8. Utiliser le chargement en différé des propriétés
20.2. Le cache de second niveau
20.2.1. Mappages de Cache
20.2.2. Stratégie : lecture seule
20.2.3. Stratégie : lecture/écriture
20.2.4. Stratégie : lecture/écriture non stricte
20.2.5. Stratégie : transactionelle
20.2.6. Support de stratégie de concurrence du fournisseur-cache
20.3. Gérer les caches
20.4. Le cache de requêtes
20.4.1. Enabling query caching
20.4.2. Query cache regions
20.5. Comprendre les performances des collections
20.5.1. Taxinomie
20.5.2. Les lists, les maps, les idbags et les ensembles sont les collections les plus efficaces pour la mise à jour
20.5.3. Les sacs et les listes sont les plus efficaces pour les collections inverses
20.5.4. Suppression en un coup
20.6. Moniteur de performance
20.6.1. Suivi d'une SessionFactory
20.6.2. Métriques
21. Guide de la boîte à outils
21.1. Génération automatique du schéma
21.1.1. Personnaliser le schéma
21.1.2. Exécuter l'outil
21.1.3. Propriétés
21.1.4. Utiliser Ant
21.1.5. Mises à jour incrémentales du schéma
21.1.6. Utiliser Ant pour des mises à jour de schéma par incrément
21.1.7. Validation du schéma
21.1.8. Utiliser Ant pour la validation du Schéma
22. Exemple : père/fils
22.1. Une note à propos des collections
22.2. Un-à-plusieurs bidirectionnel
22.3. Cycle de vie en cascade
22.4. Cascades et unsaved-value (valeurs non sauvegardées)
22.5. Conclusion
23. Exemple : application Weblog
23.1. Classes persistantes
23.2. Mappages Hibernate
23.3. Code Hibernate
24. Exemple : quelques mappages
24.1. Employeur/Employé (Employer/Employee)
24.2. Auteur/Travail
24.3. Client/Commande/Produit
24.4. Divers exemples de mappages
24.4.1. "Typed" association un-à-un
24.4.2. Exemple de clef composée
24.4.3. Plusieurs-à-plusieurs avec un attribut de clef composée partagée
24.4.4. Contenu basé sur une discrimination
24.4.5. Associations sur des clés alternées
25. Meilleures pratiques
26. Considérations de portabilité des bases de données
26.1. Aspects fondamentaux de la portabilité
26.2. Dialecte
26.3. Résolution de dialecte
26.4. Générer les identifiants
26.5. Fonctions de base de données
26.6. Type mappings
References

Working with object-oriented software and a relational database can be cumbersome and time consuming in today's enterprise environments. Hibernate is an Object/Relational Mapping tool for Java environments. The term Object/Relational Mapping (ORM) refers to the technique of mapping a data representation from an object model to a relational data model with a SQL-based schema.

Hibernate s'occupe du mappage des classes Java vers les tables de bases de données (et des types de données Java vers les types de données SQL), mais fournit également des facilités de recherche et de retrait de données. Hibernate peut réduire énormément le temps de développement, normalement passé à traiter des données manuellement dans SQL ou JDBC.

Le but d'Hibernate est de libérer le développeur de 95 pour cent des tâches de programmation liées à la persistance de données communes. Hibernate n'est peut-être pas la meilleure solution pour les applications centrées-données qui utilisent uniquement les procédures-stored pour implémenter la logique métier dans la base de données. Cela est surtout utile avec les modèles de domaines orientés-objet et la logique métier dans l'étape intermédiaire basée Java. Malgré tout, Hibernate peut vous aider à supprimer ou à encapsuler le code SQL propre à un distributeur et vous aidera à régler la tâche commune qui consiste à transposer un ensemble de résultats à partir d'un tableau de représentation vers un graphe d'objets.

Si vous n'êtes pas familiarisé avec Hibernate et le mappage Objet/Relationnel ou même Java, veuillez suivre les étapes suivantes :

  1. Read Chapitre 1, Tutoriel for a tutorial with step-by-step instructions. The source code for the tutorial is included in the distribution in the doc/reference/tutorial/ directory.

  2. Read Chapitre 2, Architecture to understand the environments where Hibernate can be used.

  3. Veuillez consulter le répertoire eg/ dans la distribution Hibernate, qui contient une application autonome simple. Copier votre pilote JDBC dans le répertoire lib/ et éditez etc/hibernate.properties, en spécifiant les valeurs qu'il faut dans votre base de données. A partir d'une invite de commande du répertoire de distribution, veuillez saisir ant eg (en utilisant Ant), et sous Windows, tapez build eg.

  4. Use this reference documentation as your primary source of information. Consider reading [JPwH] if you need more help with application design, or if you prefer a step-by-step tutorial. Also visit http://caveatemptor.hibernate.org and download the example application from [JPwH].

  5. Les questions FAQ sont traitées sur le site Hibernate.

  6. Links to third party demos, examples, and tutorials are maintained on the Hibernate website.

  7. La section Community Area (Zône communautaire) du site Hibernate constitue une ressource intéressante pour les modèles conceptuels et autres solutions diverses d'intégration (Tomcat, JBoss AS, Struts, EJB, etc.).

Si vous avez des questions, participez au forum utilisateur sur le site Hibernate. Nous proposons également des systèmes de traçage JIRA pour les rapports de bogues et les demandes sur les fonctionalités. Si vous êtes intéressé à participer au développement d'Hibernate, veuillez rejoindre la liste de distribution électronique des développeurs.

Le support pour le développement commercial, le support production, et la formation Hibernate sont disponibles à travers JBoss Inc. (voir http://www.hibernate.org/SupportTraining/). Hibernate est un projet professionnel en source ouverte et un composant critique de la suite de produits JBoss Enterprise Middleware System (JEMS).

A l'intention des nouveaux utilisateurs, ce chapitre fournit une introduction étape par étape à Hibernate, en commençant par une application simple, avec une base de données en-mémoire. Le tutoriel est basé sur une tutoriel antérieur qui avait été développé par Michael Gloegl. Tout le code est contenu dans tutorials/web qui se trouve dans le répertoire source du projet.

Important

Ce tutoriel assume que l'utilisateur est déjà familier avec Java et SQL à la fois. Si vous ne possédez qu'une connaissance de Java et d'SQL limitée, il est conseillé de commencer par vous familiariser avec ces technologies avant d'aborder Hibernate.

Note

La distribution contient un autre exemple d'application qui se trouve dans le répertoire source du projet tutorial/eg.

Supposons que nous ayons besoin d'une petite application de base de données qui puisse stocker des événements que nous voulons suivre, et des informations à propos des hôtes de ces événements.

Note

Malgré que vous puissiez utiliser tout base de données qui vous convienne, on choisira HSQLDB (une base de données Java, en-mémoire) pour éviter de décrire l'installation et la configuration de n'importe quel serveur de base de données particulière.

La première chose que nous devons faire est de configurer l'environnement de développement. Nous utiliserons la "standard layout" préconisée par de nombreux outils de génération tels que Maven. Maven, en particulier, a une bonne ressource décrivant cette layout. Comme ce tutoriel va devenir une application web, nous allons créer et utiliser les répertoires src/main/java., src/main/ressources et src/main/webapp.

Nous utiliserons Maven dans ce tutoriel. Nous profiterons de ses capacités de gestion de dépendances transitives, ainsi que de la capacité des nombreux IDE à installer automatiquement un projet sur la base du descripteur Maven.


<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">

    <modelVersion
>4.0.0</modelVersion>

    <groupId
>org.hibernate.tutorials</groupId>
    <artifactId
>hibernate-tutorial</artifactId>
    <version
>1.0.0-SNAPSHOT</version>
    <name
>First Hibernate Tutorial</name>

    <build>
         <!-- we dont want the version to be part of the generated war file name -->
         <finalName
>${artifactId}</finalName>
    </build>

    <dependencies>
        <dependency>
            <groupId
>org.hibernate</groupId>
            <artifactId
>hibernate-core</artifactId>
        </dependency>

        <!-- Because this is a web app, we also have a dependency on the servlet api. -->
        <dependency>
            <groupId
>javax.servlet</groupId>
            <artifactId
>servlet-api</artifactId>
        </dependency>

        <!-- Hibernate uses slf4j for logging, for our purposes here use the simple backend -->
        <dependency>
            <groupId
>org.slf4j</groupId>
            <artifactId
>slf4j-simple</artifactId>
        </dependency>

        <!-- Hibernate gives you a choice of bytecode providers between cglib and javassist -->
        <dependency>
            <groupId
>javassist</groupId>
            <artifactId
>javassist</artifactId>
        </dependency>
    </dependencies>

</project
>

Astuce

It is not a requirement to use Maven. If you wish to use something else to build this tutorial (such as Ant), the layout will remain the same. The only change is that you will need to manually account for all the needed dependencies. If you use something like Ivy providing transitive dependency management you would still use the dependencies mentioned below. Otherwise, you'd need to grab all dependencies, both explicit and transitive, and add them to the project's classpath. If working from the Hibernate distribution bundle, this would mean hibernate3.jar, all artifacts in the lib/required directory and all files from either the lib/bytecode/cglib or lib/bytecode/javassist directory; additionally you will need both the servlet-api jar and one of the slf4j logging backends.

Sauvegardez ce fichier sous la forme pom.xml dans le répertoire root du projet.

Ensuite, nous créons une classe qui représente l'évènement que nous voulons stocker dans notre base de données. Il s'agit d'une simple classe JavaBean avec quelques propriétés :

package org.hibernate.tutorial.domain;


import java.util.Date;
public class Event {
    private Long id;
    private String title;
    private Date date;
    public Event() {}
    public Long getId() {
        return id;
    }
    private void setId(Long id) {
        this.id = id;
    }
    public Date getDate() {
        return date;
    }
    public void setDate(Date date) {
        this.date = date;
    }
    public String getTitle() {
        return title;
    }
    public void setTitle(String title) {
        this.title = title;
    }
}

Vous constaterez que cette classe utilise les conventions de nommage standard JavaBean pour les méthodes getter/setter des propriétés, ainsi qu'une visibilité privée pour les champs. Ceci est la conception recommandée - mais pas obligatoire. Hibernate peut aussi accéder aux champs directement, le bénéfice des méthodes d'accès est la robustesse pour la refonte de code.

La propriété id contient la valeur d'un identifiant unique pour un événement particulier. Toutes les classes d'entités persistantes (il y a également des classes dépendantes de moindre importance) auront besoin d'une telle propriété identifiante si nous voulons utiliser l'ensemble complet des fonctionnalités de Hibernate. En fait, la plupart des applications (surtout les applications web) ont besoin de distinguer des objets par des identifiants, par conséquent considérez cela comme une fonctionnalité et non comme une limitation. Cependant, nous ne manipulons généralement pas l'identité d'un objet, dorénavant la méthode setter devrait être privée. Seul Hibernate assignera les identifiants lorsqu'un objet est sauvegardé. Remarquez que Hibernate peut accéder aux méthodes publiques, privées et protégées, ainsi qu'aux champs (publics, privés, protégés) directement. À vous de choisir, et vous pouvez également l'ajuster à la conception de votre application.

Le constructeur sans argument est requis pour toutes les classes persistantes; Hibernate doit créer des objets pour vous en utilisant la réflexion Java. Le constructeur peut être privé, cependant, la visibilité du paquet est requise pour la génération de proxies à l'exécution et une récupération efficace des données sans instrumentation du bytecode.

Sauvegardez ce fichier dans le répertoire src/main/java/org/hibernate/tutorial/domain.

Hibernate a besoin de savoir comment charger et stocker des objets d'une classe persistante. C'est là qu'intervient le fichier de mappage Hibernate. Le fichier de mappage indique à Hibernate à quelle table accéder dans la base de données, et les colonnes de cette table à utiliser.

La structure basique de ce fichier de mappage ressemble à ce qui suit :


<?xml version="1.0"?>
<!DOCTYPE hibernate-mapping PUBLIC
        "-//Hibernate/Hibernate Mapping DTD 3.0//EN"
        "http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd">

<hibernate-mapping package="org.hibernate.tutorial.domain">
[...]
</hibernate-mapping
>

Notez que la DTD Hibernate est très sophistiquée. Vous pouvez l'utiliser pour l'auto-finalisation des éléments et des attributs de mappage XML dans votre éditeur ou votre IDE. Ouvrez également le fichier DTD dans votre éditeur de texte - c'est le moyen le plus facile d'obtenir une vue d'ensemble de tous les éléments et attributs, et de voir les valeurs par défaut, ainsi que quelques commentaires. Notez qu'Hibernate ne chargera pas le fichier DTD à partir du web, mais regardera d'abord dans le chemin de classe de l'application. Le fichier DTD est inclus dans hibernate-core.jar ainsi que dans le répertoire src de la distribution Hibernate).

Entre les deux balises hibernate-mapping, incluez un élément class. Toutes les classes d'entités persistantes (encore une fois, il pourrait y avoir des classes dépendantes plus tard, qui ne sont pas des entités mère) ont besoin d'un mappage vers une table de la base de données SQL :


<hibernate-mapping package="org.hibernate.tutorial.domain">

    <class name="Event" table="EVENTS">

    </class>

</hibernate-mapping
>

Plus loin, nous indiquons à Hibernate comment persister et charger un objet de la classe Event dans la table EVENTS, chaque instance étant représentée par une ligne dans cette table. Maintenant nous continuons avec le mappage de la propriété de l'identifiant unique vers la clef primaire des tables. De plus, comme nous ne voulons pas nous occuper de la gestion de cet identifiant, nous utilisons une stratégie de génération d'identifiant Hibernate pour la colonne de la clé primaire subrogée :


<hibernate-mapping package="org.hibernate.tutorial.domain">

    <class name="Event" table="EVENTS">
        <id name="id" column="EVENT_ID">
            <generator class="native"/>
        </id>
    </class>

</hibernate-mapping
>

L'élément ID est la déclaration de l'identifiant de propriété. L'attribut de mappage name="id" déclare le nom de la propriété JavaBean et indique à Hibernate d'utiliser les méthodes getId() et setId() pour accéder à la propriété. L'attribut de colonne indique à Hibernate quelle colonne de la table EVENTS contient la valeur de clé primaire.

L'élément imbriqué Générateur spécifie la stratégie de génération d'identifiant (c'est à dire comment les valeurs d'identifiant sont-elles générées?). Dans ce cas nous avons choisi native, qui offre un niveau de la portabilité selon le dialecte de base de données configurée. Mise en veille prolongée prend en charge la base de données générée, unique au monde, ainsi que l'application affectée, les identifiants. Génération de valeur d'identifiant est aussi l'un des nombreux points d'extension d'Hibernate et vous pouvez plug-in votre propre stratégie.

Enfin, nous incluons des déclarations pour les propriétés persistantes de la classe dans le fichier de mappage. Par défaut, aucune propriété de la classe n'est considérée comme persistante :



<hibernate-mapping package="org.hibernate.tutorial.domain">

    <class name="Event" table="EVENTS">
        <id name="id" column="EVENT_ID">
            <generator class="native"/>
        </id>
        <property name="date" type="timestamp" column="EVENT_DATE"/>
        <property name="title"/>
    </class>

</hibernate-mapping
>

Comme avec l'élément id, l'attribut name de l'élément property indique à Hibernate quelles méthodes getters/setters utiliser. Par conséquent dans ce cas, Hibernate cherchera getDate()/setDate(), de même que getTitle()/setTitle().

Note

Pourquoi le mappage de la propriété date inclut-il l'attribut column, mais non le title ? Sans l'attribut column, Hibernate utilise par défaut le nom de la propriété comme nom de colonne. Cela fonctionne bien pour title. Cependant, date est un mot clé réservé dans la plupart des bases de données, donc nous utilisons un nom différent pour le mappage.

Il est intéressant de noter que le mappage de title manque également d'un attribut type. Les types que nous déclarons et utilisons dans les fichiers de mappage ne sont pas, comme vous pourriez vous y attendre, des types de données Java. Ce ne sont pas, non plus, des types de base de données SQL. Ces types sont donc appelés types de mappage Hibernate, des convertisseurs qui peuvent traduire des types Java en types SQL et vice versa. De plus, Hibernate tentera de déterminer la bonne conversion et le type de mappage lui-même si l'attribut type n'est pas présent dans le mappage. Dans certains cas, cette détection automatique (utilisant la réflexion sur la classe Java) pourrait ne pas donner la valeur attendue ou dont vous avez besoin. C'est le cas avec la propriété date. Hibernate ne peut pas savoir si la propriété "mappera" une colonne SQL de type date, timestamp ou time. Nous déclarons que nous voulons conserver des informations avec une date complète et l'heure en mappant la propriété avec un convertisseur timestamp.

Astuce

Hibernate rend cette détermination de type de mappage en utilisant la réflection au moment du traitement des fichiers de mappage. Cela prend du temps et consomme des ressources, donc, si la performance de démarrage est importante, vous devriez considérer définir explicitement quel type utiliser.

Sauvegardez ce fichier de mappage ainsi src/main/resources/org/hibernate/tutorial/domain/Event.hbm.xml.

A ce niveau là, vous devriez avoir la classe persistante et son fichier de mappage en place. Il est temps maintenant de configurer Hibernate. Tout d'abord, il nous faut configurer HSQLDB pour qu'il puisse exécuter en "server mode"

Vous utiliserez le lugin exec Maven pour lancer le serveur HSQLDB en exécutant : mvn exec:java -Dexec.mainClass="org.hsqldb.Server" -Dexec.args="-database.0 file:target/data/tutorial". Vous observez qu'elle démarre et ouvre un socket TCP/IP, c'est là que notre application se connectera plus tard. Si vous souhaitez démarrez à partir d'une nouvelle base de données pour ce tutoriel (choisissez CTRL + C dans la fenêtre), effacez tous les fichiers dans le répertoire target/data et redémarrez HSQL DB.

Hibernate se connectera à la base de données pour le compte de votre application, donc il devra savoir comment obtenir des connexions. Pour ce tutoriel, nous devrons utliser un pool de connexions autonomes (et non pas javax.sql.DataSource). Hibernate bénéficie du support de deux pools de connexions JDBC open source de tierce partie : c3p0 and proxool. Cependant, nous utiliserons le pool de connexions intégré Hibernate pour ce tutoriel.

Attention

The built-in Hibernate connection pool is in no way intended for production use. It lacks several features found on any decent connection pool.

Pour la configuration de Hibernate, nous pouvons utiliser un simple fichier hibernate.properties, un fichier hibernate.cfg.xml légèrement plus sophistiqué, ou même une configuration complète par programmation. La plupart des utilisateurs préfèrent le fichier de configuration XML :


<?xml version='1.0' encoding='utf-8'?>
<!DOCTYPE hibernate-configuration PUBLIC
        "-//Hibernate/Hibernate Configuration DTD 3.0//EN"
        "http://hibernate.sourceforge.net/hibernate-configuration-3.0.dtd">

<hibernate-configuration>

    <session-factory>

        <!-- Database connection settings -->
        <property name="connection.driver_class"
>org.hsqldb.jdbcDriver</property>
        <property name="connection.url"
>jdbc:hsqldb:hsql://localhost</property>
        <property name="connection.username"
>sa</property>
        <property name="connection.password"
></property>

        <!-- JDBC connection pool (use the built-in) -->
        <property name="connection.pool_size"
>1</property>

        <!-- SQL dialect -->
        <property name="dialect"
>org.hibernate.dialect.HSQLDialect</property>

        <!-- Enable Hibernate's automatic session context management -->
        <property name="current_session_context_class"
>thread</property>

        <!-- Disable the second-level cache  -->
        <property name="cache.provider_class"
>org.hibernate.cache.NoCacheProvider</property>

        <!-- Echo all executed SQL to stdout -->
        <property name="show_sql"
>true</property>

        <!-- Drop and re-create the database schema on startup -->
        <property name="hbm2ddl.auto"
>update</property>

        <mapping resource="org/hibernate/tutorial/domain/Event.hbm.xml"/>

    </session-factory>

</hibernate-configuration
>

Note

Vous pourrez remarquer que cette configuration XML utilise une DTD différente.

Nous configurons une SessionFactory de Hibernate - une fabrique globale responsable d'une base de données particulière. Si vous avez plusieurs base de données, utilisez plusieurs configurations <session-factory>, généralement dans des fichiers de configuration différents (pour un démarrage plus facile).

Les quatre premiers éléments property contiennent la configuration nécessaire pour la connexion JDBC. L'élément property du dialecte spécifie quelle variante du SQL Hibernate va générer.

Astuce

In most cases, Hibernate is able to properly determine which dialect to use. See Section 26.3, « Résolution de dialecte » for more information.

La gestion automatique des sessions d'Hibernate pour les contextes de persistance est bien pratique, comme vous pourrez le constater. L'option hbm2ddl.auto active la génération automatique des schémas de base de données - directement dans la base de données. Cela peut également être désactivé (en supprimant l'option de configuration) ou redirigé vers un fichier avec l'aide de la tâche Ant SchemaExport. Finalement, nous ajoutons le(s) fichier(s) de mappage pour les classes persistantes.

Sauvegarder ce fichier en tant que hibernate.cfg.xml dans le répertoire src/main/resources.

Nous allons maintenant construire le tutoriel avec Maven. Vous aurez besoin d'installer Maven pour cela. Il est disponible dans la page Maven download page. Maven pourra lire le fichier /pom.xml que nous avons créé plus tôt et saura comment effectuer quelques tâches du projet de base. Tout d'abord, exécutons compile pour s'assurer que nous pouvons tout compiler jusqu'à maintenant :

[hibernateTutorial]$ mvn compile
[INFO] Scanning for projects...
[INFO] ------------------------------------------------------------------------
[INFO] Building First Hibernate Tutorial
[INFO]    task-segment: [compile]
[INFO] ------------------------------------------------------------------------
[INFO] [resources:resources]
[INFO] Using default encoding to copy filtered resources.
[INFO] [compiler:compile]
[INFO] Compiling 1 source file to /home/steve/projects/sandbox/hibernateTutorial/target/classes
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 2 seconds
[INFO] Finished at: Tue Jun 09 12:25:25 CDT 2009
[INFO] Final Memory: 5M/547M
[INFO] ------------------------------------------------------------------------

Il est temps de charger et de stocker quelques objets Event, mais d'abord nous devons compléter la configuration avec du code d'infrastructure. Nous devons démarrer Hibernate. Ce démarrage inclut la construction d'un objet SessionFactory global et le stocker dans un lieu facile d'accès dans le code de l'application. Une SessionFactory peut ouvrir de nouvelles Sessions. Une Session représente une unité de travail simplement "threadée". La org.hibernate.SessionFactory est un objet global "thread-safe", instancié une seule fois.

Nous créerons une classe d'aide HibernateUtil qui s'occupe du démarrage et rend la gestion des org.hibernate.SessionFactory plus facile.

package org.hibernate.tutorial.util;


import org.hibernate.SessionFactory;
import org.hibernate.cfg.Configuration;
public class HibernateUtil {
    private static final SessionFactory sessionFactory = buildSessionFactory();
    private static SessionFactory buildSessionFactory() {
        try {
            // Create the SessionFactory from hibernate.cfg.xml
            return new Configuration().configure().buildSessionFactory();
        }
        catch (Throwable ex) {
            // Make sure you log the exception, as it might be swallowed
            System.err.println("Initial SessionFactory creation failed." + ex);
            throw new ExceptionInInitializerError(ex);
        }
    }
    public static SessionFactory getSessionFactory() {
        return sessionFactory;
    }
}

Sauvegardez ce code en tant que src/main/java/org/hibernate/tutorial/util/HibernateUtil.java

Cette classe ne produit pas seulement la org.hibernate.SessionFactory globale dans un initialiseur statique. Elle masque le fait qu'elle exploite un singleton statique. Nous aurions pu aussi bien vérouiller la référence org.hibernate.SessionFactory à partir de JNDI dans un serveur d'application ou dans n'importe quelle location en fait. Elle pourrait aussi obtenir la SessionFactory depuis JNDI dans un serveur d'applications.

Si vous nommez org.hibernate.SessionFactory dans votre fichier de configuration, Hibernate tentera la récupération depuis JNDI. Pour éviter ce code, vous pouvez aussi utiliser un déploiement JMX et laisser le conteneur (compatible JMX) instancier et lier un HibernateService à JNDI. Ces options avancées sont expliquées plus loin.

Nous avons finalement besoin de configurer le système de journalisation - Hibernate utilise commons-logging et vous laisse le choix entre log4j et le système de logs du JDK 1.4. La plupart des développeurs préfèrent log4j : copiez log4j.properties de la distribution de Hibernate (il est dans le répertoire etc/) dans votre répertoire src, puis faîtes de même avec hibernate.cfg.xml. Regardez la configuration d'exemple et changez les paramètres si vous voulez une sortie plus verbeuse. Par défaut, seul le message de démarrage de Hibernate est affiché sur la sortie standard.

L'infrastructure de ce toturiel est complète - et nous sommes prêts à effectuer un travail réel avec Hibernate.

We are now ready to start doing some real work with Hibernate. Let's start by writing an EventManager class with a main() method:

package org.hibernate.tutorial;


import org.hibernate.Session;
import java.util.*;
import org.hibernate.tutorial.domain.Event;
import org.hibernate.tutorial.util.HibernateUtil;
public class EventManager {
    public static void main(String[] args) {
        EventManager mgr = new EventManager();
        if (args[0].equals("store")) {
            mgr.createAndStoreEvent("My Event", new Date());
        }
        HibernateUtil.getSessionFactory().close();
    }
    private void createAndStoreEvent(String title, Date theDate) {
        Session session = HibernateUtil.getSessionFactory().getCurrentSession();
        session.beginTransaction();
        Event theEvent = new Event();
        theEvent.setTitle(title);
        theEvent.setDate(theDate);
        session.save(theEvent);
        session.getTransaction().commit();
    }
}

Nous créons un nouvel objet Event dans createAndStoreEvent(), et nous le remettons à Hibernate, qui s'occupe maintenant du SQL et exécute les INSERT s dans la base de données.

A org.hibernate.Session is designed to represent a single unit of work (a single atomic piece of work to be performed). For now we will keep things simple and assume a one-to-one granularity between a Hibernate org.hibernate.Session and a database transaction. To shield our code from the actual underlying transaction system we use the Hibernate org.hibernate.Transaction API. In this particular case we are using JDBC-based transactional semantics, but it could also run with JTA.

Quelle est la fonction de sessionFactory.getCurrentSession() ? Premièrement, vous pouvez l'invoquer autant de fois que vous le voulez et n'importe où, du moment que vous avez votre SessionFactory (facile grâce à HibernateUtil). La méthode getCurrentSession() renvoie toujours l'unité de travail courante. Souvenez vous que nous avons basculé notre option de configuration au mécanisme basé sur le "thread" dans hibernate.cfg.xml. Par conséquent, l'unité de travail courante est liée au thread Java courant qui exécute notre application.

Une org.hibernate.Session commence lorsque le thread courant commence à appeler getCurrentSession(). Ensuite, elle est attachée par Hibernate au thread courant. Lorsque la transaction s'achève, par commit ou par rollback, Hibernate détache automatiquement la Session du thread et la ferme pour vous. Si vous invoquez getCurrentSession() une nouvelle fois, vous obtenez une nouvelle Session et pouvez entamer une nouvelle unité de travail.

A propos de la portée de l'unité de travail, la session org.hibernate.Session Hibernate devrait-elle être utilisée pour exécuter une ou plusieurs opérations en base de données ? L'exemple ci-dessus utilise une Session pour une opération. C'est une pure coïncidence, l'exemple n'est pas assez complexe pour montrer d'autres approches. La portée d'une Session Hibernate est flexible mais vous ne devriez jamais concevoir votre application de manière à utiliser une nouvelle Session Hibernate pour chaque opération en base de données. Donc même si vous le voyez quelquefois dans les exemples suivants, considérez une session par opération comme un anti-modèle. Une véritable application (web) est affichée plus loin dans ce tutoriel.

See Chapitre 12, Transactions et Accès concurrents for more information about transaction handling and demarcation. The previous example also skipped any error handling and rollback.

Pour pouvoir exécuter ceci, nous utiliserons le plugin exec Maven pour appeler notre classe avec la configuration de classpath qui convient : mvn exec:java -Dexec.mainClass="org.hibernate.tutorial.EventManager" -Dexec.args="store"

Note

Vous aurez sans doute besoin d'effectuer mvn compile pour commencer.

Vous devriez constater qu'Hibernate démarre et selon votre configuration, beaucoup de traces sur la sortie. À la fin, vous trouverez la ligne suivante :

[java] Hibernate: insert into EVENTS (EVENT_DATE, title, EVENT_ID) values (?, ?, ?)

C'est l' INSERT exécutée par Hibernate.

Maintenant nous aimerions aussi lister les événements stockés, donc nous ajoutons une option à la méthode principale :

        if (args[0].equals("store")) {

            mgr.createAndStoreEvent("My Event", new Date());
        }
        else if (args[0].equals("list")) {
            List events = mgr.listEvents();
            for (int i = 0; i < events.size(); i++) {
                Event theEvent = (Event) events.get(i);
                System.out.println(
                        "Event: " + theEvent.getTitle() + " Time: " + theEvent.getDate()
                );
            }
        }

Nous ajoutons aussi une nouvelle méthode listEvents() :

    private List listEvents() {

        Session session = HibernateUtil.getSessionFactory().getCurrentSession();
        session.beginTransaction();
        List result = session.createQuery("from Event").list();
        session.getTransaction().commit();
        return result;
    }

Here, we are using a Hibernate Query Language (HQL) query to load all existing Event objects from the database. Hibernate will generate the appropriate SQL, send it to the database and populate Event objects with the data. You can create more complex queries with HQL. See Chapitre 15, HQL : langage d'interrogation d'Hibernate for more information.

Nous pouvons maintenant appeler notre nouvelle fonctionnalité, en utilisant à nouveau le plugin exec Maven : mvn exec:java -Dexec.mainClass="org.hibernate.tutorial.EventManager" -Dexec.args="list"

Pour l'instant, nous nous sommes contentés de mapper une classe d'une entité persistante vers une table. Profitons-en pour ajouter quelques associations de classe. D'abord nous ajouterons des gens à notre application, et stockerons une liste d'événements auxquels ils participent.

Nous allons ajouter une collection d'événements à la classe Person. De cette manière nous pouvons facilement naviguer dans les événements d'une personne particulière, sans exécuter une requête explicite - en appelant aPerson.getEvents(). Nous utilisons une collection Java, un Set, parce que la collection ne contiendra pas d'éléments dupliqués et l'ordre ne nous importe pas pour ces exemples :

public class Person {


    private Set events = new HashSet();
    public Set getEvents() {
        return events;
    }
    public void setEvents(Set events) {
        this.events = events;
    }
}

D'abord nous mappons cette association, mais pensez à l'autre côté. Clairement, nous pouvons la laisser unidirectionnelle. Ou bien, nous pourrions créer une autre collection sur Event, si nous voulons être capable de la parcourir de manière bidirectionnelle. Ce n'est pas nécessaire d'un point de vue fonctionnel. Vous pourrez toujours exécuter une requête explicite pour récupérer les participants d'un évènement particulier. Vous êtes libre de choisir la conception, ce qui est certain, c'est que la cardinalité de l'association : "plusieurs" valués des deux côtés, est appelée plusieurs-à-plusieurs. Par conséquent nous utilisons un mappage Hibernate plusieurs-à-plusieurs :


<class name="Person" table="PERSON">
    <id name="id" column="PERSON_ID">
        <generator class="native"/>
    </id>
    <property name="age"/>
    <property name="firstname"/>
    <property name="lastname"/>

    <set name="events" table="PERSON_EVENT">
        <key column="PERSON_ID"/>
        <many-to-many column="EVENT_ID" class="Event"/>
    </set>

</class
>

Hibernate supporte toutes sortes de mappage de collection, un set étant le plus commun. Pour une association plusieurs-à-plusieurs (ou une relation d'entité n:m), une table d'association est requise. Chaque ligne dans cette table représente un lien entre une personne et un événement. Le nom de la table est configuré avec l'attribut table de l'élément set. Le nom de la colonne identifiant dans l'association, du côté de la personne, est défini avec l'élément key, et le nom de la colonne pour l'événement avec l'attribut column de many-to-many. Vous devez aussi donner à Hibernate la classe des objets de votre collection (c'est-à-dire : la classe de l'autre côté de la collection).

Le schéma de base de données pour ce mappage est donc :

    _____________        __________________
   |             |      |                  |       _____________
   |   EVENTS    |      |   PERSON_EVENT   |      |             |
   |_____________|      |__________________|      |    PERSON   |
   |             |      |                  |      |_____________|
   | *EVENT_ID   | <--> | *EVENT_ID        |      |             |
   |  EVENT_DATE |      | *PERSON_ID       | <--> | *PERSON_ID  |
   |  TITLE      |      |__________________|      |  AGE        |
   |_____________|                                |  FIRSTNAME  |
                                                  |  LASTNAME   |
                                                  |_____________|
 

Réunissons quelques personnes et quelques événements dans une nouvelle méthode dans EventManager :

    private void addPersonToEvent(Long personId, Long eventId) {

        Session session = HibernateUtil.getSessionFactory().getCurrentSession();
        session.beginTransaction();
        Person aPerson = (Person) session.load(Person.class, personId);
        Event anEvent = (Event) session.load(Event.class, eventId);
        aPerson.getEvents().add(anEvent);
        session.getTransaction().commit();
    }

Après le chargement d'une Person et d'un Event, modifiez simplement la collection en utilisant les méthodes normales de la collection. Comme vous pouvez le constater, il n'y a pas d'appel explicite à update() ou save(), Hibernate détecte automatiquement que la collection a été modifiée et a besoin d'être mise à jour. Ceci est appelé la vérification sale automatique (automatic dirty checking), et vous pouvez aussi l'essayer en modifiant le nom ou la propriété date de n'importe lequel de vos objets. Tant qu'ils sont dans un état persistant, c'est-à-dire, liés à une Session Hibernate particulière (c-à-d qu'ils ont juste été chargés ou sauvegardés dans une unité de travail), Hibernate surveille les changements et exécute le SQL correspondants. Le processus de synchronisation de l'état de la mémoire avec la base de données, généralement seulement à la fin d'une unité de travail, est appelé flushing. Dans notre code, l'unité de travail s'achève par un commit (ou rollback) de la transaction avec la base de données.

Vous pourriez bien sûr charger une personne et un événement dans différentes unités de travail. Ou vous modifiez un objet à l'extérieur d'une Session, s'il n'est pas dans un état persistant (s'il était persistant avant, nous appelons cet état détaché). Vous pouvez même modifier une collection lorsqu'elle est détachée :

    private void addPersonToEvent(Long personId, Long eventId) {

        Session session = HibernateUtil.getSessionFactory().getCurrentSession();
        session.beginTransaction();
        Person aPerson = (Person) session
                .createQuery("select p from Person p left join fetch p.events where p.id = :pid")
                .setParameter("pid", personId)
                .uniqueResult(); // Eager fetch the collection so we can use it detached
        Event anEvent = (Event) session.load(Event.class, eventId);
        session.getTransaction().commit();
        // End of first unit of work
        aPerson.getEvents().add(anEvent); // aPerson (and its collection) is detached
        // Begin second unit of work
        Session session2 = HibernateUtil.getSessionFactory().getCurrentSession();
        session2.beginTransaction();
        session2.update(aPerson); // Reattachment of aPerson
        session2.getTransaction().commit();
    }

L'appel à update rend un objet détaché à nouveau persistant, vous pourriez dire qu'il le lie à une nouvelle unité de travail, ainsi toutes les modifications que vous avez faites pendant qu'il était détaché peuvent être sauvegardées dans la base de données, cela inclut toute modification effectuées sur une collection de cet objet entité.

Cela n'a pas grand intérêt dans notre situation, mais c'est un concept important qu'il vous faut concevoir dans votre application. Pour le moment, complétez cet exercice en ajoutant une nouvelle action à la méthode principale de l'EventManager et invoquez-la depuis la ligne de commande. Si vous avez besoin des identifiants d'un client et d'un évènement - la méthode save() vous les retourne (vous devrez peut-être modifier certaines méthodes précédentes pour retourner ces identifiants) :

        else if (args[0].equals("addpersontoevent")) {

            Long eventId = mgr.createAndStoreEvent("My Event", new Date());
            Long personId = mgr.createAndStorePerson("Foo", "Bar");
            mgr.addPersonToEvent(personId, eventId);
            System.out.println("Added person " + personId + " to event " + eventId);
        }

C'était un exemple d'une association entre deux classes de même importance, deux entités. Comme mentionné plus tôt, il y a d'autres classes et d'autres types dans un modèle typique, généralement "moins importants". Vous en avez déjà vu certains, comme un int ou une String. Nous appelons ces classes des types de valeur, et leurs instances dépendent d'une entité particulière. Des instances de ces types n'ont pas leur propre identité, elles ne sont pas non plus partagées entre des entités (deux personnes ne référencent pas le même objet firstname, même si elles ont le même prénom). Bien sûr, des types de valeur n'existent pas seulement dans le JDK (en fait, dans une application Hibernate toutes les classes du JDK sont considérées comme des types de valeur), vous pouvez aussi écrire vous-même des classes dépendantes, Address ou MonetaryAmount, par exemple.

Vous pouvez aussi concevoir une collection de types de valeur. C'est conceptuellement très différent d'une collection de références vers d'autres entités, mais très ressemblant dans Java.

Ajoutons un ensemble d'adresses email à l'entité Person qui sera représenté en tant que java.util.Set d'instance java.lang.String :

    private Set emailAddresses = new HashSet();


    public Set getEmailAddresses() {
        return emailAddresses;
    }
    public void setEmailAddresses(Set emailAddresses) {
        this.emailAddresses = emailAddresses;
    }

Le mappage de ce Set :


        <set name="emailAddresses" table="PERSON_EMAIL_ADDR">
            <key column="PERSON_ID"/>
            <element type="string" column="EMAIL_ADDR"/>
        </set
>

La différence comparée au mappage vu plus tôt est la partie element, qui indique à Hibernate que la collection ne contient pas de référence vers une autre entité, mais une collection d'éléments de type String (le nom en minuscule vous indique que c'est un type/convertisseur du mappage Hibernate). Une fois encore, l'attribut table de l'élément set détermine le nom de la table pour la collection. L'élément key définit le nom de la colonne de la clé étrangère dans la table de la collection. L'attribut column dans l'élément element définit le nom de la colonne où les valeurs de String seront réellement stockées.

Considérons le schéma mis à jour :

  _____________        __________________
 |             |      |                  |       _____________
 |   EVENTS    |      |   PERSON_EVENT   |      |             |       ___________________
 |_____________|      |__________________|      |    PERSON   |      |                   |
 |             |      |                  |      |_____________|      | PERSON_EMAIL_ADDR |
 | *EVENT_ID   | <--> | *EVENT_ID        |      |             |      |___________________|
 |  EVENT_DATE |      | *PERSON_ID       | <--> | *PERSON_ID  | <--> |  *PERSON_ID       |
 |  TITLE      |      |__________________|      |  AGE        |      |  *EMAIL_ADDR      |
 |_____________|                                |  FIRSTNAME  |      |___________________|
                                                |  LASTNAME   |
                                                |_____________|
 

Vous pouvez voir que la clé primaire de la table de la collection est en fait une clé composée, utilisant les deux colonnes. Ceci implique aussi qu'il ne peut pas y avoir d'adresses email dupliquées par personne, ce qui est exactement la sémantique dont nous avons besoin pour un ensemble dans Java.

Vous pouvez maintenant tester et ajouter des éléments à cette collection, juste comme nous l'avons fait auparavant en liant des personnes et des événements. C'est le même code dans Java.

    private void addEmailToPerson(Long personId, String emailAddress) {

        Session session = HibernateUtil.getSessionFactory().getCurrentSession();
        session.beginTransaction();
        Person aPerson = (Person) session.load(Person.class, personId);
        // adding to the emailAddress collection might trigger a lazy load of the collection
        aPerson.getEmailAddresses().add(emailAddress);
        session.getTransaction().commit();
    }

Cette fois-ci, nous n'avons pas utilisé de requête de chargement fetch pour initialiser la collection. Traquez les logs SQL et tentez d'optimiser ce cas avec un chargement agressif.

Ensuite nous allons mapper une association bidirectionnelle - faire fonctionner l'association entre une personne et un événement à partir des deux côtés dans Java. Bien sûr, le schéma de la base de données ne change pas, nous avons toujours une pluralité plusieurs-à-plusieurs.

D'abord, ajoutez une collection de participants à la classe Event :

    private Set participants = new HashSet();


    public Set getParticipants() {
        return participants;
    }
    public void setParticipants(Set participants) {
        this.participants = participants;
    }

Maintenant mappez ce côté de l'association aussi, dans Event.hbm.xml.


        <set name="participants" table="PERSON_EVENT" inverse="true">
            <key column="EVENT_ID"/>
            <many-to-many column="PERSON_ID" class="events.Person"/>
        </set
>

Comme vous le voyez, ce sont des mappages de sets normaux dans les deux documents de mappage. Notez que les noms de colonne dans key et many-to-many sont inversés dans les 2 documents de mappage. L'ajout le plus important ici est l'attribut inverse="true" dans l'élément set du mappage de la collection des Events.

Cela signifie que Hibernate devrait prendre l'autre côté - la classe Person - quand il a besoin de trouver des informations à propos du lien entre les deux. Ce sera beaucoup plus facile à comprendre une fois que vous verrez comment le lien bidirectionnel entre les deux entités est créé.

Premièrement, gardez à l'esprit qu'Hibernate n'affecte pas la sémantique normale de Java. Comment avons-nous créé un lien entre une Person et un Event dans l'exemple unidirectionnel? Nous avons ajouté une instance de Event à la collection des références d'événement d'une instance de Person. Donc, évidemment, si vous voulons rendre ce lien bidirectionnel, nous devons faire la même chose de l'autre côté, en ajoutant une référence de Person à la collection dans un Event. Cette "configuration du lien des deux côtés" est absolument nécessaire et vous ne devriez jamais oublier de le faire.

Beaucoup de développeurs programment de manière défensive et créent des méthodes de gestion de lien pour affecter correctement les deux côtés, par exemple dans Person :

    protected Set getEvents() {

        return events;
    }
    protected void setEvents(Set events) {
        this.events = events;
    }
    public void addToEvent(Event event) {
        this.getEvents().add(event);
        event.getParticipants().add(this);
    }
    public void removeFromEvent(Event event) {
        this.getEvents().remove(event);
        event.getParticipants().remove(this);
    }

Notez que les méthodes get et set pour la collection sont maintenant protégées - ceci permet aux classes et aux sous-classes du même paquetage d'accéder aux méthodes, mais empêche quiconque de mettre le désordre directement dans les collections (enfin, presque). Vous devriez probablement faire de même avec la collection de l'autre côté.

Et à propos de l'attribut de mappage inverse ? Pour vous, et pour Java, un lien bidirectionnel consiste simplement à configurer correctement les références des deux côtés. Hibernate n'a cependant pas assez d'informations pour ordonner correctement les expressions SQL INSERT et UPDATE (pour éviter les violations de contrainte), et a besoin d'aide pour gérer proprement les associations bidirectionnelles. Rendre inverse un côté de l'association, indique à Hibernate de l'ignorer, pour le considérer comme un miroir de l'autre côté. Cela suffit à Hibernate pour gérer tous les problèmes de transformation d'un modèle de navigation directionnelle vers un schéma SQL de base de données. Les règles dont vous devez vous souvenir sont : toutes les associations bidirectionnelles ont besoin d'un côté marqué inverse. Dans une association un-à-plusieurs ce doit être le côté plusieurs, dans une association plusieurs-à-plusieurs, vous pouvez choisir n'importe quel côté, il n'y pas de différence.

Une application web Hibernate utilise la Session et Transaction comme une application autonome. Cependant, quelques modèles communs sont utiles. Nous allons coder une EventManagerServlet. Ce servlet peut lister tous les évènements stockés dans la base de données, et fournir une formulaire HTML pour saisir de nouveaux évènements.

Tout d'abord, nous devons créer notre servlet de base. La servlet n'accepte que les requêtes HTTP GET, la méthode à implémenter est donc doGet() :

package org.hibernate.tutorial.web;


// Imports
public class EventManagerServlet extends HttpServlet {
    protected void doGet(
            HttpServletRequest request,
            HttpServletResponse response) throws ServletException, IOException {
        SimpleDateFormat dateFormatter = new SimpleDateFormat( "dd.MM.yyyy" );
        try {
            // Begin unit of work
            HibernateUtil.getSessionFactory().getCurrentSession().beginTransaction();
            // Process request and render page...
            // End unit of work
            HibernateUtil.getSessionFactory().getCurrentSession().getTransaction().commit();
        }
        catch (Exception ex) {
            HibernateUtil.getSessionFactory().getCurrentSession().getTransaction().rollback();
            if ( ServletException.class.isInstance( ex ) ) {
                throw ( ServletException ) ex;
            }
            else {
                throw new ServletException( ex );
            }
        }
    }
}

Servir la servlet en tant que src/main/java/org/hibernate/tutorial/web/EventManagerServlet.java

Le modèle appliqué ici est appelé session-per-request. Lorsqu'une requête appelle la servlet, une nouvelle Session Hibernate est ouverte à la première invocation de getCurrentSession() sur la SessionFactory. Ensuite, une transaction avec la base de données est démarrée - tous les accès à la base de données interviennent au sein de la transaction, peu importe que les données soient lues ou écrites (nous n'utilisons pas le mode auto-commit dans les applications).

N'utilisez pas une nouvelle Session Hibernate pour chaque opération en base de données. Utilisez une Session Hibernate qui porte sur l'ensemble de la requête. Utlisez getCurrentSession(), ainsi elle est automatiquement attachée au thread Java courant.

Ensuite, les actions possibles de la requêtes sont exécutées et la réponse HTML est rendue. Nous y reviendrons ultérieurement.

Enfin, l'unité de travail s'achève lorsque l'exécution et le rendu sont achevés. Si un problème survient lors de ces deux phases, une exception est lancée et la transaction avec la base de données subit un rollback. Cela complète le modèle session-per-request. Au lieu d'avoir un code de délimitant les transactions au sein de chaque servlet, vous pouvez écrire un filtre de servlet. Voir le site Hibernate et le Wiki pour plus d'informations sur ce modèle, appelé Open Session in View - vous en aurez besoin dès que vous utiliserez des JSP et non des servlets pour le rendu de vos vues.

Implémentons l'exécution de la requête et le rendu de la page.

        // Write HTML header

        PrintWriter out = response.getWriter();
        out.println("<html
><head
><title
>Event Manager</title
></head
><body
>");
        // Handle actions
        if ( "store".equals(request.getParameter("action")) ) {
            String eventTitle = request.getParameter("eventTitle");
            String eventDate = request.getParameter("eventDate");
            if ( "".equals(eventTitle) || "".equals(eventDate) ) {
                out.println("<b
><i
>Please enter event title and date.</i
></b
>");
            }
            else {
                createAndStoreEvent(eventTitle, dateFormatter.parse(eventDate));
                out.println("<b
><i
>Added event.</i
></b
>");
            }
        }
        // Print page
       printEventForm(out);
       listEvents(out, dateFormatter);
       // Write HTML footer
       out.println("</body
></html
>");
       out.flush();
       out.close();

Ce style de code avec une mixture de Java et d'HTML ne serait pas extensible dans une application plus complexe - gardez à l'esprit que nous ne faisons qu'illustrer les concepts basiques de Hibernate dans ce didacticiel. Ce code affiche une entête et un pied de page HTML. Dans cette page, sont affichés un formulaire pour la saisie d'évènements ainsi qu'une liste de tous les évènements de la base de données. La première méthode est triviale et ne fait que sortir de l'HTML :

    private void printEventForm(PrintWriter out) {

        out.println("<h2
>Add new event:</h2
>");
        out.println("<form
>");
        out.println("Title: <input name='eventTitle' length='50'/><br/>");
        out.println("Date (e.g. 24.12.2009): <input name='eventDate' length='10'/><br/>");
        out.println("<input type='submit' name='action' value='store'/>");
        out.println("</form
>");
    }

La méthode listEvents() utilise la Session Hibernate liée au thread courant pour exécuter la requête :

    private void listEvents(PrintWriter out, SimpleDateFormat dateFormatter) {


        List result = HibernateUtil.getSessionFactory()
                .getCurrentSession().createCriteria(Event.class).list();
        if (result.size() 
> 0) {
            out.println("<h2
>Events in database:</h2
>");
            out.println("<table border='1'
>");
            out.println("<tr
>");
            out.println("<th
>Event title</th
>");
            out.println("<th
>Event date</th
>");
            out.println("</tr
>");
            Iterator it = result.iterator();
            while (it.hasNext()) {
                Event event = (Event) it.next();
                out.println("<tr
>");
                out.println("<td
>" + event.getTitle() + "</td
>");
                out.println("<td
>" + dateFormatter.format(event.getDate()) + "</td
>");
                out.println("</tr
>");
            }
            out.println("</table
>");
        }
    }

Enfin, l'action store renvoie à la méthode createAndStoreEvent(), qui utilise aussi la Session du thread courant:

    protected void createAndStoreEvent(String title, Date theDate) {

        Event theEvent = new Event();
        theEvent.setTitle(title);
        theEvent.setDate(theDate);
        HibernateUtil.getSessionFactory()
                .getCurrentSession().save(theEvent);
    }

La servlet est complétée. Une requête à la servlet sera exécutée par une seule Session et Transaction. Comme dans l'application autonome vue auparavant, Hibernate peut automatiquement lier ces objets au thread courant d'exécution. Cela vous laisse la liberté de séparer votre code en couches et d'accéder à la SessionFactory selon le moyen que vous aurez choisi. Généralement, vous utiliserez des conceptions plus sophistiquées et déplacerez le code d'accès aux données dans une couche DAO. Consultez le wiki Hibernate pour plus d'exemples.

Pour déployer cette application en vue de procéder à des tests, nous devons créer un WAR (Web ARchive). Tout d'abord, nous devons définir le descripteur WAR en tant que src/main/webapp/WEB-INF/web.xml


<?xml version="1.0" encoding="UTF-8"?>
<web-app version="2.4"
    xmlns="http://java.sun.com/xml/ns/j2ee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">

    <servlet>
        <servlet-name
>Event Manager</servlet-name>
        <servlet-class
>org.hibernate.tutorial.web.EventManagerServlet</servlet-class>
    </servlet>

    <servlet-mapping>
        <servlet-name
>Event Manager</servlet-name>
        <url-pattern
>/eventmanager</url-pattern>
    </servlet-mapping>
</web-app
>

Pour construire et déployer, appelez ant war dans votre projet et copiez le fichier hibernate-tutorial.war dans le répertoire webapp de Tomcat.

Note

If you do not have Tomcat installed, download it from http://tomcat.apache.org/ and follow the installation instructions. Our application requires no changes to the standard Tomcat configuration.

Une fois l'application déployée et Tomcat lancé, accédez à l'application via http://localhost:8080/hibernate-tutorial/eventmanager. Assurez vous de consulter les traces Tomcat pour observer l'initialisation d'Hibernate à la première requête touchant votre servlet (l'initialisation statique dans HibernateUtil est invoquée) et pour vérifier qu'aucune exception ne survienne.

Le diagramme ci-dessus procure une vue - (très) haut niveau - de l'architecture Hibernate :

Nous aimerions décrire une vue plus détaillée de l'architecture. Hibernate est flexible et prend en charge différentes approches. Nous allons en montrer les deux extrêmes : l'architecture "légère" et l'architecture "complète".

Ce diagramme montre Hibernate utilisant la base de données et des données de configuration pour fournir un service de persistance, et des objets persistants, à l'application.

L'architecture "légère" permet à l'application de fournir ses propres connexions JDBC et de gérer ses propres transactions. Cette approche utilise un sous-ensemble minimum des API Hibernate :

L'architecture "complète" abstrait l'application des API JDBC/JTA sous-jacentes et permet à Hibernate de s'occuper des détails.

Voici quelques définitions des objets dans les diagrammes :

SessionFactory (org.hibernate.SessionFactory)

Un cache threadsafe (immuable) de mappages compilés pour une base de données. En tant que fabrique de Session et que client du ConnectionProvider, SessionFactorypeut contenir un cache optionnel de données (de second niveau), réutilisable entre les différentes transactions, que cela soit au sein du même processus ou au niveau d'un cluster.

Session (org.hibernate.Session)

Un objet mono-threadé, à durée de vie courte, qui représente une conversation entre l'application et l'entrepôt de persistance. Encapsule une connexion JDBC. Fabrique des objets Transaction. La Session contient un cache (de premier niveau) des objets persistants, qui sont utilisés lors de la navigation dans le graphe d'objets ou lors de la récupération d'objets par leur identifiant.

Objets et collections persistants

Objets mono-threadés à vie courte, contenant état persistant et fonction commerciale. Ceux-ci sont en général des objets ordinaires de type JavaBean (ou POJO); la seule particularité est qu'ils sont associés avec une (et une seule) Session. Dès que la Session est fermée, ils sont détachés et libres d'être utilisés par n'importe quelle couche de l'application (par ex. de et vers la présentation).

Objets et collections éphémères (transient) et détachés

Instances de classes persistantes qui ne sont actuellement pas associées à une Session. Elles ont pu être instanciées par l'application et ne pas avoir (encore) été persistées, ou elle ont pu être instanciées par une Session fermée.

Transaction (org.hibernate.Transaction)

(Optionnel) Un objet mono-threadé à vie courte utilisé par l'application pour définir une unité de travail atomique. Abstrait l'application des transactions sous-jacentes, qu'elles soient JDBC, JTA ou CORBA. Une Session peut fournir plusieurs Transactions dans certains cas. Toutefois, la délimitation des transactions, via l'API d'Hibernate ou par la Transaction sous-jacente, n'est jamais optionnelle.

ConnectionProvider (org.hibernate.connection.ConnectionProvider)

(Optionnel) Une fabrique de (pool de) connexions JDBC. Abstrait l'application de la Datasource ou du DriverManager sous-jacent. Non exposé à l'application, mais peut être étendu/implémenté par le développeur.

TransactionFactory (org.hibernate.TransactionFactory)

(Optionnel) Une fabrique d'instances de Transaction. Non exposée à l'application, mais peut être étendue/implémentée par le développeur.

Extension Interfaces

Hibernate fournit de nombreuses interfaces d'extensions optionnelles que vous pouvez implémenter pour personnaliser le comportement de votre couche de persistance. Reportez vous à la documentation de l'API pour plus de détails.

Dans une architecture légère, l'application n'aura pas à utiliser les API Transaction/TransactionFactory et/ou n'utilisera pas les API ConnectionProvider pour utiliser directement JTA ou JDBC.

JMX est le standard J2EE de gestion des composants Java. Hibernate peut être géré via un service JMX standard. Nous fournissons une implémentation d'un MBean dans la distribution : org.hibernate.jmx.HibernateService.

Pour un exemple sur la manière de déployer Hibernate en tant que service JMX dans le serveur d'application JBoss Application Server, référez vous au guide de l'utilisateur JBoss (JBoss User Guide). Si vous déployez Hibernate via JMX sur JBoss AS, vous aurez également les avantages suivants :

Consultez le guide d'utilisation de JBoss AS pour plus d'informations sur ces options.

Another feature available as a JMX service is runtime Hibernate statistics. See Section 3.4.6, « Statistiques Hibernate » for more information.

Certaines applications utilisant Hibernate ont besoin d'une sorte de session "contextuelle", où une session donnée est en effet liée à la portée d'un contexte particulier. Cependant, les applications ne définissent pas toutes la notion de contexte de la même manière, et différents contextes définissent différentes portées à la notion de "courant". Les applications qui utilisaient Hibernate, versions précédentes à la 3.0, avaient tendance à employer un principe maison de sessions contextuelles basées sur le ThreadLocal, ainsi que sur des classes utilitaires comme HibernateUtil, ou utilisaient des framework tiers (comme Spring ou Pico) qui fournissaient des sessions contextuelles basées sur l'utilisation de proxy/interception.

A partir de la version 3.0.1, Hibernate a ajouté la méthode SessionFactory.getCurrentSession(). Initialement, cela demandait l'usage de transactions JTA, où la transaction JTA définissait la portée et le contexte de la session courante. L'équipe Hibernate pense que, étant donnée la maturité des nombreuses implémentations autonomes du JTA TransactionManager, la plupart (sinon toutes) des applications devraient utiliser la gestion des transactions par JTA qu'elles soient ou non déployées dans un conteneur J2EE. Par conséquent, il vous suffira de contextualiser vos sessions via la méthode basée sur JTA.

Cependant, depuis la version 3.1, la logique derrière SessionFactory.getCurrentSession() est désormais enfichable. A cette fin, une nouvelle interface d'extension(org.hibernate.context.CurrentSessionContext et un nouveau paramètre de configuration hibernate.current_session_context_class ont été ajoutés pour enficher la portée et le contexte de sessions courantes caractéristiques.

Pour une description détaillée de son contrat, consultez les Javadocs de l'interface org.hibernate.context.CurrentSessionContext. Elle définit une seule méthode, currentSession(), par laquelle l'implémentation est responsable de traquer la session contextuelle courante. Hibernate fournit trois implémentations de cette interface :

The first two implementations provide a "one session - one database transaction" programming model. This is also known and used as session-per-request. The beginning and end of a Hibernate session is defined by the duration of a database transaction. If you use programmatic transaction demarcation in plain JSE without JTA, you are advised to use the Hibernate Transaction API to hide the underlying transaction system from your code. If you use JTA, you can utilize the JTA interfaces to demarcate transactions. If you execute in an EJB container that supports CMT, transaction boundaries are defined declaratively and you do not need any transaction or session demarcation operations in your code. Refer to Chapitre 12, Transactions et Accès concurrents for more information and code examples.

Le paramètre de configuration hibernate.current_session_context_class définit quelle implémentation de org.hibernate.context.CurrentSessionContext doit être utilisée. Notez que pour assurer la compatibilité avec les versions précédentes, si ce paramètre n'est pas défini mais qu'un org.hibernate.transaction.TransactionManagerLookup est configuré, Hibernate utilisera le org.hibernate.context.JTASessionContext. La valeur de ce paramètre devrait juste nommer la classe d'implémentation à utiliser. Pour les trois implémentations prêtes à utiliser, toutefois, il y a trois noms brefs correspondants : "jta", "thread" et "managed".

Hibernate est conçu pour fonctionner dans de nombreux environnements , c'est pourquoi il existe beaucoup de paramètres de configuration. Heureusement, la plupart ont des valeurs par défaut appropriées et la Hibernate inclut un fichier d'exemples hibernate.properties dans le répertoire etc/ qui fournit les différentes options. Vous n'avez qu'à placer ce fichier dans votre classpath et à l'adapter à vos besoins.

Une instance de org.hibernate.cfg.Configuration représente un ensemble de mappages des classes Java d'une application vers la base de données SQL. La Configuration est utilisée pour construire un objet (immuable) SessionFactory. Les mappages sont constitués d'un ensemble de fichiers de mappage XML.

Vous pouvez obtenir une instance de Configuration en l'instanciant directement et en spécifiant la liste des documents XML de mappage. Si les fichiers de mappage sont dans le classpath, vous pouvez utiliser la méthode addResource() :

Configuration cfg = new Configuration()

    .addResource("Item.hbm.xml")
    .addResource("Bid.hbm.xml");

Une solution alternative consiste à spécifier la classe mappée et à donner à Hibernate la possibilité de trouver les documents de mappage pour vous :

Configuration cfg = new Configuration()

    .addClass(org.hibernate.auction.Item.class)
    .addClass(org.hibernate.auction.Bid.class);

Hibernate va rechercher les fichiers de mappages /org/hibernate/auction/Item.hbm.xml et /org/hibernate/auction/Bid.hbm.xml dans le classpath. Cette approche élimine les noms de fichiers en dur.

Une Configuration vous permet également de préciser des propriétés de configuration. Par exemple :

Configuration cfg = new Configuration()

    .addClass(org.hibernate.auction.Item.class)
    .addClass(org.hibernate.auction.Bid.class)
    .setProperty("hibernate.dialect", "org.hibernate.dialect.MySQLInnoDBDialect")
    .setProperty("hibernate.connection.datasource", "java:comp/env/jdbc/test")
    .setProperty("hibernate.order_updates", "true");

Ce n'est pas le seul moyen de passer des propriétés de configuration à Hibernate. Les différentes options sont :

Si vous souhaitez démarrer rapidement, hibernate.properties est l'approche la plus facile.

org.hibernate.cfg.Configuration est un objet de démarrage qui sera supprimé une fois qu'une SessionFactory aura été créée.

Il est conseillé que org.hibernate.SessionFactory crée les connexions JDBC et les mette dans un pool pour vous. Si vous suivez cette approche, ouvrir une org.hibernate.Session est aussi simple que :

Session session = sessions.openSession(); // open a new Session

Dès que vous initierez une action qui requiert un accès à la base de données, une connexion JDBC sera récupérée dans le pool.

À cet effet, il faut passer les propriétés de la connexion JDBC à Hibernate. Tous les noms des propriétés Hibernate et leur signification sont définies dans la classe org.hibernate.cfg.Environment. Nous allons maintenant décrire les paramètres de configuration des connexions JDBC les plus importants.

Hibernate obtiendra des connexions (et les mettra dans un pool) en utilisant java.sql.DriverManager si vous positionnez les paramètres de la manière suivante :


L'algorithme natif de pool de connexions de Hibernate est plutôt rudimentaire. Il a été conçu dans le but de vous aider à démarrer et n'est pas prévu pour un système en production ou même pour un test de performance. Utilisez plutôt un pool tiers pour de meilleures performances et une meilleure stabilité : remplacez la propriété hibernate.connection.pool_size avec les propriétés spécifiques au pool de connexions que vous avez choisi. Cela désactivera le pool de connexions interne de Hibernate. Vous pouvez par exemple utiliser C3P0.

C3P0 est un pool de connexions JDBC open source distribué avec Hibernate dans le répertoire lib. Hibernate utilisera son provider C3P0ConnectionProvider pour le pool de connexions si vous configurez les propriétés hibernate.c3p0.*. Si vous voulez utiliser Proxool, référez vous au groupe de propriétés hibernate.properties correspondant et consultez le site web Hibernate pour plus d'informations.

Voici un exemple de fichier hibernate.properties pour C3P0:

hibernate.connection.driver_class = org.postgresql.Driver
hibernate.connection.url = jdbc:postgresql://localhost/mydatabase
hibernate.connection.username = myuser
hibernate.connection.password = secret
hibernate.c3p0.min_size=5
hibernate.c3p0.max_size=20
hibernate.c3p0.timeout=1800
hibernate.c3p0.max_statements=50
hibernate.dialect = org.hibernate.dialect.PostgreSQLDialect

Pour l'utilisation de Hibernate au sein d'un serveur d'applications, il est recommandé de configurer Hibernate presque toujours de façon à ce qu'il obtienne ses connexions de la DataSource enregistrée du serveur d'applications dans le JNDI. À cet effet, vous devrez définir au moins une des propriétés suivantes :


Voici un exemple de fichier hibernate.properties pour l'utilisation d'une datasource JNDI fournie par un serveur d'applications :

hibernate.connection.datasource = java:/comp/env/jdbc/test
hibernate.transaction.factory_class = \
    org.hibernate.transaction.JTATransactionFactory
hibernate.transaction.manager_lookup_class = \
    org.hibernate.transaction.JBossTransactionManagerLookup
hibernate.dialect = org.hibernate.dialect.PostgreSQLDialect

Les connexions JDBC obtenues à partir d'une datasource JNDI participeront automatiquement aux transactions gérées par le conteneur du serveur d'applications.

Des propriétés arbitraires de connexion peuvent être passées en préfixant le nom de la propriété par "hibernate.connnection". Par exemple, vous pouvez spécifier un charSet en utilisant hibernate.connection.charSet.

Vous pouvez fournir votre propre stratégie d'obtention des connexions JDBC en implémentant l'interface org.hibernate.connection.ConnectionProvider. Vous pouvez sélectionner une implémentation spécifique par la propriété hibernate.connection.provider_class.

Il y a un certain nombre d'autres propriétés qui contrôlent le fonctionnement d'Hibernate à l'exécution. Toutes sont optionnelles et ont comme valeurs par défaut des valeurs raisonnables.

Tableau 3.3. Propriétés de configuration Hibernate

Nom de la propriétéFonction
hibernate.dialect Le nom de la classe d'un org.hibernate.dialect.Dialect Hibernate qui permet à Hibernate de générer du SQL optimisé pour une base de données relationnelle particulière.

par ex.full.classname.of.Dialect

Dans la plupart des cas, Hibernate sera en mesure de choisir l'implémentation org.hibernate.dialect.Dialect qui convient sur la base des métadonnées JDBC retournées par le driver JDBC.

hibernate.show_sql Écrit toutes les requêtes SQL sur la console. Il s'agit d'une alternative au paramétrage de la catégorie de log org.hibernate.SQL à debug.

par ex.true | false

hibernate.format_sql Effectue un pretty print du SQL dans la console et dans le log.

par ex.true | false

hibernate.default_schema Qualifie des noms de table non qualifiés avec le schéma/tablespace dans le SQL généré.

e.g. SCHEMA_NAME

hibernate.default_catalog Qualifie les noms de tables non qualifiées avec ce catalogue dans le SQL généré.

e.g. CATALOG_NAME

hibernate.session_factory_name org.hibernate.SessionFactory sera automatiquement liée à ce nom dans JNDI après sa création.

par ex.jndi/composite/name

hibernate.max_fetch_depth Configure la profondeur maximale d'un arbre de chargement par jointures externes pour les associations à cardinalité unitaire (un-à-un, plusieurs-à-un). Un 0 désactive le chargement par défaut par jointure externe.

par ex. valeurs recommandées entre 0 et 3

hibernate.default_batch_fetch_size Configure une taille par défaut pour le chargement par lot des associations Hibernate

ex. valeurs recommandées : 4, 8, 16

hibernate.default_entity_mode Sets a default mode for entity representation for all sessions opened from this SessionFactory

dynamic-map, dom4j, pojo

hibernate.order_updates Force Hibernate à trier les mises à jour SQL par la valeur de la clé primaire des éléments mis à jour. Cela permet de limiter les deadlocks de transaction dans les systèmes hautement concurrents.

par ex.true | false

hibernate.generate_statistics Si activé, Hibernate va collecter des statistiques utiles pour le réglage des performances.

par ex.true | false

hibernate.use_identifier_rollback Si activé, les propriétés correspondant à l'identifiant des objets sont remises aux valeurs par défaut lorsque les objets sont supprimés.

par ex.true | false

hibernate.use_sql_comments Si activé, Hibernate génère des commentaires à l'intérieur des requêtes SQL pour faciliter le débogage, par défaut à false.

par ex.true | false


Tableau 3.4. Propriétés Hibernate liées à JDBC et aux connexions

Nom de la propriétéFonction
hibernate.jdbc.fetch_size Une valeur non nulle détermine la taille des chargements JDBC (appelle Statement.setFetchSize()).
hibernate.jdbc.batch_size Une valeur non nulle active l'utilisation par Hibernate des mise à jour par lot de JDBC2.

ex. les valeurs recommandées entre 5 et 30

hibernate.jdbc.batch_versioned_data Set this property to true if your JDBC driver returns correct row counts from executeBatch(). It is usually safe to turn this option on. Hibernate will then use batched DML for automatically versioned data. Defaults to false.

par ex.true | false

hibernate.jdbc.factory_class Sélectionne un org.hibernate.jdbc.Batcher personnalisé. La plupart des applications n'auront pas besoin de cette propriété de configuration.

par.ex. classname.of.BatcherFactory

hibernate.jdbc.use_scrollable_resultset Active l'utilisation par Hibernate des ensembles de résultats déroulants de JDBC2. Cette propriété est seulement nécessaire lorsque l'on utilise des connexions JDBC fournies par l'utilisateur. Autrement, Hibernate utilise les métadonnées de la connexion.

par ex.true | false

hibernate.jdbc.use_streams_for_binary Utilise des flux lorsque l'on écrit/lit des types binary ou des types serializablevers/à partir de JDBC. *system-level property*

par ex.true | false

hibernate.jdbc.use_get_generated_keys Active l'utilisation de PreparedStatement.getGeneratedKeys() de JDBC3 pour récupérer nativement les clés générées après insertion. Nécessite un pilote JDBC3+ et JRE1.4+, configurés à false si votre pilote a des problèmes avec les générateurs d'identifiant Hibernate. Par défaut, essaie de déterminer les possibilités du pilote en utilisant les metadonnées de connexion.

par ex. true|false

hibernate.connection.provider_class Le nom de la classe d'un org.hibernate.connection.ConnectionProvider personnalisé qui fournit des connexions JDBC à Hibernate.

par ex.classname.of.ConnectionProvider

hibernate.connection.isolation Définit le niveau d'isolation des transactions JDBC. Regardez java.sql.Connection pour des valeurs significatives mais notez également que la plupart des bases de données ne supportent pas tous les niveaux d'isolation et que certaines définissent des isolations non standard supplémentaires.

par ex.1, 2, 4, 8

hibernate.connection.autocommit Active le mode de commit automatique (autocommit) pour les connexions JDBC du pool (non recommandé).

par ex.true | false

hibernate.connection.release_mode Spécifie à quel moment Hibernate doit relâcher les connexions JDBC. Par défaut, une connexion JDBC est conservée jusqu'à ce que la session soit explicitement fermée ou déconnectée. Pour une source de données JTA d'un serveur d'applications, vous devriez utiliser after_statement pour libérer les connexions de manière plus agressive après chaque appel JDBC. Pour une connexion non JTA, il est souvent préférable de libérer la connexion à la fin de chaque transaction en utilisant after_transaction. auto choisira after_statement pour les stratégies de transactions JTA et CMT et after_transaction pour des stratégies de transactions JDBC.

e.g. auto (default) | on_close | after_transaction | after_statement

This setting only affects Sessions returned from SessionFactory.openSession. For Sessions obtained through SessionFactory.getCurrentSession, the CurrentSessionContext implementation configured for use controls the connection release mode for those Sessions. See Section 2.5, « Sessions contextuelles  »

hibernate.connection.<propertyName> Passez une propriété JDBC propertyName à DriverManager.getConnection().
hibernate.jndi.<propertyName> Passez la propriété <propertyName> au JNDI InitialContextFactory.



Tableau 3.7. Propriétés diverses

Nom de la propriétéFonction
hibernate.current_session_context_class Supply a custom strategy for the scoping of the "current" Session. See Section 2.5, « Sessions contextuelles  » for more information about the built-in strategies.

e.g. jta | thread | managed | custom.Class

hibernate.query.factory_class Choisit l'implémentation du parseur de requête HQL.

par ex.org.hibernate.hql.ast.ASTQueryTranslatorFactory ou org.hibernate.hql.classic.ClassicQueryTranslatorFactory

hibernate.query.substitutions Lien entre les jetons de requêtes Hibernate et les jetons SQL (les jetons peuvent être des fonctions ou des noms textuels par exemple).

par ex.hqlLiteral=SQL_LITERAL, hqlFunction=SQLFUNC

hibernate.hbm2ddl.auto Valide ou exporte automatiquement le schéma DDL vers la base de données lorsque la SessionFactory est créée. La valeur create-drop permet de supprimer le schéma de base de données lorsque la SessionFactory est fermée explicitement.

par ex.validate | update | create | create-drop

hibernate.bytecode.use_reflection_optimizer

Enables the use of bytecode manipulation instead of runtime reflection. This is a System-level property and cannot be set in hibernate.cfg.xml. Reflection can sometimes be useful when troubleshooting. Hibernate always requires either CGLIB or javassist even if you turn off the optimizer.

par ex.true | false

hibernate.bytecode.provider

Both javassist or cglib can be used as byte manipulation engines; the default is javassist.

e.g. javassist | cglib


Il est recommandé de toujours positionner la propriété hibernate.dialect à la sous-classe de org.hibernate.dialect.Dialect appropriée à votre base de données. Si vous spécifiez un dialecte, Hibernate utilisera des valeurs adaptées pour certaines autres propriétés listées ci-dessus, vous évitant ainsi de l'effectuer à la main.


Hibernate utilise Simple Logging Facade for Java (SLF4J) pour enregistrer divers événements du système. SLF4J peut diriger votre sortie de logging vers plusieurs structures de loggings (NOP, Simple, log4j version 1.2, JDK 1.4 logging, JCL or logback) suivant la liaison que vous choisirez. Pour pouvoir configurer votre logging, vous aurez besoin de slf4j-api.jar dans votre chemin de classe, ainsi que du fichier jar pour votre liaison préférée - slf4j-log4j12.jar pour Log4J. Voir la documentation SLF4J documentation pour davantage d'informations. Pour utiliser Log4j, vous aurez aussi besoin de mettre un fichier log4j.properties dans votre chemin de classe. Un exemple de fichier de propriétés est distribué avec Hibernate dans le répertoire src/.

Il est vivement recommandé de vous familiariser avec les messages des logs de Hibernate. Beaucoup de soin a été apporté pour donner le plus de détails possible sans les rendre illisibles. C'est un outil essentiel en cas de problèmes. Les catégories de logs les plus intéressantes sont les suivantes :


Lorsque vous développez des applications avec Hibernate, vous devriez quasiment toujours travailler avec le niveau debug activé pour la catégorie org.hibernate.SQL, ou sinon avec la propriété hibernate.show_sql activée.

Une approche alternative est de spécifier toute la configuration dans un fichier nommé hibernate.cfg.xml. Ce fichier peut être utilisé à la place du fichier hibernate.properties, voire même peut servir à surcharger les propriétés si les deux fichiers sont présents.

Le fichier de configuration XML doit par défaut se placer à la racine du CLASSPATH. En voici un exemple :


<?xml version='1.0' encoding='utf-8'?>
<!DOCTYPE hibernate-configuration PUBLIC
    "-//Hibernate/Hibernate Configuration DTD//EN"
    "http://hibernate.sourceforge.net/hibernate-configuration-3.0.dtd">

<hibernate-configuration>

    <!-- a SessionFactory instance listed as /jndi/name -->
    <session-factory
        name="java:hibernate/SessionFactory">

        <!-- properties -->
        <property name="connection.datasource"
>java:/comp/env/jdbc/MyDB</property>
        <property name="dialect"
>org.hibernate.dialect.MySQLDialect</property>
        <property name="show_sql"
>false</property>
        <property name="transaction.factory_class">
            org.hibernate.transaction.JTATransactionFactory
        </property>
        <property name="jta.UserTransaction"
>java:comp/UserTransaction</property>

        <!-- mapping files -->
        <mapping resource="org/hibernate/auction/Item.hbm.xml"/>
        <mapping resource="org/hibernate/auction/Bid.hbm.xml"/>

        <!-- cache settings -->
        <class-cache class="org.hibernate.auction.Item" usage="read-write"/>
        <class-cache class="org.hibernate.auction.Bid" usage="read-only"/>
        <collection-cache collection="org.hibernate.auction.Item.bids" usage="read-write"/>

    </session-factory>

</hibernate-configuration
>

Comme vous pouvez le constater, l'avantage de cette approche est l'externalisation des noms des fichiers de mappage de la configuration. Le fichier hibernate.cfg.xml est également plus pratique quand on commence à régler le cache d'Hibernate. Notez que vous pouvez choisir entre utiliser hibernate.properties ou hibernate.cfg.xml, les deux sont équivalents, sauf en ce qui concerne les bénéfices de l'utilisation de la syntaxe XML mentionnés ci-dessus.

Avec la configuration XML, démarrer Hibernate devient donc aussi simple que ceci :

SessionFactory sf = new Configuration().configure().buildSessionFactory();

Vous pouvez choisir un fichier de configuration XML différent en utilisant :

SessionFactory sf = new Configuration()

    .configure("catdb.cfg.xml")
    .buildSessionFactory();

Hibernate possède les points d'intégration suivants pour l'infrastructure J2EE :

En fonction de votre environnement, vous mettrez l'option de configuration hibernate.connection.aggressive_release à true si le serveur d'applications affiche des exceptions de type "connection containment".

L'API de la Session Hibernate est indépendante de tout système de démarcation des transactions, présent dans votre architecture. Si vous laissez Hibernate utiliser l'API JDBC directement via un pool de connexion, vous commencerez et terminerez vos transactions en appelant l'API JDBC. Si votre application tourne à l'intérieur d'un serveur d'applications J2EE, vous utiliserez peut être les transactions gérées par les beans (BMT) et vous appellerez l'API JTA et UserTransaction lorsque cela est nécessaire.

Pour conserver votre code portable entre ces deux environnements (et d'autres), nous vous recommandons d'utiliser l'API optionnelle Transaction d'Hibernate, qui encapsule et masque le système de transaction sous-jacent. Pour cela, vous devez préciser une classe de fabrique d'instances de Transaction en positionnant la propriété de configuration hibernate.transaction.factory_class.

Il existe trois choix standards (intégrés) :

Vous pouvez également définir vos propres stratégies transactionnelles (pour un service de transaction CORBA par exemple).

Certaines fonctionnalités de Hibernate (c'est-à-dire le cache de second niveau, l'association automatique des Sessions à JTA, etc.) nécessitent l'accès au TransactionManager JTA dans un environnement géré. Dans un serveur d'applications, vous devez indiquer comment Hibernate peut obtenir une référence vers le TransactionManager, car J2EE ne fournit pas un seul mécanisme standard.


Une SessionFactory Hibernate associée au JNDI peut simplifier l'accès à la fabrique et donc la création de nouvelles Session s. Notez que cela n'est pas lié avec les Datasource associées au JNDI, elles utilisent juste le même registre !

Si vous désirez associer la SessionFactory à un nom JNDI, spécifiez un nom (par ex. java:hibernate/SessionFactory) en utilisant la propriété hibernate.session_factory_name. Si cette propriété est omise, la SessionFactory ne sera pas associée au JNDI (c'est particulièrement pratique dans les environnements ayant une implémentation JNDI par défaut en lecture seule, comme c'est le cas pour Tomcat).

Lorsqu'il associe la SessionFactory au JNDI, Hibernate utilisera les valeurs de hibernate.jndi.url, hibernate.jndi.class pour instancier un contexte d'initialisation. S'ils ne sont pas spécifiés, l'InitialContext par défaut sera utilisé.

Hibernate va automatiquement placer la SessionFactory dans JNDI après avoir appelé cfg.buildSessionFactory(). Cela signifie que vous devez avoir cet appel dans un code de démarrage (ou dans une classe utilitaire) dans votre application sauf si vous utilisez le déploiement JMX avec le service HibernateService présenté plus tard dans ce document.

Si vous utilisez SessionFactory JNDI, un EJB ou n'importe quelle autre classe peut obtenir la SessionFactory en utilisant une recherche JNDI.

Nous recommandons de lier la SessionFactory à JNDI dans les environnements gérés et d'utilisier un singleton static si ce n'est pas le cas. Pour isoler votre application de ces détails, nous vous recommandons aussi de masquer le code de recherche actuel pour une SessionFactory dans une classe helper, comme HibernateUtil.getSessionFactory(). Notez qu'une telle classe est aussi un moyen efficace de démarrer Hibernate - voir chapitre 1.

The easiest way to handle Sessions and transactions is Hibernate's automatic "current" Session management. For a discussion of contextual sessions see Section 2.5, « Sessions contextuelles  ». Using the "jta" session context, if there is no Hibernate Session associated with the current JTA transaction, one will be started and associated with that JTA transaction the first time you call sessionFactory.getCurrentSession(). The Sessions retrieved via getCurrentSession() in the "jta" context are set to automatically flush before the transaction completes, close after the transaction completes, and aggressively release JDBC connections after each statement. This allows the Sessions to be managed by the life cycle of the JTA transaction to which it is associated, keeping user code clean of such management concerns. Your code can either use JTA programmatically through UserTransaction, or (recommended for portable code) use the Hibernate Transaction API to set transaction boundaries. If you run in an EJB container, declarative transaction demarcation with CMT is preferred.

La ligne cfg.buildSessionFactory() doit toujours être exécutée quelque part pour obtenir une SessionFactory dans JNDI. Vous pouvez faire cela dans un bloc d'initialisation static (comme celui qui se trouve dans la classe HibernateUtil) ou vous pouvez déployer Hibernate en temps que service géré.

Hibernate est distribué avec org.hibernate.jmx.HibernateService pour le déploiement sur un serveur d'applications avec le support de JMX comme JBoss AS. Le déploiement et la configuration sont spécifiques à chaque vendeur. Voici un fichier jboss-service.xml d'exemple pour JBoss 4.0.x :


<?xml version="1.0"?>
<server>

<mbean code="org.hibernate.jmx.HibernateService"
    name="jboss.jca:service=HibernateFactory,name=HibernateFactory">

    <!-- Required services -->
    <depends
>jboss.jca:service=RARDeployer</depends>
    <depends
>jboss.jca:service=LocalTxCM,name=HsqlDS</depends>

    <!-- Bind the Hibernate service to JNDI -->
    <attribute name="JndiName"
>java:/hibernate/SessionFactory</attribute>

    <!-- Datasource settings -->
    <attribute name="Datasource"
>java:HsqlDS</attribute>
    <attribute name="Dialect"
>org.hibernate.dialect.HSQLDialect</attribute>

    <!-- Transaction integration -->
    <attribute name="TransactionStrategy">
        org.hibernate.transaction.JTATransactionFactory</attribute>
    <attribute name="TransactionManagerLookupStrategy">
        org.hibernate.transaction.JBossTransactionManagerLookup</attribute>
    <attribute name="FlushBeforeCompletionEnabled"
>true</attribute>
    <attribute name="AutoCloseSessionEnabled"
>true</attribute>

    <!-- Fetching options -->
    <attribute name="MaximumFetchDepth"
>5</attribute>

    <!-- Second-level caching -->
    <attribute name="SecondLevelCacheEnabled"
>true</attribute>
    <attribute name="CacheProviderClass"
>org.hibernate.cache.EhCacheProvider</attribute>
    <attribute name="QueryCacheEnabled"
>true</attribute>

    <!-- Logging -->
    <attribute name="ShowSqlEnabled"
>true</attribute>

    <!-- Mapping files -->
    <attribute name="MapResources"
>auction/Item.hbm.xml,auction/Category.hbm.xml</attribute>

</mbean>

</server
>

Ce fichier est déployé dans un répertoire META-INF et est empaqueté dans un fichier JAR avec l'extension .sar (service archive). Vous devez également empaqueter Hibernate, les librairies tierces requises, vos classes persistantes compilées et vos fichiers de mappage dans la même archive. Vos beans entreprise (souvent des EJB session) peuvent rester dans leur propre fichier JAR mais vous pouvez inclure ce fichier JAR dans le jar principal du service pour avoir une seule unité déployable à chaud. Vous pouvez consulter la documentation de JBoss AS pour plus d'informations sur les services JMX et le déploiement des EJB.

Les classes persistantes sont les classes d'une application qui implémentent les entités d'un problème métier (par ex. Client et Commande dans une application de commerce électronique). Toutes les instances d'une classe persistante ne sont pas forcément dans l'état persistant - en revanche, une instance peut être éphémère (transient) ou détachée.

Hibernate fonctionne de manière optimale lorsque ces classes suivent quelques règles simples, aussi connues comme le modèle de programmation Plain Old Java Object (POJO). Cependant, aucune de ces règles ne sont des besoins absolus. En effet, Hibernate3 présuppose très peu de choses à propos de la nature de vos objets persistants. Vous pouvez exprimer un modèle de domaine par d'autres moyens : utiliser des arbres d'instances de Map, par exemple.

Toute bonne application Java nécessite une classe persistante représentant les félins. Par exemple :

package eg;

import java.util.Set;
import java.util.Date;
public class Cat {
    private Long id; // identifier
    private Date birthdate;
    private Color color;
    private char sex;
    private float weight;
    private int litterId;
    private Cat mother;
    private Set kittens = new HashSet();
    private void setId(Long id) {
        this.id=id;
    }
    public Long getId() {
        return id;
    }
    void setBirthdate(Date date) {
        birthdate = date;
    }
    public Date getBirthdate() {
        return birthdate;
    }
    void setWeight(float weight) {
        this.weight = weight;
    }
    public float getWeight() {
        return weight;
    }
    public Color getColor() {
        return color;
    }
    void setColor(Color color) {
        this.color = color;
    }
    void setSex(char sex) {
        this.sex=sex;
    }
    public char getSex() {
        return sex;
    }
    void setLitterId(int id) {
        this.litterId = id;
    }
    public int getLitterId() {
        return litterId;
    }
    void setMother(Cat mother) {
        this.mother = mother;
    }
    public Cat getMother() {
        return mother;
    }
    void setKittens(Set kittens) {
        this.kittens = kittens;
    }
    public Set getKittens() {
        return kittens;
    }
    
    // addKitten not needed by Hibernate
    public void addKitten(Cat kitten) {
            kitten.setMother(this);
        kitten.setLitterId( kittens.size() ); 
        kittens.add(kitten);
    }
}

On explore quatre règles principales de classes persistantes en détail dans les sections qui suivent :

Vous devez surcharger les méthodes equals() et hashCode() si vous :

Hibernate garantit l'équivalence de l'identité persistante (ligne de base de données) et l'identité Java seulement à l'intérieur de la portée d'une session particulière. Donc dès que nous mélangeons des instances venant de différentes sessions, nous devons implémenter equals() et hashCode() si nous souhaitons avoir une sémantique correcte pour les Set s.

La manière la plus évidente est d'implémenter equals()/hashCode() en comparant la valeur de l'identifiant des deux objets. Si cette valeur est identique, les deux doivent représenter la même ligne de base de données, ils sont donc égaux (si les deux sont ajoutés à un Set, nous n'aurons qu'un seul élément dans le Set). Malheureusement, nous ne pouvons pas utiliser cette approche avec des identifiants générés ! Hibernate n'assignera de valeur d'identifiant qu'aux objets qui sont persistants, une instance nouvellement créée n'aura donc pas de valeur d'identifiant ! De plus, si une instance est non sauvegardée et actuellement dans un Set, le sauvegarder assignera une valeur d'identifiant à l'objet. Si equals() et hashCode() sont basées sur la valeur de l'identifiant, le code de hachage devrait changer, rompant le contrat du Set. Consultez le site web de Hibernate pour des informations plus approfondies. Notez que ceci n'est pas un problème Hibernate, mais concerne la sémantique normale de Java pour l'identité et l'égalité d'un objet.

Nous recommandons donc d'implémenter equals() et hashCode() en utilisant l'égalité par clé métier. L'égalité par clé métier signifie que la méthode equals() compare uniquement les propriétés qui forment une clé métier, une clé qui identifierait notre instance dans le monde réel (une clé candidate naturelle) :

public class Cat {


    ...
    public boolean equals(Object other) {
        if (this == other) return true;
        if ( !(other instanceof Cat) ) return false;
        final Cat cat = (Cat) other;
        if ( !cat.getLitterId().equals( getLitterId() ) ) return false;
        if ( !cat.getMother().equals( getMother() ) ) return false;
        return true;
    }
    public int hashCode() {
        int result;
        result = getMother().hashCode();
        result = 29 * result + getLitterId();
        return result;
    }
}

A business key does not have to be as solid as a database primary key candidate (see Section 12.1.3, « L'identité des objets »). Immutable or unique properties are usually good candidates for a business key.

Les entités persistantes ne doivent pas nécessairement être représentées comme des classes POJO ou des objets JavaBean à l'exécution. Hibernate supporte aussi les modèles dynamiques (en utilisant des Map s de Map s à l'exécution) et la représentation des entités comme des arbres DOM4J. Avec cette approche, vous n'écrivez pas de classes persistantes, seulement des fichiers de mappage.

By default, Hibernate works in normal POJO mode. You can set a default entity representation mode for a particular SessionFactory using the default_entity_mode configuration option (see Tableau 3.3, « Propriétés de configuration Hibernate »).

Les exemples suivants démontrent la représentation utilisant des Map s. D'abord, dans le fichier de mappage, un entity-name doit être déclaré au lieu (ou en plus) d'un nom de classe :


<hibernate-mapping>

    <class entity-name="Customer">

        <id name="id"
            type="long"
            column="ID">
            <generator class="sequence"/>
        </id>

        <property name="name"
            column="NAME"
            type="string"/>

        <property name="address"
            column="ADDRESS"
            type="string"/>

        <many-to-one name="organization"
            column="ORGANIZATION_ID"
            class="Organization"/>

        <bag name="orders"
            inverse="true"
            lazy="false"
            cascade="all">
            <key column="CUSTOMER_ID"/>
            <one-to-many class="Order"/>
        </bag>

    </class>
    
</hibernate-mapping
>

Notez que même si des associations sont déclarées en utilisant des noms de classe cible, le type de cible d'une association peut aussi être une entité dynamique au lieu d'un POJO.

Après avoir configuré le mode d'entité par défaut à dynamic-map pour la SessionFactory, nous pouvons lors de l'exécution fonctionner avec des Map s de Map s :

Session s = openSession();

Transaction tx = s.beginTransaction();
// Create a customer
Map david = new HashMap();
david.put("name", "David");
// Create an organization
Map foobar = new HashMap();
foobar.put("name", "Foobar Inc.");
// Link both
david.put("organization", foobar);
// Save both
s.save("Customer", david);
s.save("Organization", foobar);
tx.commit();
s.close();

Les avantages d'un mappage dynamique sont un gain de temps pour le prototypage sans la nécessité d'implémenter les classes d'entité. Pourtant, vous perdez la vérification du typage au moment de la compilation et aurez plus d'exceptions à gérer lors de l'exécution. Grâce au mappage de Hibernate, le schéma de la base de données peut facilement être normalisé et solidifié, permettant de rajouter une implémentation propre du modèle de domaine plus tard.

Les modes de représentation d'une entité peuvent aussi être configurés en se basant sur Session :

Session dynamicSession = pojoSession.getSession(EntityMode.MAP);


// Create a customer
Map david = new HashMap();
david.put("name", "David");
dynamicSession.save("Customer", david);
...
dynamicSession.flush();
dynamicSession.close()
...
// Continue on pojoSession

Veuillez noter que l'appel à getSession() en utilisant un EntityMode se fait sur l'API Session, et non sur SessionFactory. De cette manière, la nouvelle Session partage les connexions JDBC, transactions et autres informations de contexte sous-jacentes. Cela signifie que vous n'avez pas à appeler flush() et close() sur la Session secondaire, et laissez aussi la gestion de la transaction et de la connexion à l'unité de travail primaire.

More information about the XML representation capabilities can be found in Chapitre 19, Mappage XML.

org.hibernate.tuple.Tuplizer, et ses sous-interfaces, sont responsables de la gestion d'une représentation particulière d'un fragment de données, en fonction du org.hibernate.EntityMode de représentation. Si un fragment donné de données est considéré comme une structure de données, alors un tuplizer sait comment créer une telle structure de données, comment extraire des valeurs et injecter des valeurs dans une telle structure de données. Par exemple, pour le mode d'entité POJO, le tuplizer correspondant sait comment créer le POJO à travers son constructeur et comment accéder aux propriétés du POJO utilisant les accesseurs de la propriété définie.

Il y a deux types de Tuplizers de haut niveau, représentés par les interfaces org.hibernate.tuple.EntityTuplizer et org.hibernate.tuple.ComponentTuplizer. Les EntityTuplizer s sont responsables de la gestion des contrats mentionnés ci-dessus pour les entités, alors que les ComponentTuplizer s s'occupent des composants.

Les utilisateurs peuvent aussi brancher leurs propres tuplizers. Il vous faudra peut-être utiliser une implémentation de java.util.Map autre que java.util.HashMap dans le mode d'entité dynamic-map ; ou peut-être aurez vous besoin de définir une stratégie de génération de proxy différente de celle utilisée par défaut. Les deux devraient être effectuées en définissant une implémentation de tuplizer utilisateur. Les définitions de tuplizers sont attachées au mappage de l'entité ou du composant qu'ils devraient gérer. Revenons à l'exemple de notre entité utilisateur :


<hibernate-mapping>
    <class entity-name="Customer">
        <!--
            Override the dynamic-map entity-mode
            tuplizer for the customer entity
        -->
        <tuplizer entity-mode="dynamic-map"
                class="CustomMapTuplizerImpl"/>

        <id name="id" type="long" column="ID">
            <generator class="sequence"/>
        </id>

        <!-- other properties -->
        ...
    </class>
</hibernate-mapping>


public class CustomMapTuplizerImpl
        extends org.hibernate.tuple.entity.DynamicMapEntityTuplizer {
    // override the buildInstantiator() method to plug in our custom map...
    protected final Instantiator buildInstantiator(
            org.hibernate.mapping.PersistentClass mappingInfo) {
        return new CustomMapInstantiator( mappingInfo );
    }

    private static final class CustomMapInstantiator
            extends org.hibernate.tuple.DynamicMapInstantitor {
        // override the generateMap() method to return our custom map...
            protected final Map generateMap() {
                    return new CustomMap();
            }
    }
}

L'interface org.hibernate.EntityNameResolver représente un contrat pour résoudre le nom de l'entité d'une instance d'entité donnée. L'interface définit une méthode simple resolveEntityName, à qui l'on passe l'instance d'entité et qui doit retourner le nom d'entité qui convient (null est accepté et indiquerait que le resolver ne sait pas comment résoudre le nom de l'entité de l'instance d'entité donnée). Normalement, un org.hibernate.EntityNameResolver est surtout utile pour les modèles dynamiques. Vous pourriez, par exemple, utiliser des interfaces proxy comme modèle de domaine. La suite de test Hibernate comprend un exemple de ce style précis d'utilisation dans org.hibernate.test.dynamicentity.tuplizer2. Vous trouverez ci dessous une illustration du code de ce package.

/**

 * A very trivial JDK Proxy InvocationHandler implementation where we proxy an interface as
 * the domain model and simply store persistent state in an internal Map.  This is an extremely
 * trivial example meant only for illustration.
 */
public final class DataProxyHandler implements InvocationHandler {
        private String entityName;
        private HashMap data = new HashMap();
        public DataProxyHandler(String entityName, Serializable id) {
                this.entityName = entityName;
                data.put( "Id", id );
        }
        public Object invoke(Object proxy, Method method, Object[] args) throws Throwable {
                String methodName = method.getName();
                if ( methodName.startsWith( "set" ) ) {
                        String propertyName = methodName.substring( 3 );
                        data.put( propertyName, args[0] );
                }
                else if ( methodName.startsWith( "get" ) ) {
                        String propertyName = methodName.substring( 3 );
                        return data.get( propertyName );
                }
                else if ( "toString".equals( methodName ) ) {
                        return entityName + "#" + data.get( "Id" );
                }
                else if ( "hashCode".equals( methodName ) ) {
                        return new Integer( this.hashCode() );
                }
                return null;
        }
        public String getEntityName() {
                return entityName;
        }
        public HashMap getData() {
                return data;
        }
}
/**
 *
 */
public class ProxyHelper {
    public static String extractEntityName(Object object) {
        // Our custom java.lang.reflect.Proxy instances actually bundle
        // their appropriate entity name, so we simply extract it from there
        // if this represents one of our proxies; otherwise, we return null
        if ( Proxy.isProxyClass( object.getClass() ) ) {
            InvocationHandler handler = Proxy.getInvocationHandler( object );
            if ( DataProxyHandler.class.isAssignableFrom( handler.getClass() ) ) {
                DataProxyHandler myHandler = ( DataProxyHandler ) handler;
                return myHandler.getEntityName();
            }
        }
        return null;
    }
    // various other utility methods ....
}
/**
 * The EntityNameResolver implementation.
 * IMPL NOTE : An EntityNameResolver really defines a strategy for how entity names should be
 * resolved.  Since this particular impl can handle resolution for all of our entities we want to
 * take advantage of the fact that SessionFactoryImpl keeps these in a Set so that we only ever
 * have one instance registered.  Why?  Well, when it comes time to resolve an entity name,
 * Hibernate must iterate over all the registered resolvers.  So keeping that number down
 * helps that process be as speedy as possible.  Hence the equals and hashCode impls
 */
public class MyEntityNameResolver implements EntityNameResolver {
    public static final MyEntityNameResolver INSTANCE = new MyEntityNameResolver();
    public String resolveEntityName(Object entity) {
        return ProxyHelper.extractEntityName( entity );
    }
    public boolean equals(Object obj) {
        return getClass().equals( obj.getClass() );
    }
    public int hashCode() {
        return getClass().hashCode();
    }
}
public class MyEntityTuplizer extends PojoEntityTuplizer {
        public MyEntityTuplizer(EntityMetamodel entityMetamodel, PersistentClass mappedEntity) {
                super( entityMetamodel, mappedEntity );
        }
        public EntityNameResolver[] getEntityNameResolvers() {
                return new EntityNameResolver[] { MyEntityNameResolver.INSTANCE };
        }
    public String determineConcreteSubclassEntityName(Object entityInstance, SessionFactoryImplementor factory) {
        String entityName = ProxyHelper.extractEntityName( entityInstance );
        if ( entityName == null ) {
            entityName = super.determineConcreteSubclassEntityName( entityInstance, factory );
        }
        return entityName;
    }
    ...
}
        

Pour enregistrer un org.hibernate.EntityNameResolver, les utilisateurs doivent soit :

  1. Implement a custom Tuplizer, implementing the getEntityNameResolvers method.

  2. L'enregistrer dans org.hibernate.impl.SessionFactoryImpl (qui est la classe d'implémentation de org.hibernate.SessionFactory) à l'aide de la méthode registerEntityNameResolver.

Les mappages objet/relationnel sont généralement définis dans un document XML. Le document de mappage est conçu pour être lisible et éditable à la main. Le langage de mappage est Java-centrique, c'est-à-dire que les mappages sont construits à partir de déclarations de classes persistantes et non à partir de déclarations de tables.

Remarquez que même si beaucoup d'utilisateurs de Hibernate préfèrent écrire les fichiers de mappages XML à la main, plusieurs outils existent pour générer ce document, notamment XDoclet, Middlegen et AndroMDA.

Commençons avec un exemple de mappage :


<?xml version="1.0"?>
<!DOCTYPE hibernate-mapping PUBLIC
      "-//Hibernate/Hibernate Mapping DTD 3.0//EN"
          "http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd">

<hibernate-mapping package="eg">

        <class name="Cat"
            table="cats"
            discriminator-value="C">

                <id name="id">
                        <generator class="native"/>
                </id>

                <discriminator column="subclass"
                     type="character"/>

                <property name="weight"/>

                <property name="birthdate"
                    type="date"
                    not-null="true"
                    update="false"/>

                <property name="color"
                    type="eg.types.ColorUserType"
                    not-null="true"
                    update="false"/>

                <property name="sex"
                    not-null="true"
                    update="false"/>

                <property name="litterId"
                    column="litterId"
                    update="false"/>

                <many-to-one name="mother"
                    column="mother_id"
                    update="false"/>

                <set name="kittens"
                    inverse="true"
                    order-by="litter_id">
                        <key column="mother_id"/>
                        <one-to-many class="Cat"/>
                </set>

                <subclass name="DomesticCat"
                    discriminator-value="D">

                        <property name="name"
                            type="string"/>

                </subclass>

        </class>

        <class name="Dog">
                <!-- mapping for Dog could go here -->
        </class>

</hibernate-mapping
>

Étudions le contenu du document de mappage. Nous ne décrirons que les éléments et attributs du document utilisés par Hibernate à l'exécution. Le document de mappage contient aussi des attributs et éléments optionnels qui agissent sur le schéma de base de données exporté par l'outil de génération de schéma. (Par exemple l'attribut not-null).

Tous les mappages XML devraient utiliser le doctype indiqué. En effet vous trouverez le fichier DTD à l'URL ci-dessus, dans le répertoire hibernate-x.x.x/src/org/hibernate ou dans hibernate3.jar. Hibernate va toujours chercher la DTD dans son classpath en premier lieu. Si vous constatez des recherches de la DTD sur Internet, vérifiez votre déclaration de DTD par rapport au contenu de votre classpath.

Comme mentionné précédemment, Hibernate tentera en premier lieu de résoudre les DTD dans leur classpath. Il réussit à le faire en enregistrant une implémentation personnalisée de org.xml.sax.EntityResolver avec le SAXReader qu'il utilise pour lire les fichiers xml. Cet EntityResolver personnalisé reconnaît deux espaces de nommage systemId différents :

Un exemple d'utilisation de l'espace de nommage utilisateur:


<?xml version="1.0"?>
<!DOCTYPE hibernate-mapping PUBLIC '-//Hibernate/Hibernate Mapping DTD 3.0//EN' 'http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd' [
<!ENTITY version "3.5.6-Final">
<!ENTITY today "September 15, 2010">

    <!ENTITY types SYSTEM "classpath://your/domain/types.xml">


]>


<hibernate-mapping package="your.domain">
    <class name="MyEntity">
        <id name="id" type="my-custom-id-type">
            ...
        </id>
    <class>
    &types;
</hibernate-mapping>

Where types.xml is a resource in the your.domain package and contains a custom typedef.

Cet élément a plusieurs attributs optionnels. Les attributs schema et catalog indiquent que les tables mentionnées dans ce mappage appartiennent au schéma nommé et/ou au catalogue. S'ils sont spécifiés, les noms de tables seront qualifiés par les noms de schéma et de catalogue. L'attribut default-cascade indique quel type de cascade sera utilisé par défaut pour les propriétés et collections qui ne précisent pas l'attribut cascade. L'attribut auto-import nous permet d'utiliser par défaut des noms de classes non qualifiés dans le langage de requête, par défaut.

<hibernate-mapping
         schem(1)a="schemaName"
         catal(2)og="catalogName"
         defau(3)lt-cascade="cascade_style"
         defau(4)lt-access="field|property|ClassName"
         defau(5)lt-lazy="true|false"
         auto-(6)import="true|false"
         packa(7)ge="package.name"
 />

1

schema (optionnel) : le nom d'un schéma de base de données.

2

catalog (optionnel) : le nom d'un catalogue de base de données.

3

default-cascade (optionnel - par défaut vaut : none) : un type de cascade par défaut.

4

default-access (optionnel - par défaut vaut : property) : Comment hibernate accèdera aux propriétés. On peut aussi redéfinir sa propre implémentation de PropertyAccessor.

5

default-lazy (optionnel - par défaut vaut : true) : Valeur par défaut pour des attributs lazy non spécifiés des mappages de classe et de collection.

6

auto-import (optionnel - par défaut vaut : true) : spécifie si l'on peut utiliser des noms de classes non qualifiés (de classes de ce mappage) dans le langage de requête.

7

package (optionnel) : préfixe de paquetage par défaut pour les noms de classe non qualifiés du document de mappage.

Si deux classes persistantes possèdent le même nom de classe (non qualifié), vous devez configurer auto-import="false". Hibernate lancera une exception si vous essayez d'assigner le même nom "importé" à deux classes.

Notez que l'élément hibernate-mappage vous permet d'imbriquer plusieurs mappages de <class> persistantes, comme dans l'exemple ci-dessus. Cependant il est recommandé (et c'est parfois une exigence de certains outils) de mapper une seule classe persistante (ou une seule hiérarchie de classes) par fichier de mappage et de nommer ce fichier d'après le nom de la superclasse persistante, par exemple Cat.hbm.xml, Dog.hbm.xml, ou en cas d'héritage, Animal.hbm.xml.

Déclarez une classe persistante avec l'élément class. Part exemple :

<class
        name="(1)ClassName"
        table=(2)"tableName"
        discri(3)minator-value="discriminator_value"
        mutabl(4)e="true|false"
        schema(5)="owner"
        catalo(6)g="catalog"
        proxy=(7)"ProxyInterface"
        dynami(8)c-update="true|false"
        dynami(9)c-insert="true|false"
        select(10)-before-update="true|false"
        polymo(11)rphism="implicit|explicit"
        where=(12)"arbitrary sql where condition"
        persis(13)ter="PersisterClass"
        batch-(14)size="N"
        optimi(15)stic-lock="none|version|dirty|all"
        lazy="(16)true|false"
        entity(17)-name="EntityName"
        check=(18)"arbitrary sql check condition"
        rowid=(19)"rowid"
        subsel(20)ect="SQL expression"
        abstra(21)ct="true|false"
        node="element-name"
/>

1

name (optionnel) : le nom Java complet de la classe (ou interface) persistante. Si cet attribut est absent, nous supposons que ce mappage ne se rapporte pas à une entité POJO.

2

table (optionnel - par défaut le nom non-qualifié de la classe) : le nom de sa table en base de données.

3

discriminator-value (optionnel - par défaut le nom de la classe) : une valeur permettant de distinguer les différentes sous-classes utilisées dans le comportement polymorphique. Les valeurs null et not null sont autorisées.

4

mutable (optionnel, vaut true par défaut) : spécifie que des instances de la classe sont (ou non) immuables.

5

schema (optionnel) : surcharge le nom de schéma spécifié par l'élément racine <hibernate-mappage>.

6

catalog (optionnel) : surcharge le nom du catalogue spécifié par l'élément racine <hibernate-mappage>.

7

proxy (optionnel) : spécifie une interface à utiliser pour l'initialisation différée (lazy loading) des proxies. Vous pouvez indiquer le nom de la classe elle-même.

8

dynamic-update (optionnel, par défaut à false) : spécifie que les SQL UPDATE doivent être générés à l'exécution et contenir uniquement les colonnes dont les valeurs ont été modifiées.

9

dynamic-insert (optionnel, par défaut à false) : spécifie que les SQL INSERT doivent être générés à l'exécution et ne contenir que les colonnes dont les valeurs sont non nulles.

10

select-before-update (optionnel, par défaut à false): spécifie que Hibernate ne doit jamais exécuter un SQL UPDATE sans être certain qu'un objet a été réellement modifié. Dans certains cas, (en réalité, seulement quand un objet transient a été associé à une nouvelle session par update()), cela signifie que Hibernate exécutera un SQL SELECT pour déterminer si un SQL UPDATE est véritablement nécessaire.

11

polymorphism (optionnel, vaut implicit par défaut) : détermine si, pour cette classe, une requête polymorphique implicite ou explicite est utilisée.

12

where (optionnel) spécifie une clause SQL WHERE à utiliser lorsque l'on récupère des objets de cette classe.

13

persister (optionnel) : spécifie un ClassPersister particulier.

14

batch-size (optionnel, par défaut = 1) : spécifie une "taille de lot" pour remplir les instances de cette classe par identifiant en une seule requête.

15

optimistic-lock (optionnel, par défaut = version) : détermine la stratégie de verrouillage optimiste.

(16)

lazy (optionnel) : l'extraction différée (lazy fetching) peut être totalement désactivée en configurant lazy="false".

(17)

entity-name (optional - defaults to the class name): Hibernate3 allows a class to be mapped multiple times, potentially to different tables. It also allows entity mappings that are represented by Maps or XML at the Java level. In these cases, you should provide an explicit arbitrary name for the entity. See Section 4.4, « Modèles dynamiques » and Chapitre 19, Mappage XML for more information.

(18)

check (optionnel) : expression SQL utilisée pour générer une contrainte de vérification check multi-lignes pour la génération automatique de schéma.

(19)

rowid (optionnel) : Hibernate peut utiliser des ROWID sur les bases de données qui utilisent ce mécanisme. Par exemple avec Oracle, Hibernate peut utiliser la colonne additionnelle rowid pour des mise à jour rapides si cette option vaut rowid. Un ROWID est un détail d'implémentation et représente la localisation physique d'un uplet enregistré.

(20)

subselect (optionnel) : permet de mapper une entité immuable en lecture-seule sur un sous-select de base de données. Utile pour avoir une vue au lieu d'une table de base, mais à éviter. Voir plus bas pour plus d'informations.

(21)

abstract (optionnel) : utilisé pour marquer des superclasses abstraites dans des hiérarchies de <union-subclass>.

Il est tout à fait possible d'utiliser une interface comme nom de classe persistante. Vous devez alors déclarer les classes implémentant cette interface en utilisant l'élément <subclass>. Vous pouvez faire persister toute classe interne static. Vous devez alors spécifier le nom de la classe par la notation habituelle des classes internes, c'est à dire eg.Foo$Bar.

Les classes immuables, mutable="false", ne peuvent pas être modifiées ou supprimées par l'application. Cela permet à Hibernate de faire quelques optimisations mineures sur les performances.

L'attribut optionnel proxy permet les initialisations différées des instances persistantes de la classe. Hibernate retournera initialement des proxies CGLIB qui implémentent l'interface nommée. Le véritable objet persistant ne sera chargé que lorsqu'une méthode du proxy sera appelée. Voir plus bas le paragraphe abordant les Proxies et leur initialisation différée (lazy initialization).

Le polymorphisme implicite signifie que des instances de la classe seront retournées par une requête qui utilise les noms de la classe ou de chacune de ses superclasses ou encore des interfaces implémentées par cette classe ou ses superclasses. Les instances des classes filles seront retournées par une requête qui utilise le nom de la classe elle même. Le polymorphisme explicite signifie que les instances de la classe ne seront retournées que par une requête qui utilise explicitement son nom et que seules les instances des classes filles déclarées dans les éléments <subclass> ou <joined-subclass> seront retournées. Dans la majorités des cas la valeur par défaut, polymorphism="implicit", est appropriée. Le polymorphisme explicite est utile lorsque deux classes différentes sont mappées à la même table (ceci permet d'écrire une classe "légère" qui ne contient qu'une partie des colonnes de la table - voir la partie design pattern du site communautaire).

L'attribut persister vous permet de personnaliser la stratégie de persistance utilisée pour la classe. Vous pouvez, par exemple, spécifier votre propre sous-classe de org.hibernate.persister.EntityPersister ou vous pourriez aussi fournir une nouvelle implémentation de l'interface org.hibernate.persister.ClassPersister qui proposerait une persistance via, par exemple, des appels de procédures stockées, de la sérialisation vers des fichiers plats ou un annuaire LDAP. Voir org.hibernate.test.CustomPersister pour un exemple simple (d'une "persistance" vers une Hashtable).

Notez que les paramètres dynamic-update et dynamic-insert ne sont pas hérités par les sous-classes et peuvent donc être spécifiés pour les éléments <subclass> ou <joined-subclass>. Ces paramètres peuvent améliorer les performances dans certains cas, mais peuvent aussi les amoindrir. À utiliser en connaissance de causes.

L'utilisation de select-before-update va généralement faire baisser les performances. Ce paramètre est pratique pour éviter l'appel inutile par un déclenchement de mise à jour de base de donnée, quand on ré-attache un graphe d'instances à une Session.

Si vous utilisez le dynamic-update, les différentes stratégies de verrouillage optimiste sont les suivantes :

Nous encourageons très fortement l'utilisation de colonnes de version/timestamp pour le verrouillage optimiste avec Hibernate. C'est la meilleure stratégie en ce qui concerne les performances et la seule qui gère correctement les modifications sur les instances détachées (c'est à dire lorsqu'on utilise Session.merge()).

Il n'y a pas de différence entre table et vue pour le mappage Hibernate, comme on peut s'y attendre, cela est transparent au niveau base de données (remarquez que certaines BDD ne supportent pas les vues correctement, notamment pour les mise à jour). Il est possible que vous souhaitiez utiliser une vue mais vous ne puissiez pas en créer une sur votre BDD (c'est-à-dire avec un schéma ancien). Dans ces cas, vous pouvez mapper une entité immuable en lecture seule sur une expression sous-select SQL donnée :


<class name="Summary">
    <subselect>
        select item.name, max(bid.amount), count(*)
        from item
        join bid on bid.item_id = item.id
        group by item.name
    </subselect>
    <synchronize table="item"/>
    <synchronize table="bid"/>
    <id name="name"/>
    ...
</class
>

Déclarez les tables à synchroniser avec cette entité pour assurer que le flush automatique se produise correctement, et pour que les requêtes sur l'entité dérivée ne renvoient pas des données périmées. Le <subselect> est disponible comme attribut ou comme élément de mappage imbriqué.

Les classes mappées doivent déclarer la clé primaire de la table en base de données. La plupart des classes auront aussi une propriété de type JavaBeans présentant l'identifiant unique d'une instance. L'élément <id> sert à définir le mappage entre cette propriété et la colonne de la clé primaire.

<id
        name="(1)propertyName"
        type="(2)typename"
        column(3)="column_name"
        unsave(4)d-value="null|any|none|undefined|id_value"
        access(5)="field|property|ClassName">
        node="element-name|@attribute-name|element/@attribute|."

        <generator class="generatorClass"/>
</id
>

1

name (optionnel) : nom de la propriété de l'identifiant.

2

type (optionnel) : nom indiquant le type Hibernate.

3

column (optionnel - le nom de la propriété est pris par défaut) : nom de la colonne de la clé primaire.

4

unsaved-value (optionnel - devient par défaut une valeur "sensible") : une valeur de propriété d'identifiant qui indique que l'instance est nouvellement instanciée (non sauvegardée), et qui la distingue des instances détachées qui ont été sauvegardées ou chargées dans une session précédente.

5

access (optionnel - par défaut property) : la stratégie que doit utiliser Hibernate pour accéder aux valeurs des propriétés.

Si l'attribut name est absent, Hibernate considère que la classe ne possède pas de propriété d'identifiant.

L'attribut unsaved-value n'est presque jamais nécessaire dans Hibernate3.

La déclaration alternative <composite-id> permet l'accès aux données d'anciens systèmes qui utilisent des clés composées. Son utilisation est fortement déconseillée pour d'autres cas.

L'élément enfant <generator> nomme une classe Java utilisée pour générer les identifiants uniques pour les instances des classes persistantes. Si des paramètres sont requis pour configurer ou initialiser l'instance du générateur, ils sont passés en utilisant l'élément <param>.


<id name="id" type="long" column="cat_id">
        <generator class="org.hibernate.id.TableHiLoGenerator">
                <param name="table"
>uid_table</param>
                <param name="column"
>next_hi_value_column</param>
        </generator>
</id
>

Tous les générateurs implémentent l'interface org.hibernate.id.IdentifierGenerator. C'est une interface très simple ; certaines applications peuvent proposer leurs propres implémentations spécialisées. Cependant, Hibernate propose une série d'implémentations intégrées. Il existe des noms raccourcis pour les générateurs intégrés :

increment

génère des identifiants de type long, short ou int qui ne sont uniques que si aucun autre processus n'insère de données dans la même table. Ne pas utiliser en environnement clusterisé.

identity

prend en charge les colonnes d'identité dans DB2, MySQL, MS SQL Server, Sybase et HypersonicSQL. L'identifiant renvoyé est de type long, short ou int.

sequence

utilise une séquence dans DB2, PostgreSQL, Oracle, SAP DB, McKoi ou un générateur dans Interbase. L'identifiant renvoyé est de type long, short ou int

hilo

utilise un algorithme hi/lo pour générer de façon efficace des identifiants de type long, short ou int, en prenant comme source de valeurs "hi" une table et une colonne (par défaut hibernate_unique_key et next_hi respectivement). L'algorithme hi/lo génère des identifiants uniques pour une base de données particulière seulement.

seqhilo

utilise un algorithme hi/lo pour générer efficacement des identifiants de type long, short ou int, en prenant une séquence en base nommée.

uuid

utilise un algorithme de type UUID 128 bits pour générer des identifiants de type string, unique au sein d'un réseau (l'adresse IP est utilisée). Le UUID est encodé en une chaîne de nombre héxadécimaux de longueur 32.

guid

utilise une chaîne GUID générée par la base pour MS SQL Server et MySQL.

native

choisit identity, sequence ou hilo selon les possibilités offertes par la base de données sous-jacente.

assigned

permet à l'application d'affecter un identifiant à l'objet avant que la méthode save() soit appelée. Il s'agit de la stratégie par défaut si aucun <generator> n'est spécifié.

select

récupère une clé primaire assignée par un déclencheur (trigger) de base de données en sélectionnant la ligne par une clé unique quelconque et en extrayant la valeur de la clé primaire.

foreign

utilise l'identifiant d'un autre objet associé. Habituellement utilisé en conjonction avec une association <one-to-one> sur la clé primaire.

sequence-identity

Une stratégie de génération de séquence spécialisée qui utilise une séquence de base de données pour la génération réelle de valeurs, tout en utilisant JDBC3 getGeneratedKeys pour retourner effectivement la valeur d'identifiant générée, comme faisant partie de l'exécution de la déclaration insert. Cette stratégie est uniquement prise en charge par les pilotes Oracle 10g pour JDK 1.4. Notez que les commentaires sur ces déclarations insert sont désactivés à cause d'un bogue dans les pilotes d'Oracle.

A partir de la version 3.2.3, 2 générateurs représentent une nouvelle conception de 2 aspects séparés de la génération d'identifiants. Le premier aspect est la portabilité de la base de données; le second est l'optimization, c'est à dire que vous n'avez pas à interroger la base de données pour chaque requête de valeur d'identifiant. Ces deux nouveaux générateurs sont sensés prendre la place de générateurs décrits ci-dessus, ayant pour préfixe 3.3.x. Cependant, ils sont inclus dans les versions actuelles, et peuvent être référencés par FQN.

Le premier de ces nouveaux générateurs est org.Hibernate.ID.Enhanced.SequenceStyleGenerator qui est destiné, tout d'abord, comme un remplacement pour le générateur séquence et, deuxièmement, comme un générateur de portabilité supérieur à natif. C'est parce que natif a généralement le choix entre identité et séquence qui ont des sémantiques largement différentes, ce qui peut entraîner des problèmes subtils en observant la portabilité des applications. org.Hibernate.ID.Enhanced SequenceStyleGenerator., cependant, réalise la portabilité d'une manière différente. Il choisit entre une table ou une séquence dans la base de données pour stocker ses valeurs s'incrémentant, selon les capacités du dialecte utilisé. La différence avec natif c'est que de stockage basé sur les tables ou basé sur la séquence ont la même sémantique. En fait, les séquences sont exactement ce qu'Hibernate essaie d'émuler avec ses générateurs basée sur les tables. Ce générateur a un certain nombre de paramètres de configuration :

Le deuxième de ces nouveaux générateurs est org.Hibernate.ID.Enhanced.TableGenerator, qui est destiné, tout d'abord, comme un remplacement pour le générateur de la table, même si elle fonctionne effectivement beaucoup plus comme org.Hibernate.ID.MultipleHiLoPerTableGeneratoret deuxièmement, comme une remise en œuvre de org.Hibernate.ID.MultipleHiLoPerTableGenerator, qui utilise la notion d'optimizers enfichables. Essentiellement ce générateur définit une table susceptible de contenir un certain nombre de valeurs d'incrément différents simultanément à l'aide de plusieurs lignes distinctement masquées. Ce générateur a un certain nombre de paramètres de configuration :

  • table_name (en optin - valeur par défaut = hibernate_sequences): le nom de la table à utiliser.

  • value_column_name (en option - valeur par défaut =next_val): le nom de la colonne contenue dans la table utilisée pour la valeur.

  • segment_column_name (en option - par défaut = sequence_name): le nom de la colonne de la table qui est utilisée pour contenir la "segment key". Il s'agit de la valeur qui identifie la valeur d'incrément à utiliser.

  • segment_value (en option - par défaut = par défaut): La "segment key"valeur pour le segment à partir de laquelle nous voulons extraire des valeurs d'incrémentation pour ce générateur.

  • segment_value_length (en option - par défaut = 255): Utilisée pour la génération de schéma ; la taille de la colonne pour créer cette colonne de clé de segment.

  • initial_value (en option - par défaut est 1 : La valeur initiale à récupérer à partir de la table.

  • increment_size (en option - par défaut = 1): La valeur par laquelle les appels à la table, qui suivent, devront différer.

  • optimizer (optional - defaults to ): See Section 5.1.6, « Optimisation du générateur d'identifiants »

For identifier generators that store values in the database, it is inefficient for them to hit the database on each and every call to generate a new identifier value. Instead, you can group a bunch of them in memory and only hit the database when you have exhausted your in-memory value group. This is the role of the pluggable optimizers. Currently only the two enhanced generators (Section 5.1.5, « La méthode getter de l'identifiant  » support this operation.

  • aucun (en général il s'agit de la valeur par défaut si aucun optimizer n'a été spécifié): n'effectuera pas d'optimisations et n'interrogera pas la base de données à chaque demande.

  • hilo: applique un algorithme hi/lo autour des valeurs extraites des base de données. Les valeurs de la base de données de cet optimizer sont censées être séquentielles. Les valeurs extraites de la structure des base de données pour cet optimizer indique le "numéro de groupe". Le increment_size est multiplié par cette valeur en mémoire pour définir un groupe de "hi value".

  • mise en commun: tout comme dans le cas de hilo, cet optimizer tente de réduire le nombre d'interrogations vers la base de données. Ici, cependant, nous avons simplement stocké la valeur de départ pour le "prochain groupe"dans la structure de la base de données plutôt qu'une valeur séquentielle en combinaison avec un algorithme de regroupement en mémoire. Ici, increment_size fait référence aux valeurs provenant de la base de données.


<composite-id
        name="propertyName"
        class="ClassName"
        mapped="true|false"
        access="field|property|ClassName">
        node="element-name|."

        <key-property name="propertyName" type="typename" column="column_name"/>
        <key-many-to-one name="propertyName" class="ClassName" column="column_name"/>
        ......
</composite-id
>

Pour une table avec clé composée, vous pouvez mapper plusieurs attributs de la classe comme propriétés identifiantes. L'élément <composite-id> accepte les mappages de propriétés <key-property> et les mappages <key-many-to-one> comme éléments enfants.


<composite-id>
        <key-property name="medicareNumber"/>
        <key-property name="dependent"/>
</composite-id
>

Vos classes persistantes doivent surcharger les méthodes equals() et hashCode() pour implémenter l'égalité d'identifiant composite. Elles doivent aussi implémenter l'interface Serializable.

Malheureusement, cette approche signifie qu'un objet persistant est son propre identifiant. Il n'y a pas d'autre moyen pratique de "manipuler" l'objet que par l'objet lui-même. Vous devez instancier une instance de la classe persistante elle-même et peupler ses attributs identifiants avant de pouvoir appeler la méthode load() pour charger son état persistant associé à une clé composée. Nous appelons cette approche "identifiant composé embarqué" et ne la recommandons pas pour des applications complexes.

Une seconde approche, appelée identifiant composé mappé, consiste à dupliquer les propriétés identifiantes nommées dans l'élément <composite-id>) à la fois dans la classe persistante et dans une classe identifiante particulière.


<composite-id class="MedicareId" mapped="true">
        <key-property name="medicareNumber"/>
        <key-property name="dependent"/>
</composite-id
>

Dans cet exemple, la classe d'identifiant composée,MedicareId et la classe mappée elle-même, possèdent les propriétés medicareNumber et dependent. La classe identifiante doit redéfinir equals() et hashCode() et implémenter Serializable. Le désavantage de cette approche est la duplication du code.

Les attributs suivants servent à configurer un identifiant composé mappé :

We will describe a third, even more convenient approach, where the composite identifier is implemented as a component class in Section 8.4, « Les composants en tant qu'identifiants composites ». The attributes described below apply only to this alternative approach:

  • name (optionnel, requis pour cette approche) : une propriété de type composant qui contient l'identifiant composé (voir chapitre 9).

  • access (optionnel - par défaut property) : la stratégie que doit utiliser Hibernate pour accéder aux valeurs des propriétés.

  • class (optionnel - par défaut le type de la propriété déterminé par réflexion) : la classe composant utilisée comme identifiant (voir prochaine section).

La troisième approche, un composant d'identifiant, est celle que nous recommandons pour toutes vos applications.

L'élément <discriminator> est nécessaire pour la persistance polymorphique qui utilise la stratégie de mappage de table par hiérarchie de classe et déclare une colonne discriminante de la table. La colonne discriminante contient des valeurs marqueur qui permettent à la couche de persistance de savoir quelle sous-classe instancier pour une ligne particulière de table en base. Un nombre restreint de types peuvent être utilisés : string, character, integer, byte, short, boolean, yes_no, true_false.

<discriminator
        column(1)="discriminator_column"
        type="(2)discriminator_type"
        force=(3)"true|false"
        insert(4)="true|false"
        formul(5)a="arbitrary sql expression"
/>

1

column (optionnel - par défaut à class), le nom de la colonne discriminante.

2

type (optionnel - par défaut à string) un nom indiquant le type Hibernate.

3

force (optionnel - par défaut à false) "oblige" Hibernate à spécifier une valeur discriminante autorisée même quand on récupère toutes les instances de la classe de base.

4

insert (optionnel - par défaut à true) à passer à false si la colonne discriminante fait aussi partie d'un identifiant composé mappé (Indique à Hibernate de ne pas inclure la colonne dans les SQL INSERT s).

5

formula (optionnel) une expression SQL arbitraire qui est exécutée quand un type doit être évalué. Permet la discrimination basée sur le contenu.

Les véritables valeurs de la colonne discriminante sont spécifiées par l'attribut discriminator-value des éléments <class> et <subclass>.

L'attribut force n'est utile que si la table contient des lignes avec des valeurs "extra" discriminantes qui ne sont pas mappées à une classe persistante. Ce ne sera généralement pas le cas.

En utilisant l'attribut formula vous pouvez déclarer une expression SQL arbitraire qui sera utilisée pour évaluer le type d'une ligne :


<discriminator
    formula="case when CLASS_TYPE in ('a', 'b', 'c') then 0 else 1 end"
    type="integer"/>

L'élément <version> est optionnel et indique que la table contient des données versionnées. C'est particulièrement utile si vous avez l'intention d'utiliser des transactions longues (voir plus-bas).

<version
        column(1)="version_column"
        name="(2)propertyName"
        type="(3)typename"
        access(4)="field|property|ClassName"
        unsave(5)d-value="null|negative|undefined"
        genera(6)ted="never|always"
        insert(7)="true|false"
        node="element-name|@attribute-name|element/@attribute|."
/>

1

column (optionnel - par défaut égal au nom de la propriété) : le nom de la colonne contenant le numéro de version.

2

name : le nom d'un attribut de la classe persistante.

3

type (optionnel - par défaut à integer) : le type du numéro de version.

4

access (optionnel - par défaut property) : la stratégie que doit utiliser Hibernate pour accéder aux valeurs des propriétés.

5

unsaved-value (optionnel - par défaut à undefined) : une valeur de la propriété d'identifiant qui indique que l'instance est nouvellement instanciée (non sauvegardée), et qui la distingue des instances détachées qui ont été sauvegardées ou chargées dans une session précédente. Undefined indique que la valeur de la propritété identifiant devrait être utilisée.

6

generated (optional - defaults to never): specifies that this version property value is generated by the database. See the discussion of generated properties for more information.

7

insert (optionnel - par défaut à true) : indique si la colonne de version doit être incluse dans les ordres SQL insert. Peut être configuré à false si et seulement si la colonne de la base de données est définie avec une valeur par défaut égale à 0.

Les numéros de version doivent avoir les types Hibernate long, integer, short, timestamp ou calendar.

Une propriété de version ou un timestamp ne doit jamais être null pour une instance détachée, ainsi Hibernate pourra détecter toute instance ayant une version ou un timestamp null comme transient, quelles que soient les stratégies unsaved-value spécifiées. Déclarer un numéro de version ou un timestamp "nullable" est un moyen pratique d'éviter tout problème avec les ré-attachements transitifs dans Hibernate, particulièrement utile pour ceux qui utilisent des identifiants assignés ou des clés composées .

L'élément optionnel <timestamp> indique que la table contient des données horodatées (timestamped). Cela sert d'alternative à l'utilisation de numéros de version. Les timestamps (ou horodatage) sont par nature une implémentation moins fiable pour le verrouillage optimiste. Cependant, l'application peut parfois utiliser l'horodatage à d'autres fins.

<timestamp
        column(1)="timestamp_column"
        name="(2)propertyName"
        access(3)="field|property|ClassName"
        unsave(4)d-value="null|undefined"
        source(5)="vm|db"
        genera(6)ted="never|always"
        node="element-name|@attribute-name|element/@attribute|."
/>

1

column (optionnel - par défaut devient le nom de la propriété) : le nom d'une colonne contenant le timestamp.

2

name : le nom d'une propriété au sens JavaBean de type Java Date ou Timestamp de la classe persistante.

3

access (optionnel - par défaut property) : la stratégie que doit utiliser Hibernate pour accéder aux valeurs des propriétés.

4

unsaved-value (optionnel - par défaut à null) : propriété dont la valeur est un numéro de version qui indique que l'instance est nouvellement instanciée (non sauvegardée), et qui la distingue des instances détachées qui ont été sauvegardées ou chargées dans une session précédente. (undefined indique que la valeur de propriété identifiant devrait être utilisée).

5

source (optionnel - par défaut à vm) : d'où Hibernate doit-il récupérer la valeur du timestamp? Depuis la base de données ou depuis la JVM d'exécution? Les valeurs de timestamp de la base de données provoquent une surcharge puisque Hibernate doit interroger la base pour déterminer la prochaine valeur mais cela est plus sûr lorsque vous fonctionnez dans un cluster. Remarquez aussi que certains des Dialect s ne supportent pas cette fonction, et que d'autres l'implémentent mal, à cause d'un manque de précision (Oracle 8 par exemple).

6

generated (optional - defaults to never): specifies that this timestamp property value is actually generated by the database. See the discussion of generated properties for more information.

L'élément <property> déclare une propriété persistante de la classe au sens JavaBean.

<property
        name="(1)propertyName"
        column(2)="column_name"
        type="(3)typename"
        update(4)="true|false"
        insert(4)="true|false"
        formul(5)a="arbitrary SQL expression"
        access(6)="field|property|ClassName"
        lazy="(7)true|false"
        unique(8)="true|false"
        not-nu(9)ll="true|false"
        optimi(10)stic-lock="true|false"
        genera(11)ted="never|insert|always"
        node="element-name|@attribute-name|element/@attribute|."
        index="index_name"
        unique_key="unique_key_id"
        length="L"
        precision="P"
        scale="S"
/>

1

name : nom de la propriété, avec une lettre initiale en minuscule.

2

column (optionnel - par défaut au nom de la propriété) : le nom de la colonne mappée. Cela peut aussi être indiqué dans le(s) sous-élément(s) <column> imbriqués.

3

type (optionnel) : nom indiquant le type Hibernate.

4

update, insert (optionnel - par défaut à true) : indique que les colonnes mappées devraient être incluses dans des déclarations SQL UPDATE et/ou des INSERT. Mettre les deux à false autorise une propriété pure dérivée dont la valeur est initialisée de quelque autre propriété qui mappe à la même colonne(s) ou par un trigger ou une autre application. (utile si vous savez qu'un trigger affectera la valeur à la colonne).

5

formula (optionnel) : une expression SQL qui définit la valeur pour une propriété calculée. Les propriétés calculées ne possèdent pas leur propre mappage.

6

access (optionnel - par défaut property) : la stratégie que doit utiliser Hibernate pour accéder aux valeurs des propriétés.

7

lazy (optionnel - par défaut à false) : indique que cette propriété devrait être chargée en différé (lazy loading) quand on accède à la variable d'instance pour la première fois (nécessite une instrumentation du bytecode lors de la phase de construction).

8

unique (optionnel) : génère le DDL d'une contrainte d'unicité pour les colonnes. Permet aussi d'en faire la cible d'une property-ref.

9

not-null (optionnel) : génère le DDL d'une contrainte de nullité pour les colonnes.

10

optimistic-lock (optionnel - par défaut à true) : indique si les mise à jour de cette propriété nécessitent ou non l'acquisition d'un verrou optimiste. En d'autres termes, cela détermine s'il est nécessaire d'incrémenter un numéro de version quand cette propriété est marquée obsolète (dirty).

11

generated (optional - defaults to never): specifies that this property value is actually generated by the database. See the discussion of generated properties for more information.

typename peut être :

Si vous n'indiquez pas un type, Hibernate utilisera la réflexion sur le nom de la propriété pour tenter de trouver le type Hibernate correct. Hibernate essayera d'interprêter le nom de la classe retournée par le getter de la propriété en utilisant les règles 2, 3, 4 dans cet ordre. Dans certains cas vous aurez encore besoin de l'attribut type. (Par exemple, pour distinguer Hibernate.DATE et Hibernate.TIMESTAMP, ou pour préciser un type personnalisé).

L'attribut access permet de contrôler comment Hibernate accédera à la propriété à l'exécution. Par défaut, Hibernate utilisera les méthodes set/get. Si vous indiquez access="field", Hibernate ignorera les getter/setter et accédera à la propriété directement en utilisant la réflexion. Vous pouvez spécifier votre propre stratégie d'accès aux propriétés en nommant une classe qui implémente l'interface org.hibernate.propertexige une instrumentation de code d'octets build-timey.PropertyAccessor.

Les propriétés dérivées représentent une fonctionnalité particulièrement intéressante. Ces propriétés sont par définition en lecture seule, la valeur de la propriété est calculée au chargement. Le calcul est déclaré comme une expression SQL, qui se traduit par une sous-requête SELECT dans la requête SQL qui charge une instance :



<property name="totalPrice"
    formula="( SELECT SUM (li.quantity*p.price) FROM LineItem li, Product p
                WHERE li.productId = p.productId
                AND li.customerId = customerId
                AND li.orderNumber = orderNumber )"/>

Remarquez que vous pouvez référencer la propre table des entités en ne déclarant pas un alias sur une colonne particulière (customerId dans l'exemple donné). Notez aussi que vous pouvez utiliser le sous-élément de mappage <formula> plutôt que d'utiliser l'attribut si vous le souhaitez.

Une association ordinaire vers une autre classe persistante est déclarée en utilisant un élément many-to-one. Le modèle relationnel est une association de type plusieurs-à-un : une clé étrangère dans une table référence la ou les clé(s) primaire(s) dans la table cible.

<many-to-one
        name="(1)propertyName"
        column(2)="column_name"
        class=(3)"ClassName"
        cascad(4)e="cascade_style"
        fetch=(5)"join|select"
        update(6)="true|false"
        insert(6)="true|false"
        proper(7)ty-ref="propertyNameFromAssociatedClass"
        access(8)="field|property|ClassName"
        unique(9)="true|false"
        not-nu(10)ll="true|false"
        optimi(11)stic-lock="true|false"
        lazy="(12)proxy|no-proxy|false"
        not-fo(13)und="ignore|exception"
        entity(14)-name="EntityName"
        formul(15)a="arbitrary SQL expression"
        node="element-name|@attribute-name|element/@attribute|."
        embed-xml="true|false"
        index="index_name"
        unique_key="unique_key_id"
        foreign-key="foreign_key_name"
/>

1

name : le nom de la propriété.

2

column (optionnel) : le nom de la colonne de la clé étrangère. Cela peut être aussi spécifié par un ou des sous-élément(s) <column>.

3

class (optionnel - par défaut, le type de la propriété déterminé par réflexion) : le nom de la classe associée.

4

cascade (optionnel) : indique quelles opérations doivent être cascadées de l'objet parent vers l'objet associé.

5

fetch (optionnel - par défaut à select) : choisit entre le chargement de type jointure externe (outer-join) ou le chargement par select successifs.

6

update, insert (optionnel - par défaut à true) : indique que les colonnes mappées devraient être incluses dans des SQL UPDATE et/ou des déclarations INSERT. Mettre les deux à false, permet une association pure dérivée dont la valeur est initialisée à partir d'une autre propriété qui mappe à une ou plusieurs mêmes colonnes, ou par un trigger ou une autre application.

7

property-ref (optionnel) : le nom d'une propriété de la classe associée qui est jointe à cette clé étrangère. Si non-spécifiée, la clé primaire de la classe associée est utilisée.

8

access (optionnel - par défaut property) : la stratégie que doit utiliser Hibernate pour accéder aux valeurs des propriétés.

9

unique (optionnel) : génère le DDL d'une contrainte unique pour la clé étrangère. Permet aussi d'en faire la cible d'une property-ref. Cela permet de créer une véritable association un-à-un.

10

not-null (optionnel) : active le DDL d'une contrainte de nullité pour les colonnes de clés étrangères.

11

optimistic-lock (optionnel - par défaut à true) : indique si les mise à jour de cette propriété nécessitent ou non l'acquisition d'un verrou optimiste. En d'autres termes, cela détermine s'il est nécessaire d'incrémenter un numéro de version quand cette propriété est marquée obsolète (dirty).

12

lazy (optionnel - par défaut à proxy) : par défaut, les associations de point uniques utilisent des proxies. lazy="no-proxy" indique que cette propriété doit être chargée en différé au premier accès à la variable d'instance (nécessite une instrumentation du bytecode lors de la phase de construction). lazy="false" indique que l'association sera toujours chargée.

13

not-found (optionnel - par défaut = exception) : spécifie comment les clés étrangères qui référencent des lignes manquantes seront gérées : ignore traitera une ligne manquante comme une association nulle.

14

entity-name (optionnel) : le nom de l'entité de la classe associée.

15

formula (optionnel) : une expression SQL qui définit la valeur pour une clé étrangère calculée.

Setting a value of the cascade attribute to any meaningful value other than none will propagate certain operations to the associated object. The meaningful values are divided into three categories. First, basic operations, which include: persist, merge, delete, save-update, evict, replicate, lock and refresh; second, special values: delete-orphan; and third, all comma-separated combinations of operation names: cascade="persist,merge,evict" or cascade="all,delete-orphan". See Section 10.11, « Persistance transitive » for a full explanation. Note that single valued, many-to-one and one-to-one, associations do not support orphan delete.

Une déclaration many-to-one typique est aussi simple que :


<many-to-one name="product" class="Product" column="PRODUCT_ID"/>

L'attribut property-ref devrait être utilisé pour mapper seulement des données provenant d'un ancien système où les clés étrangères font référence à une clé unique de la table associée et qui n'est pas la clé primaire. C'est un cas de mauvaise conception relationnelle. Par exemple, supposez que la classe Product ait un numéro de série unique qui n'est pas la clé primaire. L'attribut unique contrôle la génération DDL par Hibernate avec l'outil SchemaExport.


<property name="serialNumber" unique="true" type="string" column="SERIAL_NUMBER"/>

Ainsi le mappage pour OrderItem peut utiliser :


<many-to-one name="product" property-ref="serialNumber" column="PRODUCT_SERIAL_NUMBER"/>

Bien que ce ne soit certainement pas encouragé.

Si la clé unique référencée comprend des propriétés multiples de l'entité associée, vous devez mapper ces propriétés à l'intérieur d'un élément nommé <properties>.

Si la clé unique référencée est la propriété d'un composant, vous pouvez spécifier le chemin de propriété :


<many-to-one name="owner" property-ref="identity.ssn" column="OWNER_SSN"/>

Une association un-à-un vers une autre classe persistante est déclarée avec l'élément one-to-one.

<one-to-one
        name="(1)propertyName"
        class=(2)"ClassName"
        cascad(3)e="cascade_style"
        constr(4)ained="true|false"
        fetch=(5)"join|select"
        proper(6)ty-ref="propertyNameFromAssociatedClass"
        access(7)="field|property|ClassName"
        formul(8)a="any SQL expression"
        lazy="(9)proxy|no-proxy|false"
        entity(10)-name="EntityName"
        node="element-name|@attribute-name|element/@attribute|."
        embed-xml="true|false"
        foreign-key="foreign_key_name"
/>

1

name : le nom de la propriété.

2

class (optionnel - par défaut, le type de la propriété déterminé par réflexion) : le nom de la classe associée.

3

cascade (optionnel) : indique quelles opérations doivent être cascadées de l'objet parent vers l'objet associé.

4

constrained (optionnel) : indique qu'une contrainte de clé étrangère sur la clé primaire de la table mappée référence la table de la classe associée. Cette option affecte l'ordre dans lequel chaque save() et chaque delete() est cascadé et détermine si l'association peut utiliser un proxy (aussi utilisé par l'outil SchemaExport).

5

fetch (optionnel - par défaut à select) : choisit entre le chargement de type jointure externe (outer-join) ou le chargement par select successifs.

6

property-ref (optionnel) : le nom de la propriété de la classe associée qui est jointe à la clé primaire de cette classe. Si ce n'est pas spécifié, la clé primaire de la classe associée est utilisée.

7

access (optionnel - par défaut property) : la stratégie que doit utiliser Hibernate pour accéder aux valeurs des propriétés.

8

formula (optionnel) : presque toutes les associations un-à-un pointent sur la clé primaire de l'entité propriétaire. Dans les rares cas différents, vous devez donner une ou plusieurs autres colonnes ou expression à joindre par une formule SQL . Voir org.hibernate.test.onetooneformula pour un exemple.

9

lazy (optionnel - par défaut proxy) : par défaut, les associations simples sont soumises à proxy. lazy="no-proxy" spécifie que la propriété doit être chargée en différé au premier accès à l'instance. (nécessite l'instrumentation du bytecode à la construction). lazy="false" indique que l'association sera toujours chargée agressivement. . Notez que si constrained="false", l'utilisation de proxy est impossible et Hibernate chargera automatiquement l'association .

10

entity-name (optionnel) : le nom de l'entité de la classe associée.

Il existe deux types d'associations un-à-un :

Les associations par clé primaire ne nécessitent pas une colonne supplémentaire en table ; si deux lignes sont liées par l'association alors les deux lignes de la table partagent la même valeur de clé primaire. Donc si vous voulez que deux objets soient liés par une association par clé primaire, vous devez faire en sorte qu'on leur assigne la même valeur d'identifiant.

Pour une association par clé primaire, ajoutez les mappages suivants à Employee et Person, respectivement :


<one-to-one name="person" class="Person"/>

<one-to-one name="employee" class="Employee" constrained="true"/>

Maintenant, vous devez faire en sorte que les clés primaires des lignes liées dans les tables PERSON et EMPLOYEE sont égales. On utilise une stratégie Hibernate spéciale de génération d'identifiants appelée foreign :


<class name="person" table="PERSON">
    <id name="id" column="PERSON_ID">
        <generator class="foreign">
            <param name="property"
>employee</param>
        </generator>
    </id>
    ...
    <one-to-one name="employee"
        class="Employee"
        constrained="true"/>
</class
>

Une instance fraîchement enregistrée de Person se voit alors assignée la même valeur de clé primaire que l'instance de Employee référencée par la propriété employee de cette Person.

Alternativement, une clé étrangère avec contrainte d'unicité de Employee vers Person peut être indiquée ainsi :


<many-to-one name="person" class="Person" column="PERSON_ID" unique="true"/>

Et cette association peut être rendue bidirectionnelle en ajoutant ceci au mappage de Person :


<one-to-one name="employee" class="Employee" property-ref="person"/>

L'élément <component> mappe les propriétés d'un objet enfant aux colonnes d'une classe parente. Les composants peuvent en retour déclarer leurs propres propriétés, composants ou collections. Voir "Components" plus bas :

<component
        name="(1)propertyName"
        class=(2)"className"
        insert(3)="true|false"
        update(4)="true|false"
        access(5)="field|property|ClassName"
        lazy="(6)true|false"
        optimi(7)stic-lock="true|false"
        unique(8)="true|false"
        node="element-name|."
>

        <property ...../>
        <many-to-one .... />
        ........
</component
>

1

name : le nom de la propriété.

2

class (optionnel - par défaut au type de la propriété déterminé par réflexion) : le nom de la classe (enfant) du composant.

3

insert : les colonnes mappées apparaissent-elles dans les SQL INSERT s ?

4

update: les colonnes mappées apparaissent-elles dans les SQL UPDATE s ?

5

access (optionnel - par défaut property) : la stratégie que doit utiliser Hibernate pour accéder aux valeurs des propriétés.

6

lazy (optionnel - par défaut à false) : indique que ce composant doit être chargé en différé au premier accès à la variable d'instance (nécessite une instrumentation du bytecode lors de la phase de construction).

7

optimistic-lock (optionnel - par défaut à true) : spécifie si les mise à jour sur ce composant nécessitent ou non l'acquisition d'un verrou optimiste. En d'autres termes, cela détermine si une incrémentation de version doit avoir lieu quand la propriété est marquée obsolète (dirty).

8

unique (optionnel - par défaut à false) : Indique qu'une contrainte d'unicité existe sur toutes les colonnes mappées de ce composant.

Les balises enfant <property> mappent les propriétés de la classe enfant sur les colonnes de la table.

L'élément <component> permet de déclarer un sous-élément <parent> qui associe une propriété de la classe composant comme une référence arrière vers l'entité contenante.

The <dynamic-component> element allows a Map to be mapped as a component, where the property names refer to keys of the map. See Section 8.5, « Les composants dynamiques » for more information.

L'élément <properties> permet la définition d'un groupement logique nommé des propriétés d'une classe. L'utilisation la plus importante de cette construction est la possibilité pour une combinaison de propriétés d'être la cible d'un property-ref. C'est aussi un moyen pratique de définir une contrainte d'unicité multi-colonnes. Par exemple :

<properties
        name="(1)logicalName"
        insert(2)="true|false"
        update(3)="true|false"
        optimi(4)stic-lock="true|false"
        unique(5)="true|false"
>

        <property ...../>
        <many-to-one .... />
        ........
</properties
>

1

name : le nom logique d'un regroupement et non le véritable nom d'une propriété.

2

insert : les colonnes mappées apparaissent-elles dans les SQL INSERT s ?

3

update: les colonnes mappées apparaissent-elles dans les SQL UPDATE s ?

4

optimistic-lock (optionnel - par défaut à true) : indique si les mise à jour sur ce composant nécessitent ou non l'acquisition d'un verrou optimiste. En d'autres termes, cela détermine si une incrémentation de version doit avoir lieu quand la propriété est marquée obsolète (dirty).

5

unique (optionnel - par défaut à false) : Indique qu'une contrainte d'unicité existe sur toutes les colonnes mappées de ce composant.

Par exemple, si nous avons le mappage de <properties> suivant :


<class name="Person">
    <id name="personNumber"/>

    ...
    <properties name="name"
            unique="true" update="false">
        <property name="firstName"/>
        <property name="initial"/>
        <property name="lastName"/>
    </properties>
</class
>

Alors nous pourrions avoir une association sur des données d'un ancien système qui font référence à cette clé unique de la table Person au lieu de la clé primaire :


<many-to-one name="person"
         class="Person" property-ref="name">
    <column name="firstName"/>
    <column name="initial"/>
    <column name="lastName"/>
</many-to-one
>

Nous ne recommandons pas une telle utilisation, en dehors du contexte de mappage de données héritées d'anciens systèmes.

Il est également possible de mapper chaque sous-classe vers sa propre table (stratégie de mappage de type table-per-subclass). L'état hérité est récupéré en joignant la table de la super-classe. L'élément <joined-subclass> est utilisé. Par exemple :

<joined-subclass
        name="(1)ClassName"
        table=(2)"tablename"
        proxy=(3)"ProxyInterface"
        lazy="(4)true|false"
        dynamic-update="true|false"
        dynamic-insert="true|false"
        schema="schema"
        catalog="catalog"
        extends="SuperclassName"
        persister="ClassName"
        subselect="SQL expression"
        entity-name="EntityName"
        node="element-name">

        <key .... >

        <property .... />
        .....
</joined-subclass
>

1

name : le nom de classe complet de la sous-classe.

2

table: le nom de la table de la sous-classe.

3

proxy (optionnel) : indique une classe ou interface à utiliser pour l'initialisation différée des proxies.

4

lazy (optionnel, par défaut à true) : spécifier lazy="false" désactive l'utilisation de l'extraction différée.

Aucune colonne discriminante n'est nécessaire pour cette stratégie de mappage. Cependant, chaque sous-classe doit déclarer une colonne de table contenant l'objet identifiant qui utilise l'élément <key>. Le mappage au début de ce chapitre serait ré-écrit ainsi :


<?xml version="1.0"?>
<!DOCTYPE hibernate-mapping PUBLIC
        "-//Hibernate/Hibernate Mapping DTD//EN"
        "http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd">

<hibernate-mapping package="eg">

        <class name="Cat" table="CATS">
                <id name="id" column="uid" type="long">
                        <generator class="hilo"/>
                </id>
                <property name="birthdate" type="date"/>
                <property name="color" not-null="true"/>
                <property name="sex" not-null="true"/>
                <property name="weight"/>
                <many-to-one name="mate"/>
                <set name="kittens">
                        <key column="MOTHER"/>
                        <one-to-many class="Cat"/>
                </set>
                <joined-subclass name="DomesticCat" table="DOMESTIC_CATS">
                    <key column="CAT"/>
                    <property name="name" type="string"/>
                </joined-subclass>
        </class>

        <class name="eg.Dog">
                <!-- mapping for Dog could go here -->
        </class>

</hibernate-mapping
>

For information about inheritance mappings see Chapitre 9, Mapping d'héritage de classe .

Une troisième option est de mapper uniquement les classes concrètes d'une hiérarchie d'héritage vers des tables, (stratégie de type table-per-concrete-class) où chaque table définit tous les états persistants de la classe, y compris les états hérités. Dans Hibernate il n'est absolument pas nécessaire de mapper explicitement de telles hiérarchies d'héritage. Vous pouvez simplement mapper chaque classe avec une déclaration <class> différente. Cependant, si vous souhaitez utiliser des associations polymorphiques (c'est-à-dire une association vers la superclasse de votre hiérarchie), vous devez utiliser le mappage <union-subclass>. Par exemple :

<union-subclass
        name="(1)ClassName"
        table=(2)"tablename"
        proxy=(3)"ProxyInterface"
        lazy="(4)true|false"
        dynamic-update="true|false"
        dynamic-insert="true|false"
        schema="schema"
        catalog="catalog"
        extends="SuperclassName"
        abstract="true|false"
        persister="ClassName"
        subselect="SQL expression"
        entity-name="EntityName"
        node="element-name">

        <property .... />
        .....
</union-subclass
>

1

name : le nom de classe complet de la sous-classe.

2

table: le nom de la table de la sous-classe.

3

proxy (optionnel) : indique une classe ou interface à utiliser pour l'initialisation différée des proxies.

4

lazy (optionnel, par défaut à true) : spécifier lazy="false" désactive l'utilisation de l'extraction différée.

Aucune colonne discriminante ou colonne clé n'est requise pour cette stratégie de mappage.

For information about inheritance mappings see Chapitre 9, Mapping d'héritage de classe .

En utilisant l'élément <join>, il est possible de mapper des propriétés d'une classe sur plusieurs tables quand il existe une relation un-à-un entre les tables. Par exemple :

<join
        table=(1)"tablename"
        schema(2)="owner"
        catalo(3)g="catalog"
        fetch=(4)"join|select"
        invers(5)e="true|false"
        option(6)al="true|false">

        <key ... />

        <property ... />
        ...
</join
>

1

table : le nom de la table jointe.

2

schema (optionnel) : surcharge le nom de schéma spécifié par l'élément racine <hibernate-mappage>.

3

catalog (optionnel) : surcharge le nom du catalogue spécifié par l'élément racine <hibernate-mappage>.

4

fetch (optionnel - par défaut à join) : si positionné à join, Hibernate utilisera une jointure interne pour charger une jointure définie par une classe ou ses super-classes et une jointure externe pour une <jointure> définie par une sous-classe. Si positionné à select, Hibernate utilisera un select séquentiel pour une <jointure> définie sur une sous-classe, qui ne sera délivrée que si une ligne représente une instance de la sous-classe. Les jointures internes seront quand même utilisées pour charger une <jointure> définie par une classe et ses super-classes.

5

inverse (optionnel - par défaut à false) : si positionné à true, Hibernate n'essaiera pas d'insérer ou de mettre à jour les propriétés définies par cette jointure.

6

optionnel (optionnel - par défaut à false) : si positionné à true, Hibernate insèrera une ligne seulement si les propriétés définies par cette jointure sont non-nulles et utilisera toujours une jointure externe pour extraire les propriétés.

Par exemple, les informations d'adresse pour une personne peuvent être mappées vers une table séparée (tout en préservant des sémantiques de type valeur pour toutes ses propriétés) :


<class name="Person"
    table="PERSON">

    <id name="id" column="PERSON_ID"
>...</id>

    <join table="ADDRESS">
        <key column="ADDRESS_ID"/>
        <property name="address"/>
        <property name="zip"/>
        <property name="country"/>
    </join>
    ...

Cette fonctionnalité est souvent seulement utile pour les modèles de données hérités d'anciens systèmes, nous recommandons d'utiliser moins de tables que de classes et un modèle de domaine à granularité fine. Cependant, c'est utile pour passer d'une stratégie de mappage d'héritage à une autre dans une hiérarchie simple, comme nous le verrons plus tard.

Nous avons rencontré l'élément <key> à plusieurs reprises maintenant. Il apparaît partout que l'élément de mappage parent définit une jointure sur une nouvelle table, et définit la clé étrangère dans la table jointe, qui référence la clé primaire de la table d'origine :

<key
        column(1)="columnname"
        on-del(2)ete="noaction|cascade"
        proper(3)ty-ref="propertyName"
        not-nu(4)ll="true|false"
        update(5)="true|false"
        unique(6)="true|false"
/>

1

column (optionnel) : le nom de la colonne de la clé étrangère. Cela peut être aussi spécifié par un ou des sous-élément(s) <column>.

2

on-delete (optionnel, par défaut à noaction) : indique si la contrainte de clé étrangère possède la possibilité au niveau base de données de suppression en cascade.

3

property-ref (optionnel) : indique que la clé étrangère fait référence à des colonnes qui ne sont pas la clé primaire de la table d'origine (Pour les données d'anciens systèmes).

4

not-null (optionnel) : indique que les colonnes des clés étrangères ne peuvent pas être nulles (c'est implicite si la clé étrangère fait partie de la clé primaire).

5

update (optionnel) : indique que la clé étrangère ne devrait jamais être mise à jour (implicite si celle-ci fait partie de la clé primaire).

6

unique (optionnel) : indique que la clé étrangère doit posséder une contrainte d'unicité (implicite si la clé étrangère est aussi la clé primaire).

Là où les suppressions doivent être performantes, nous recommandons pour les systèmes de définir toutes les clés on-delete="cascade", ainsi Hibernate utilisera une contrainte ON CASCADE DELETE au niveau base de données, plutôt que de nombreux DELETE individuels. Attention, cette fonctionnalité court-circuite la stratégie habituelle de verrou optimiste pour les données versionnées.

Les attributs not-null et update sont utiles pour mapper une association un-à-plusieurs unidirectionnelle. Si vous mappez un un-à-plusieurs unidirectionnel vers une clé étrangère non nulle, vous devez déclarer la colonne de la clé en utilisant <key not-null="true">.

Il existe encore un type de mappage de propriété. L'élément de mappage <any> définit une association polymorphique vers des classes de tables multiples. Ce type de mappage requiert toujours plus d'une colonne. La première colonne contient le type de l'entité associée. Les colonnes restantes contiennent l'identifiant. Il est impossible de spécifier une contrainte de clé étrangère pour ce type d'association, donc ce n'est certainement pas considéré comme le moyen habituel de mapper des associations (polymorphiques). Ne doit être utilisé que dans des cas particuliers (par exemple des logs d'audit, des données de session utilisateur, etc...).

L'attribut meta-type permet à l'application de spécifier un type personnalisé qui mappe des valeurs de colonnes de base de données sur des classes persistantes qui ont un attribut identifiant du type spécifié par id-type. Vous devez spécifier le mappage à partir de valeurs du méta-type sur les noms des classes.


<any name="being" id-type="long" meta-type="string">
    <meta-value value="TBL_ANIMAL" class="Animal"/>
    <meta-value value="TBL_HUMAN" class="Human"/>
    <meta-value value="TBL_ALIEN" class="Alien"/>
    <column name="table_name"/>
    <column name="id"/>
</any
>
<any
        name="(1)propertyName"
        id-typ(2)e="idtypename"
        meta-t(3)ype="metatypename"
        cascad(4)e="cascade_style"
        access(5)="field|property|ClassName"
        optimi(6)stic-lock="true|false"
>
        <meta-value ... />
        <meta-value ... />
        .....
        <column .... />
        <column .... />
        .....
</any
>

1

name : le nom de la propriété.

2

id-type : le type identifiant.

3

meta-type (optionnel - par défaut à string) : tout type permis pour un mappage par discriminateur.

4

cascade (optionnel - par défaut à none) : le style de cascade.

5

access (optionnel - par défaut property) : la stratégie que doit utiliser Hibernate pour accéder aux valeurs des propriétés.

6

optimistic-lock (optionnel - par défaut à true) : indique si les mise à jour sur cette propriété nécessitent ou non l'acquisition d'un verrou optimiste. En d'autres termes, définit si un incrément de version doit avoir lieu quand cette propriété est marquée dirty.

Pour le service de persistance, les objets sont classés en deux groupes au niveau langage Java :

Une entité existe indépendamment de tout autre objet possédant des références vers l'entité. Comparez cela avec le modèle Java habituel où un objet est supprimé par le garbage collector dès qu'il n'est plus référencé. Les entités doivent être explicitement enregistrées et supprimées (sauf dans les cas où sauvegardes et suppressions sont cascadées d'une entité parent vers ses enfants). C'est différent du modèle ODMG de persistance par atteignabilité - et correspond mieux à la façon dont les objets sont habituellement utilisés dans des grands systèmes. Les entités permettent les références circulaires et partagées. Elles peuvent aussi être versionnées.

L'état persistant d'une entité consiste en des références vers d'autres entités et instances de types valeurs. Ces valeurs sont des types primitifs, des collections (et non le contenu d'une collection), des composants de certains objets immuables. Contrairement aux entités, les valeurs (et en particulier les collections et composants) sont persistées et supprimées par atteignabiliité. Comme les valeurs (et types primitifs) sont persistées et supprimées avec l'entité qui les contient, ils ne peuvent pas posséder leurs propres versions. Les valeurs n'ont pas d'identité indépendantes, ainsi elles ne peuvent pas être partagées par deux entités ou collections.

Jusqu'à présent nous avons utilisé le terme "classe persistante" pour parler d'entités. Nous allons continuer à faire ainsi. Cependant, au sens strict, toutes les classes définies par un utilisateur possédant un état persistant ne sont pas des entités. Un composant est une classe définie par un utilisateur avec la sémantique d'une valeur. Une propriété Java de type java.lang.String a aussi les caractéristiques d'une valeur. Selon cette définition, nous sommes en mesure de déclarer que tous les types (classes) fournis par JDK possèdent la sémantique d'une valeur dans Java, alors que les types définis par un utilisateur pourront être mappés avec des sémantiques entités ou valeur type. Cette décision est prise par le développeur d'application. Un bon conseil pour une classe entité dans un modèle de domaine sont des références partagées à une instance unique de cette classe, alors que la composition ou l'agrégation se traduit en général par une valeur type.

Nous nous pencherons sur ces deux concepts tout au long de la documentation.

Le défi est de mapper les types Javas (et la définition des développeurs des entités et valeurs types) sur les types du SQL ou des bases de données. Le pont entre les deux systèmes est proposé par Hibernate : pour les entités nous utilisons <class>, <subclass> et ainsi de suite. Pour les types valeurs nous utilisons <property>, <component>, etc., habituellement avec un attribut type. La valeur de cet attribut est le nom d'un type de mappage Hibernate. Hibernate propose de nombreux mappages prêts à l'utilisation (pour les types de valeurs standards du JDK). Vous pouvez écrire vos propres types de mappages et implémenter aussi vos propres stratégies de conversion comme nous le verrons plus tard.

Tous les types proposés Hibernate à part les collections autorisent les sémantiques null.

Les types de mappage de base peuvent être classés de la façon suivante :

integer, long, short, float, double, character, byte, boolean, yes_no, true_false

Les mappages de type des primitives Java ou leurs classes wrappers (ex : Integer pour int) vers les types de colonne SQL (propriétaires) appropriés. boolean, yes_noet true_false sont tous des alternatives pour les types Java boolean ou java.lang.Boolean.

string

Mappage de type de java.lang.String vers VARCHAR (ou le VARCHAR2 Oracle).

date, time, timestamp

mappages de type pour java.util.Date et ses sous-classes vers les types SQL DATE, TIME et TIMESTAMP (ou équivalent).

calendar, calendar_date

mappages de type pour java.util.Calendar vers les types SQL TIMESTAMP et DATE (ou équivalent).

big_decimal, big_integer

mappages de type de java.math.BigDecimal et java.math.BigInteger vers NUMERIC (ou le NUMBER Oracle).

locale, timezone, currency

mappages de type pour java.util.Locale, java.util.TimeZone et java.util.Currency vers VARCHAR (ou le VARCHAR2 Oracle). Les instances de Locale et Currency sont mappées sur leurs codes ISO. Les instances de TimeZone sont mappées sur leur ID.

class

Un type de mappage de java.lang.Class vers VARCHAR (ou le VARCHAR2 Oracle). Un objet Class est mappé sur son nom Java complet.

binary

Mappe les tableaux de bytes vers le type binaire SQL approprié.

text

Mappe les longues chaînes de caractères Java vers les types SQL CLOB ou TEXT.

serializable

Mappe les types Java sérialisables vers le type SQL binaire approprié. Vous pouvez aussi indiquer le type Hibernate serializable avec le nom d'une classe Java sérialisable ou une interface qui ne soit pas par défaut un type de base.

clob, blob

Mappages de type pour les classes JDBC java.sql.Clob et java.sql.Blob. Ces types peuvent ne pas convenir pour certaines applications car un objet blob ou clob peut ne pas être réutilisable en dehors d'une transaction (de plus l'implémentation par les pilotes comporte des lacunes).

imm_date, imm_time, imm_timestamp, imm_calendar, imm_calendar_date, imm_serializable, imm_binary

Mappages de type pour ceux qui sont habituellement considérés comme des types Java modifiables, et pour lesquels Hibernate effectue certaines optimisations convenant seulement aux types Java immuables. L'application les traite comme immuables. Par exemple, vous ne devriez pas appeler Date.setTime() sur une instance mappée sur un imm_timestamp. Pour changer la valeur de la propriété, et faire en sorte que cette modification soit persistée, l'application doit assigner un nouvel (non identique) objet à la propriété.

Les identifiants uniques des entités et collections peuvent être de n'importe quel type de base excepté binary, blob et clob (les identifiants composites sont aussi permis, voir plus bas).

Les types de base des valeurs ont des Type constants correspondants et définis dans org.hibernate.Hibernate. Par exemple, Hibernate.STRING représente le type string.

Il est assez facile pour les développeurs de créer leurs propres types de valeurs. Par exemple, vous aimeriez persister des propriétés du type java.lang.BigInteger dans des colonnes VARCHAR. Hibernate ne procure pas de type par défaut à cet effet. Toutefois, les types personnalisés ne se limitent pas à mapper des propriétés (ou élément collection) à une simple colonne de table. Donc, par exemple, vous pourriez avoir une propriété Java getName()/setName() de type java.lang.String persistée dans les colonnes FIRST_NAME, INITIAL, SURNAME.

Pour implémenter votre propre type, vous pouvez soit implémenter org.hibernate.UserType soit org.hibernate.CompositeUserType et déclarer des propriétés utilisant des noms de classes complets du type. Consultez org.hibernate.test.DoubleStringType pour étudier les possibilités.


<property name="twoStrings" type="org.hibernate.test.DoubleStringType">
    <column name="first_string"/>
    <column name="second_string"/>
</property
>

Remarquez l'utilisation des balises <column> pour mapper une propriété sur des colonnes multiples.

Les interfaces CompositeUserType, EnhancedUserType, UserCollectionType, et UserVersionType prennent en charge des utilisations plus spécialisées.

Vous pouvez même fournir des paramètres en indiquant UserType dans le fichier de mappage. À cet effet, votre UserType doit implémenter l'interface org.hibernate.usertype.ParameterizedType. Pour spécifier des paramètres dans votre type propre, vous pouvez utiliser l'élément <type> dans vos fichiers de mappage.


<property name="priority">
    <type name="com.mycompany.usertypes.DefaultValueIntegerType">
        <param name="default"
>0</param>
    </type>
</property
>

Le UserType permet maintenant de récupérer la valeur pour le paramètre nommé default à partir de l'objet Properties qui lui est passé.

Si vous utilisez fréquemment un UserType, il est utile de lui définir un nom plus court. Vous pouvez l'effectuer, en utilisant l'élément <typedef>. Les typedefs permettent d'assigner un nom à votre type propre et peuvent aussi contenir une liste de valeurs de paramètres par défaut si ce type est paramétré.


<typedef class="com.mycompany.usertypes.DefaultValueIntegerType" name="default_zero">
    <param name="default"
>0</param>
</typedef
>

<property name="priority" type="default_zero"/>

Il est également possible de redéfinir les paramètres par défaut du typedef au cas par cas en utilisant des paramètres type sur le mappage de la propriété.

Alors que Hibernate offre une riche variété de types, et la prise en charge des composants, vous aurez très rarement besoin d'utiliser un type personnalisé, il est néanmoins recommandé d'utiliser des types personnalisés pour les classes (non entités) qui apparaissent fréquemment dans votre application. Par exemple, une classe MonetaryAmount est un bon candidat pour un CompositeUserType même si elle pourrait facilement être mappée en tant que composant. Une motivation pour cela est l'abstraction. Avec un type personnalisé, vos documents de mappage sont à l'abri des changements futurs dans votre façon de représenter des valeurs monétaires.

XML ne convient pas à tout le monde, il y a donc des moyens alternatifs pour définir des métadonnées de mappage O/R dans Hibernate.

De nombreux utilisateurs de Hibernate préfèrent embarquer les informations de mappages directement au sein du code source en utilisant lesbalises XDoclet @hibernate.tags. Nous ne couvrons pas cette approche dans ce document puisque cela est considéré comme faisant partie de XDoclet. Cependant, nous présentons l'exemple suivant de la classe Cat avec des mappages XDoclet :

package eg;

import java.util.Set;
import java.util.Date;
/**
 * @hibernate.class
 *  table="CATS"
 */
public class Cat {
    private Long id; // identifier
    private Date birthdate;
    private Cat mother;
    private Set kittens
    private Color color;
    private char sex;
    private float weight;
    /*
     * @hibernate.id
     *  generator-class="native"
     *  column="CAT_ID"
     */
    public Long getId() {
        return id;
    }
    private void setId(Long id) {
        this.id=id;
    }
    /**
     * @hibernate.many-to-one
     *  column="PARENT_ID"
     */
    public Cat getMother() {
        return mother;
    }
    void setMother(Cat mother) {
        this.mother = mother;
    }
    /**
     * @hibernate.property
     *  column="BIRTH_DATE"
     */
    public Date getBirthdate() {
        return birthdate;
    }
    void setBirthdate(Date date) {
        birthdate = date;
    }
    /**
     * @hibernate.property
     *  column="WEIGHT"
     */
    public float getWeight() {
        return weight;
    }
    void setWeight(float weight) {
        this.weight = weight;
    }
    /**
     * @hibernate.property
     *  column="COLOR"
     *  not-null="true"
     */
    public Color getColor() {
        return color;
    }
    void setColor(Color color) {
        this.color = color;
    }
    /**
     * @hibernate.set
     *  inverse="true"
     *  order-by="BIRTH_DATE"
     * @hibernate.collection-key
     *  column="PARENT_ID"
     * @hibernate.collection-one-to-many
     */
    public Set getKittens() {
        return kittens;
    }
    void setKittens(Set kittens) {
        this.kittens = kittens;
    }
    // addKitten not needed by Hibernate
    public void addKitten(Cat kitten) {
        kittens.add(kitten);
    }
    /**
     * @hibernate.property
     *  column="SEX"
     *  not-null="true"
     *  update="false"
     */
    public char getSex() {
        return sex;
    }
    void setSex(char sex) {
        this.sex=sex;
    }
}

Voyez le site web de Hibernate pour plus d'exemples sur XDoclet et Hibernate.

Le JDK 5.0 introduit des annotations proches de celles de XDoclet au niveau java, qui sont type-safe et vérifiées à la compilation. Ce mécanisme est plus puissant que XDoclet et mieux supporté par les outils et les IDE. IntelliJ IDEA, par exemple, supporte l'auto-complétion et le surlignement syntaxique des annotations JDK 5.0. La nouvelle révision des spécifications des EJB (JSR-220) utilise les annotations JDK 5.0 comme mécanisme primaire pour les metadonnées des beans entités. Hibernate3 implémente l'EntityManager de la JSR-220 (API de persistance), le support du mappage de métadonnées est disponible via le paquetage Hibernate Annotations, en tant que module séparé à télécharger. EJB3 (JSR-220) et les métadonnées Hibernate3 sont supportés.

Ceci est un exemple d'une classe POJO annotée comme un EJB entité :

@Entity(access = AccessType.FIELD)

public class Customer implements Serializable {
    @Id;
    Long id;
    String firstName;
    String lastName;
    Date birthday;
    @Transient
    Integer age;
    @Embedded
    private Address homeAddress;
    @OneToMany(cascade=CascadeType.ALL)
    @JoinColumn(name="CUSTOMER_ID")
    Set<Order
> orders;
    // Getter/setter and business methods
}

Hibernate allows you to customize the SQL it uses to read and write the values of columns mapped to simple properties. For example, if your database provides a set of data encryption functions, you can invoke them for individual columns like this:

<!-- XML : generated by JHighlight v1.0 (http://jhighlight.dev.java.net) -->
<span class="xml_tag_symbols">&lt;</span><span class="xml_tag_name">property</span><span class="xml_plain">&nbsp;</span><span class="xml_attribute_name">name</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">&quot;creditCardNumber&quot;</span><span class="xml_tag_symbols">&gt;</span><span class="xml_plain"></span><br />
<span class="xml_plain">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="xml_tag_symbols">&lt;</span><span class="xml_tag_name">column</span><span class="xml_plain">&nbsp;</span><br />
<span class="xml_plain">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="xml_attribute_name">name</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">&quot;credit_card_num&quot;</span><span class="xml_plain"></span><br />
<span class="xml_plain">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="xml_attribute_name">read</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">&quot;decrypt(credit_card_num)&quot;</span><span class="xml_plain"></span><br />
<span class="xml_plain">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="xml_attribute_name">write</span><span class="xml_tag_symbols">=</span><span class="xml_attribute_value">&quot;encrypt(?)&quot;</span><span class="xml_tag_symbols">/&gt;</span><span class="xml_plain"></span><br />
<span class="xml_tag_symbols">&lt;/</span><span class="xml_tag_name">property</span><span class="xml_plain"></span><br />
<span class="xml_tag_symbols">&gt;</span><span class="xml_plain"></span><br />

Hibernate applies the custom expressions automatically whenever the property is referenced in a query. This functionality is similar to a derived-property formula with two differences:

  • The property is backed by one or more columns that are exported as part of automatic schema generation.

  • The property is read-write, not read-only.

The write expression, if specified, must contain exactly one '?' placeholder for the value.

Permettent les ordres CREATE et DROP d'objets arbitraire de la base de données, en conjonction avec les outils Hibernate d'évolutions de schéma, pour permettre de définir complètement un schéma utilisateur au sein des fichiers de mappage Hibernate. Bien que conçu spécifiquement pour créer et supprimer des objets tels que les triggers et les procédures stockées, en réalité toute commande pouvant être exécutée via une méthode de java.sql.Statement.execute() (ALTERs, INSERTS, etc) est valable à cet endroit. Il y a principalement deux modes pour définir les objets auxiliaires de base de données :

Le premier mode est de lister explicitement les commandes CREATE et DROP dans le fichier de mappage :


<hibernate-mapping>
    ...
    <database-object>
        <create
>CREATE TRIGGER my_trigger ...</create>
        <drop
>DROP TRIGGER my_trigger</drop>
    </database-object>
</hibernate-mapping
>

Le second mode est de fournir une classe personnalisée qui sait comment construire les commandes CREATE et DROP. Cette classe personnalisée doit implémenter l'interface org.hibernate.mappage.AuxiliaryDatabaseObject.


<hibernate-mapping>
    ...
    <database-object>
        <definition class="MyTriggerDefinition"/>
    </database-object>
</hibernate-mapping
>

De plus, ces objets de base de données peuvent être optionnellement traités selon l'utilisation de dialectes particuliers.


<hibernate-mapping>
    ...
    <database-object>
        <definition class="MyTriggerDefinition"/>
        <dialect-scope name="org.hibernate.dialect.Oracle9iDialect"/>
        <dialect-scope name="org.hibernate.dialect.Oracle10gDialect"/>
    </database-object>
</hibernate-mapping
>

Hibernate requiert que les champs contenant des collections persistantes soient déclarés comme des types d'interface, par exemple :

public class Product {

    private String serialNumber;
    private Set parts = new HashSet();
    
    public Set getParts() { return parts; }
    void setParts(Set parts) { this.parts = parts; }
    public String getSerialNumber() { return serialNumber; }
    void setSerialNumber(String sn) { serialNumber = sn; }
}

L'interface réelle peut être java.util.Set, java.util.Collection, java.util.List, java.util.Map, java.util.SortedSet, java.util.SortedMap ou n'importe quoi d'autre ! (Où "n'importe quoi d'autre" signifie que vous devrez écrire une implémentation de org.hibernate.usertype.UserCollectionType.)

Notez comment nous avons initialisé la variable d'instance avec une instance de HashSet. C'est le meilleur moyen pour initialiser les collections d'instances nouvellement créées (non persistantes). Quand nous fabriquons l'instance persistante - en appelant persist(), par exemple - Hibernate remplacera réellement le HashSet par une instance d'une implémentation propre à Hibernate de Set. Prenez garde aux erreurs suivantes :

Cat cat = new DomesticCat();

Cat kitten = new DomesticCat();
....
Set kittens = new HashSet();
kittens.add(kitten);
cat.setKittens(kittens);
session.persist(cat);
kittens = cat.getKittens(); // Okay, kittens collection is a Set
(HashSet) cat.getKittens(); // Error!

Les collections persistantes injectées par Hibernate se comportent de la même manière que HashMap, HashSet, TreeMap, TreeSet ou ArrayList, selon le type de l'interface.

Les instances des collections ont le comportement habituel des types de valeurs. Elles sont automatiquement persistées quand elles sont référencées par un objet persistant et automatiquement effacées quand elles sont déréférencées. Si une collection est passée d'un objet persistant à un autre, ses éléments peuvent être déplacés d'une table à une autre. Deux entités ne peuvent pas partager une référence vers une même instance de collection. Dû au modèle relationnel sous-jacent, les propriétés contenant des collections ne supportent pas la sémantique de la valeur null ; Hibernate ne fait pas de distinction entre une référence de collection nulle et une collection vide.

Ne vous en souciez pas trop. Utilisez les collections persistantes de la même manière que vous utilisez des collections Java ordinaires. Assurez-vous de comprendre la sémantique des associations bidirectionnelles (traitée plus loin).

L'élément de mappage d'Hibernate utilisé pour mapper une collection dépend du type de l'interface. Par exemple, un élément <set> est utilisé pour mapper des propriétés de type Set.

<class name="Product">

    <id name="serialNumber" column="productSerialNumber"/>
    <set name="parts">
        <key column="productSerialNumber" not-null="true"/>
        <one-to-many class="Part"/>
    </set>
</class
>

À part <set>, il y aussi les éléments de mappage <list>, <map>, <bag>, <array> et <primitive-array>. L'élément <map> est représentatif :

<map
    name="prop(1)ertyName"
    table="tab(2)le_name"
    schema="sc(3)hema_name"
    lazy="true(4)|extra|false"
    inverse="t(5)rue|false"
    cascade="a(6)ll|none|save-update|delete|all-delete-orphan|delete-orphan"
    sort="unso(7)rted|natural|comparatorClass"
    order-by="(8)column_name asc|desc"
    where="arb(9)itrary sql where condition"
    fetch="joi(10)n|select|subselect"
    batch-size(11)="N"
    access="fi(12)eld|property|ClassName"
    optimistic(13)-lock="true|false"
    mutable="t(14)rue|false"
    node="element-name|."
    embed-xml="true|false"
>

    <key .... />
    <map-key .... />
    <element .... />
</map
>

1

name : le nom de la propriété contenant la collection

2

table (optionnel - par défaut = nom de la propriété) : le nom de la table de la collection (non utilisé pour les associations un-à-plusieurs)

3

schema (optionnel) : le nom du schéma pour surcharger le schéma déclaré dans l'élément racine

4

lazy (optionnel - par défaut = true) : peut être utilisé pour désactiver l'initialisation tardive et spécifier que l'association est toujours rapportée, ou pour activer la récupération extra-paresseuse (extra-lazy) où la plupart des opérations n'initialisent pas la collection (approprié pour de très grosses collections).

5

inverse (optionnel - par défaut = false) : définit cette collection comme l'extrémité "inverse" de l'association bidirectionnelle.

6

cascade (optionnel - par défaut = none) : active les opérations de cascade vers les entités filles.

7

sort (optionnel) : spécifie une collection triée via un ordre de tri naturel, ou via une classe comparateur donnée.

8

order-by (optionnel, seulement à partir du JDK1.4) : spécifie une colonne de table (ou des colonnes) qui définit l'ordre d'itération de Map, Set ou Bag, avec en option asc ou desc.

9

where (optionnel) : spécifie une condition SQL arbitraire WHERE à utiliser au chargement ou à la suppression d'une collection (utile si la collection ne doit contenir qu'un sous ensemble des données disponibles).

10

fetch (optionnel, par défaut = select) : à choisir entre récupération par jointures externes, récupération par selects séquentiels, et récupération par sous-selects séquentiels.

11

batch-size (optionnel, par défaut = 1) : une "taille de batch" utilisée pour charger plusieurs instances de cette collection.

12

access (optionnel - par défaut = property) : la stratégie que Hibernate doit utiliser pour accéder à la valeur de la propriété.

13

optimistic-lock (optionnel - par défaut = true) : spécifie que changer l'état des résultats de la collection entraîne l'incrémentation de la version appartenant à l'entité (Pour une association un-à-plusieurs, il est souvent raisonnable de désactiver ce paramètre).

14

mutable (optionnel - par défaut = true) : une valeur à false spécifie que les éléments de la collection ne changent jamais (une optimisation mineure dans certains cas).

Tous les mappages de collection, exceptés ceux avec les sémantiques d'ensemble (set) et de sac (bag), ont besoin d'une colonne d'index dans la table de la collection - une colonne qui mappe un index de tableau, ou un index de List, ou une clé de Map. L'index d'une Map peut être n'importe quel type basique, mappé avec <map-key>, ou peut être une référence d'entité mappée avec <map-key-many-to-many>, ou peut être un type composé, mappé avec <composite-map-key>. L'index d'un tableau ou d'une liste est toujours de type integer et est mappé en utilisant l'élément <list-index>. Les colonnes mappées contiennent des entiers séquentiels (numérotés à partir de zéro par défaut).

<list-index
        column(1)="column_name"
        base="(2)0|1|..."/>

1

column_name (required): the name of the column holding the collection index values.

1

base (optional - defaults to 0): the value of the index column that corresponds to the first element of the list or array.

<map-key
        column(1)="column_name"
        formul(2)a="any SQL expression"
        type="(3)type_name"
        node="@attribute-name"
        length="N"/>

1

column (optional): the name of the column holding the collection index values.

2

formula (optional): a SQL formula used to evaluate the key of the map.

3

type (required): the type of the map keys.

<map-key-many-to-many
        column(1)="column_name"
        formul(2)(3)a="any SQL expression"
        class="ClassName"
/>

1

column (optional): the name of the foreign key column for the collection index values.

2

formula (optional): a SQ formula used to evaluate the foreign key of the map key.

3

class (required): the entity class used as the map key.

Si votre table n'a pas de colonne d'index, et que vous souhaitez tout de même utiliser List comme type de propriété, vous devriez mapper la propriété comme un <bag> Hibernate. Un sac (bag) ne garde pas son ordre quand il est récupéré de la base de données, mais il peut être optionnellement trié ou ordonné.

Toute collection de valeurs ou association plusieurs-à-plusieurs requiert une table de collection avec une(des) colonne(s) de clé étrangère, une(des) colonne(s) d'élément de la collection ou des colonnes et éventuellement une(des) colonne(s) d'index.

Pour une collection de valeurs, nous utilisons la balise <element>. Par exemple :

<element
        column(1)="column_name"
        formul(2)a="any SQL expression"
        type="(3)typename"
        length="L"
        precision="P"
        scale="S"
        not-null="true|false"
        unique="true|false"
        node="element-name"
/>

1

column (optional): the name of the column holding the collection element values.

2

formula (optional): an SQL formula used to evaluate the element.

3

type (required): the type of the collection element.

A many-to-many association is specified using the <many-to-many> element.

<many-to-many
        column(1)="column_name"
        formul(2)a="any SQL expression"
        class=(3)"ClassName"
        fetch=(4)"select|join"
        unique(5)="true|false"
        not-fo(6)und="ignore|exception"
        entity(7)-name="EntityName"
        proper(8)ty-ref="propertyNameFromAssociatedClass"
        node="element-name"
        embed-xml="true|false"
    />

1

column (optional): the name of the element foreign key column.

2

formula (optional): an SQL formula used to evaluate the element foreign key value.

3

class (required): the name of the associated class.

4

fetch (optional - defaults to join): enables outer-join or sequential select fetching for this association. This is a special case; for full eager fetching in a single SELECT of an entity and its many-to-many relationships to other entities, you would enable join fetching,not only of the collection itself, but also with this attribute on the <many-to-many> nested element.

5

unique (optional): enables the DDL generation of a unique constraint for the foreign-key column. This makes the association multiplicity effectively one-to-many.

6

not-found (optional - defaults to exception): specifies how foreign keys that reference missing rows will be handled: ignore will treat a missing row as a null association.

7

entity-name (optional): the entity name of the associated class, as an alternative to class.

8

property-ref (optional): the name of a property of the associated class that is joined to this foreign key. If not specified, the primary key of the associated class is used.

Voici quelques exemples :

Un ensemble de chaînes de caractères :


<set name="names" table="person_names">
    <key column="person_id"/>
    <element column="person_name" type="string"/>
</set
>

Un sac contenant des entiers (avec un ordre d'itération déterminé par l'attribut order-by) :


<bag name="sizes"
        table="item_sizes" 
        order-by="size asc">
    <key column="item_id"/>
    <element column="size" type="integer"/>
</bag
>

Un tableau d'entités - dans ce cas, une association plusieurs-à-plusieurs :


<array name="addresses"
        table="PersonAddress" 
        cascade="persist">
    <key column="personId"/>
    <list-index column="sortOrder"/>
    <many-to-many column="addressId" class="Address"/>
</array
>

Une map de chaînes de caractères vers des dates :


<map name="holidays"
        table="holidays" 
        schema="dbo" 
        order-by="hol_name asc">
    <key column="id"/>
    <map-key column="hol_name" type="string"/>
    <element column="hol_date" type="date"/>
</map
>

Une liste de composants (traité dans le prochain chapitre) :


<list name="carComponents"
        table="CarComponents">
    <key column="carId"/>
    <list-index column="sortOrder"/>
    <composite-element class="CarComponent">
        <property name="price"/>
        <property name="type"/>
        <property name="serialNumber" column="serialNum"/>
    </composite-element>
</list
>

Une association un-à-plusieurs lie les tables de deux classes par une clé étrangère, sans l'intervention d'une table de collection. Ce mappage perd certaines sémantiques des collections Java normales :

Une association de Product vers Part requiert l'existence d'une clé étrangère et éventuellement une colonne d'index pour la table Part. Une balise <one-to-many> indique que c'est une association un-à-plusieurs.

<one-to-many
        class=(1)"ClassName"
        not-fo(2)und="ignore|exception"
        entity(3)-name="EntityName"
        node="element-name"
        embed-xml="true|false"
    />

1

class (requis) : le nom de la classe associée.

2

not-found (optionnel - par défaut exception) : spécifie comment les identifiants cachés qui référencent des lignes manquantes seront gérés : ignore traitera une ligne manquante comme une association nulle.

3

entity-name (optionnel) : le nom de l'entité de la classe associée, comme une alternative à class.

Notez que l'élément <one-to-many> n'a pas besoin de déclarer de colonnes. Il n'est pas non plus nécessaire de spécifier le nom de la table à aucun endroit.

Cet exemple montre une map d'entités Part par nom (où partName est une propriété persistante de Part). Notez l'utilisation d'un index basé sur une formule :


<map name="parts"
        cascade="all">
    <key column="productId" not-null="true"/>
    <map-key formula="partName"/>
    <one-to-many class="Part"/>
</map
>

Hibernate supporte des collections implémentant java.util.SortedMap et java.util.SortedSet. Vous devez spécifier un comparateur dans le fichier de mappage :


<set name="aliases"
            table="person_aliases" 
            sort="natural">
    <key column="person"/>
    <element column="name" type="string"/>
</set>

<map name="holidays" sort="my.custom.HolidayComparator">
    <key column="year_id"/>
    <map-key column="hol_name" type="string"/>
    <element column="hol_date" type="date"/>
</map
>

Les valeurs permises pour l'attribut sort sont unsorted, natural et le nom d'une classe implémentant java.util.Comparator.

Les collections triées se comportent réellement comme java.util.TreeSet ou java.util.TreeMap.

Si vous voulez que la base de données elle-même ordonne les éléments de la collection, utilisez l'attribut order-by des mappages set, bag ou map. Cette solution est seulement disponible à partir du JDK 1.4 (c'est implémenté en utilisant LinkedHashSet ou LinkedHashMap). Ceci exécute le tri dans la requête SQL, pas en mémoire.


<set name="aliases" table="person_aliases" order-by="lower(name) asc">
    <key column="person"/>
    <element column="name" type="string"/>
</set>

<map name="holidays" order-by="hol_date, hol_name">
    <key column="year_id"/>
    <map-key column="hol_name" type="string"/>
    <element column="hol_date type="date"/>
</map
>

Les associations peuvent même être triées sur des critères arbitraires à l'exécution en utilisant un filter() de collection :

sortedUsers = s.createFilter( group.getUsers(), "order by this.name" ).list();

Une association bidirectionnelle permet la navigation à partir des deux extrémités de l'association. Deux types d'associations bidirectionnelles sont supportées :

Vous pouvez spécifier une association bidirectionnelle plusieurs-à-plusieurs simplement en mappant deux associations plusieurs-à-plusieurs vers la même table de base de données et en déclarant une extrémité comme inverse (celle de votre choix, mais pas une collection indexée).

Voici un exemple d'association bidirectionnelle plusieurs-à-plusieurs ; chaque catégorie peut avoir plusieurs objets et chaque objet peut être dans plusieurs catégories :


<class name="Category">
    <id name="id" column="CATEGORY_ID"/>
    ...
    <bag name="items" table="CATEGORY_ITEM">
        <key column="CATEGORY_ID"/>
        <many-to-many class="Item" column="ITEM_ID"/>
    </bag>
</class>

<class name="Item">
    <id name="id" column="ITEM_ID"/>
    ...

    <!-- inverse end -->
    <bag name="categories" table="CATEGORY_ITEM" inverse="true">
        <key column="ITEM_ID"/>
        <many-to-many class="Category" column="CATEGORY_ID"/>
    </bag>
</class
>

Les changements faits uniquement sur l'extrémité inverse de l'association ne sont pas persistés. Ceci signifie qu'Hibernate a deux représentations en mémoire pour chaque association bidirectionnelle, un lien de A vers B et un autre de B vers A. Ceci est plus facile à comprendre si vous pensez au modèle objet de Java et à la façon dont nous créons une relation plusieurs-à-plusieurs dans Java :



category.getItems().add(item);          // The category now "knows" about the relationship
item.getCategories().add(category);     // The item now "knows" about the relationship
session.persist(item);                   // The relationship won't be saved!
session.persist(category);               // The relationship will be saved

La partie non-inverse est utilisée pour sauvegarder la représentation en mémoire dans la base de données.

Vous pouvez définir une association bidirectionnelle un-à-plusieurs en mappant une association un-à-plusieurs vers la(es) même(s) colonne(s) de table qu'une association plusieurs-à-un et en déclarant l'extrémité pluri-valuée inverse="true".


<class name="Parent">
    <id name="id" column="parent_id"/>
    ....
    <set name="children" inverse="true">
        <key column="parent_id"/>
        <one-to-many class="Child"/>
    </set>
</class>

<class name="Child">
    <id name="id" column="child_id"/>
    ....
    <many-to-one name="parent" 
        class="Parent" 
        column="parent_id"
        not-null="true"/>
</class
>

Mapper une extrémité d'une association avec inverse="true" n'affecte pas l'opération de cascades, ce sont des concepts orthogonaux.

Une association bidirectionnelle où une extrémité est représentée comme une <list> ou une <map> requiert une considération spéciale. S'il y a une propriété de la classe enfant qui mappe la colonne de l'index, pas de problème, nous pouvons continuer à utiliser inverse="true" sur le mappage de la collection :


<class name="Parent">
    <id name="id" column="parent_id"/>
    ....
    <map name="children" inverse="true">
        <key column="parent_id"/>
        <map-key column="name" 
            type="string"/>
        <one-to-many class="Child"/>
    </map>
</class>

<class name="Child">
    <id name="id" column="child_id"/>
    ....
    <property name="name" 
        not-null="true"/>
    <many-to-one name="parent" 
        class="Parent" 
        column="parent_id"
        not-null="true"/>
</class
>

Mais, si il n'y a pas de telle propriété sur la classe enfant, nous ne pouvons pas considérer l'association comme vraiment bidirectionnelle (il y a des informations disponibles à une extrémité de l'association qui ne sont pas disponibles à l'autre extrémité). Dans ce cas, nous ne pouvons pas mapper la collection inverse="true". Par contre, nous utiliserons le mappage suivant :


<class name="Parent">
    <id name="id" column="parent_id"/>
    ....
    <map name="children">
        <key column="parent_id"
            not-null="true"/>
        <map-key column="name" 
            type="string"/>
        <one-to-many class="Child"/>
    </map>
</class>

<class name="Child">
    <id name="id" column="child_id"/>
    ....
    <many-to-one name="parent" 
        class="Parent" 
        column="parent_id"
        insert="false"
        update="false"
        not-null="true"/>
</class
>

Note that in this mapping, the collection-valued end of the association is responsible for updates to the foreign key.

Si vous êtes bien d'accord avec nous sur le fait que les clés composées sont une mauvaise chose et que les entités devraient avoir des identifiants artificiels (des clés subrogées), vous pourrez trouver un peu curieux que les associations plusieurs-à-plusieurs et les collections de valeurs que nous avons montrées jusqu'ici, mappent toutes des tables avec des clés composées ! Il est vrai que ce point est ambigu ; une table d'association pure ne semble pas tirer avantage d'une clé subrogée (bien qu'une collection de valeur composées le pourrait). Néanmoins, Hibernate fournit une fonctionnalité qui vous permet de mapper des associations plusieurs-à-plusieurs et des collections de valeurs vers une table avec une clé subrogée.

L'élément <idbag> vous laisse mapper une List (ou une Collection) avec une sémantique de sac. Par exemple :


<idbag name="lovers" table="LOVERS">
    <collection-id column="ID" type="long">
        <generator class="sequence"/>
    </collection-id>
    <key column="PERSON1"/>
    <many-to-many column="PERSON2" class="Person" fetch="join"/>
</idbag
>

Comme vous pouvez le constater, un <idbag> a un générateur d'id artificiel, exactement comme une classe d'entité ! Une clé subrogée différente est assignée à chaque ligne de la collection. Cependant, Hibernate ne fournit pas de mécanisme pour découvrir la valeur d'une clé subrogée d'une ligne particulière.

Notez que les performances de la mise à jour d'un <idbag> sont bien meilleures qu'un <bag> ordinaire ! Hibernate peut localiser des lignes individuelles efficacement et les mettre à jour ou les effacer individuellement, comme une liste, une map ou un ensemble.

Dans l'implémentation actuelle, la stratégie de la génération de l'identifiant native n'est pas supportée pour les identifiants de collection <idbag>.

Exemples de collections

La classe suivante possède une collection d'instances Child(filles) :

package eg;

import java.util.Set;
public class Parent {
    private long id;
    private Set children;
    public long getId() { return id; }
    private void setId(long id) { this.id=id; }
    private Set getChildren() { return children; }
    private void setChildren(Set children) { this.children=children; }
    ....
    ....
}

Si chaque instance fille a au plus un parent, le mappage le plus naturel est une association un-à-plusieurs :


<hibernate-mapping>

    <class name="Parent">
        <id name="id">
            <generator class="sequence"/>
        </id>
        <set name="children">
            <key column="parent_id"/>
            <one-to-many class="Child"/>
        </set>
    </class>

    <class name="Child">
        <id name="id">
            <generator class="sequence"/>
        </id>
        <property name="name"/>
    </class>

</hibernate-mapping
>

Ceci mappe les définitions de tables suivantes :


create table parent ( id bigint not null primary key )
create table child ( id bigint not null primary key, name varchar(255), parent_id bigint )
alter table child add constraint childfk0 (parent_id) references parent

Si le parent est requis, utilisez une association bidirectionnelle un-à-plusieurs :


<hibernate-mapping>

    <class name="Parent">
        <id name="id">
            <generator class="sequence"/>
        </id>
        <set name="children" inverse="true">
            <key column="parent_id"/>
            <one-to-many class="Child"/>
        </set>
    </class>

    <class name="Child">
        <id name="id">
            <generator class="sequence"/>
        </id>
        <property name="name"/>
        <many-to-one name="parent" class="Parent" column="parent_id" not-null="true"/>
    </class>

</hibernate-mapping
>

Notez la contrainte NOT NULL :


create table parent ( id bigint not null primary key )
create table child ( id bigint not null
                     primary key,
                     name varchar(255),
                     parent_id bigint not null )
alter table child add constraint childfk0 (parent_id) references parent

Alternativement, si vous insistez absolument pour que cette association soit unidirectionnelle, vous pouvez déclarer la contrainte NOT NULL sur le mappage <key> :


<hibernate-mapping>

    <class name="Parent">
        <id name="id">
            <generator class="sequence"/>
        </id>
        <set name="children">
            <key column="parent_id" not-null="true"/>
            <one-to-many class="Child"/>
        </set>
    </class>

    <class name="Child">
        <id name="id">
            <generator class="sequence"/>
        </id>
        <property name="name"/>
    </class>

</hibernate-mapping
>

D'autre part, si un enfant peut avoir plusieurs parents, une association plusieurs-à-plusieurs est plus appropriée :


<hibernate-mapping>

    <class name="Parent">
        <id name="id">
            <generator class="sequence"/>
        </id>
        <set name="children" table="childset">
            <key column="parent_id"/>
            <many-to-many class="Child" column="child_id"/>
        </set>
    </class>

    <class name="Child">
        <id name="id">
            <generator class="sequence"/>
        </id>
        <property name="name"/>
    </class>

</hibernate-mapping
>

Définitions des tables :

create table parent ( id bigint not null primary key )
create table child ( id bigint not null primary key, name varchar(255) )
create table childset ( parent_id bigint not null,
                        child_id bigint not null,
                        primary key ( parent_id, child_id ) )
alter table childset add constraint childsetfk0 (parent_id) references parent
alter table childset add constraint childsetfk1 (child_id) references child

For more examples and a complete explanation of a parent/child relationship mapping, see Chapitre 22, Exemple : père/fils for more information.

Des mappages d'association plus exotiques sont possibles, nous cataloguerons toutes les possibilités dans le prochain chapitre.

Une association bidirectionnelle plusieurs-à-un est le type d'association que l'on rencontre le plus fréquemment. L'exemple suivant illustre la façon standard de créer des relations parents/enfants.


<class name="Person">
    <id name="id" column="personId">
        <generator class="native"/>
    </id>
    <many-to-one name="address" 
        column="addressId"
        not-null="true"/>
</class>

<class name="Address">
    <id name="id" column="addressId">
        <generator class="native"/>
    </id>
    <set name="people" inverse="true">
        <key column="addressId"/>
        <one-to-many class="Person"/>
    </set>
</class
>
create table Person ( personId bigint not null primary key, addressId bigint not null )
create table Address ( addressId bigint not null primary key )
        

Si vous utilisez une List, ou toute autre collection indexée, vous devez paramétrer la colonne key de la clé étrangère à not null, et laisser Hibernate gérer l'association depuis l'extrémité collection pour maintenir l'index de chaque élément (rendant l'autre extrémité virtuellement inverse en paramétrant update="false" et insert="false") :


<class name="Person">
   <id name="id"/>
   ...
   <many-to-one name="address"
      column="addressId"
      not-null="true"
      insert="false"
      update="false"/>
</class>

<class name="Address">
   <id name="id"/>
   ...
   <list name="people">
      <key column="addressId" not-null="true"/>
      <list-index column="peopleIdx"/>
      <one-to-many class="Person"/>
   </list>
</class
>

Il est important de définir not-null="true sur l'élément <key> du mapping de la collection si la colonne de clé étrangère sous-jacente est NOT NULL. Ne déclarez pas seulement not-null="true" sur un élément imbriqué possible<column>, mais sur l'élément <key>.

Des associations encore plus complexes sont extrêmement rares. Hibernate permet de gérer des situations plus complexes en utilisant des extraits SQL embarqués dans le fichier de mapping. Par exemple, si une table avec des informations historiques sur un compte définit les colonnes accountNumber, effectiveEndDate et effectiveStartDate, elle sera mappée de la façon suivante :


<properties name="currentAccountKey">
    <property name="accountNumber" type="string" not-null="true"/>
    <property name="currentAccount" type="boolean">
        <formula
>case when effectiveEndDate is null then 1 else 0 end</formula>
    </property>
</properties>
<property name="effectiveEndDate" type="date"/>
<property name="effectiveStateDate" type="date" not-null="true"/>

Nous pouvons mapper une association à l'instance courante, celle avec une effectiveEndDate nulle, en utilisant :


<many-to-one name="currentAccountInfo"
        property-ref="currentAccountKey"
        class="AccountInfo">
    <column name="accountNumber"/>
    <formula
>'1'</formula>
</many-to-one
>

Dans un exemple plus complexe, imaginez qu'une association entre Employee et Organization soit gérée dans une table Employment pleine de données historiques. Dans ce cas, une association vers l'employeur le plus récent (celui avec la startDate (date de commencement de travail la plus récente) pourrait être mappée comme suit :


<join>
    <key column="employeeId"/>
    <subselect>
        select employeeId, orgId 
        from Employments 
        group by orgId 
        having startDate = max(startDate)
    </subselect>
    <many-to-one name="mostRecentEmployer" 
            class="Organization" 
            column="orgId"/>
</join
>

Vous pouvez être créatif grâce à ces possibilités, mais il est généralement plus pratique de gérer ce genre de cas en utilisant des requêtes HQL ou par critère.