Généralité et pré-requis
L'annotation dans le monde Java est une technique qui permet de "marquer" certains éléments au sein d'un programme afin de leur ajouter une propriété particulière. Ces annotations peuvent ensuite être utilisées à la compilation ou à l'exécution pour automatiser certaines tâches.
Les annotations peuvent être divisées en deux catégories, les annotations de mapping logique (vous permettant de décrire le modèle objet, les associations de classe, etc....) et les annotations de mapping physique (décrivant le schéma physique, les tables, les colonnes, les index, etc...)
Pour utiliser les annotations avec Hibernate il faut un certain nombre de pré-requis :

Une version de Hibernate supérieure ou égale à Hibernate 3.2.0.GA
une version de JDK supérieure ou égale JDK 5.0
D'abord, on commence par paramètrer le classpath; on copie toutes les bibliothéques du noyau Hibernate3, toutes les bibliothéques requises pour les annotations comme, "hibernate-annotations.jar" et "lib/ejb3-persistence.jar" de la distribution Hibernate Annotations dans le classpath.
On crée un repertoire lib dans le repertoire de développement et on y copie les fichiers.jar suivants:

//Hibernate 3
          commons-logging.jar
          dom4j.jar
          javassist.jar
          antlr.jar
          commons-collections.jar
          cglib.jar
          hibernate3.jar
          asm-attrs.jar
          asm.jar
          c3p0-0.9.1.jar
          hibernate-entitymanager.jar
          iijdbc.jar
          j2ee.jar
          concurrent-1.3.2.jar
          javassist.jar
          jboss-archive-browsing.jar
          ehcache-1.2.3.jar
          log4j-1.2.11.jar                    
  //Hibernate Annotations
          hibernate-annotations.jar
          ejb3-persistence.jar
   

Il faut que dans le classpath on ait tous les pré-requis pour la compilation et l'exécution de l'application.
L'annotation avec Hibernate a pour but de se passer des fichiers "hbm.xml" qui permettent de configurer chaque classe que l'on veut rendre persistente. Les différents éléments qu'on peut annotés seront ilustrés dan différents exemples.Les annotations sont directement injectés dans les classes relatives aux classes persistentes.

Configuration

Si on utilise Hibernate en s'appuyant sur un fichier de configuration, Les packages, les classes annotées sont déclarés dans le fichier de configuration XML (généralement hibernate.cfg.xml) comme le montre l'exemple de fichier de configuration hibernat.cfg.xml suivant :

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

On voit bien que l'on indique le package (test.animals) concerné par les annotions ainsi les différentes classes(test.Flight, test.Person, test.animals.Dog ) et ressources.

Programmation

Si on n'utilise pas un fichier de configuration pour se servir de Hibernate mais de la programmation, on rend visible les packages et les classes concernés par les annotions en procédant comme suit:

  sessionFactory = new AnnotationConfiguration()
                    .addPackage("test.animals") //the fully qualified package name
                    .addAnnotatedClass(Flight.class)
                    .addAnnotatedClass(Sky.class)
                    .addAnnotatedClass(Person.class)
                    .addAnnotatedClass(Dog.class)
                    .addResource("test/animals/orm.xml")
                    .configure().buildSessionFactory();

EntityManager

On peut aussi utiliser Hibernate EntityManager qui a son propre mécanisme de configuration. 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 d'extension ".hbm.xml" vers les annotations, le mécanisme de configuration détecte la duplication de mappings entre les annotations et les fichiers d'extension ".hbm.xml" . 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