Téléchargez et installez la distribution Hibernate Annotations à partir du site web d'Hibernate.
Cette version requiert Hibernate 3.2.0.GA ou supérieur. N'utilisez pas cette version d'Hibernate Annotations avec une version plus ancienne d'Hibernate 3.x !
Cette version est connue pour fonctionner avec le noyau 3.2.0.CR5 et 3.2.0.GA d'Hibernate.
Assurez-vous que vous avez le JDK 5.0 d'installé. Vous pouvez bien sûr continuer à utiliser XDoclet et avoir certains des avantages des méta-données basées sur les annotations avec des versions plus anciennes du JDK. Notez que ce document décrit seulement les annotations du JDK 5.0 et que vous devez vous référer à la documentation de XDoclet pour plus d'informations.
Tout d'abord, paramétrez votre classpath (après avoir créer un nouveau projet dans votre IDE favori) :
Copiez toutes les bibliothèques du noyau Hibernate3 et toutes les bibliothèques tierces requises (voir lib/README.txt dans Hibernate).
Copiez aussi hibernate-annotations.jar et lib/ejb3-persistence.jar de la distribution Hibernate Annotations dans votre classpath.
Pour utiliser Chapitre 5, Intégration de Lucene avec Hibernate, ajouter le fichier jar de lucene.
Nous recommandons aussi un petit wrapper pour démarrer Hibernate dans un bloc statique d'initialisation, connu en tant que HibernateUtil. Vous pourriez avoir vu cette classe sous diverses formes dans d'autres parties de la documentation Hibernate. Pour prendre en charge Annotation vous devez modifier cette classe d'aide de la manière suivante :
package hello;
import org.hibernate.*;
import org.hibernate.cfg.*;
import test.*;
import test.animals.Dog;
public class HibernateUtil {
private static final SessionFactory sessionFactory;
static {
try {
sessionFactory = new AnnotationConfiguration().buildSessionFactory();
} catch (Throwable ex) {
// Log exception!
throw new ExceptionInInitializerError(ex);
}
}
public static Session getSession()
throws HibernateException {
return sessionFactory.openSession();
}
}
La partie intéressante ici est l'utilisation de AnnotationConfiguration. Les packages et les classes annotées sont déclarés dans votre fichier de configuration XML habituel (généralement hibernate.cfg.xml). Voici un équivalent de la déclaration ci-dessus :
<!DOCTYPE hibernate-configuration PUBLIC
"-//Hibernate/Hibernate Configuration DTD 3.0//EN"
"http://hibernate.sourceforge.net/hibernate-configuration-3.0.dtd">
<hibernate-configuration>
<session-factory>
<mapping package="test.animals"/>
<mapping class="test.Flight"/>
<mapping class="test.Sky"/>
<mapping class="test.Person"/>
<mapping class="test.animals.Dog"/>
<mapping resource="test/animals/orm.xml"/>
</session-factory>
</hibernate-configuration>
Notez que vous pouvez mélanger l'utilisation du fichier hbm.xml et celle des annotations. L'élément de ressource peut être un fichier hbm ou un descripteur de déploiement XML EJB3. Cette distinction est transparente pour votre procédure de configuration.
Alternativement, vous pouvez définir les classes annotées et des packages en utilisant l'API :
sessionFactory = new AnnotationConfiguration() .addPackage("test.animals") // le nom complet du package .addAnnotatedClass(Flight.class) .addAnnotatedClass(Sky.class) .addAnnotatedClass(Person.class) .addAnnotatedClass(Dog.class) .addResource("test/animals/orm.xml") .buildSessionFactory();
Vous pouvez aussi utiliser Hibernate EntityManager qui a son propre mécanisme de configuration. Veullez vous référer à la documentation de ce projet pour plus de détails.
Il n'y a pas d'autres différences dans la façon d'utiliser les APIs d'Hibernate, excepté ce changement de routine de démarrage ou le fichier de configuration. Vous pouvez utiliser votre méthode de configuration favorite pour d'autres propriétés (hibernate.properties, hibernate.cfg.xml, utilisation des APIs, etc). Vous pouvez même mélanger les classes persistantes annotées et des déclarations hbm.cfg.xml classiques avec la même SessionFactory. Vous ne pouvez cependant pas déclarer une classe plusieurs fois (soit avec les annotations, soit avec un fichier hbm.xml). Vous ne pouvez pas non plus mélanger des stratégies de configuration (hbm vs annotations) dans une hiérarchie d'entités mappées.
Pour faciliter la procédure de migration de fichiers hbm vers les annotations, le mécanisme de configuration détecte la duplication de mappings entre les annotations et les fichiers hbm. Les classes décrites dans les fichiers hbm se voient alors affecter une priorité plus grande que les classes annotées. Vous pouvez changer cette priorité avec la propriété hibernate.mapping.precedence. La valeur par défaut est : hbm, class ; la changer en : class, hbm donne alors la priorité aux classes annotées lorsqu'un conflit survient.