Le code source suivant présente l'entité simple Photo.

entité.Photo.java

package entité;

import java.awt.image.BufferedImage;
import java.util.Date;
import javax.persistence.*;

@Entity
@NamedQuery(name="toutes", query="SELECT photo FROM Photo AS photo")
public class Photo { //  implements java.io.Serializable {
    @Id
    private String id;
    @Temporal(TemporalType.TIMESTAMP)
    private Date instant;
    private int largeur;
    private int hauteur;
    private long poids;

    public String getId()            { return id; }
    public int      getHauteur()   { return hauteur;  }
    public Date   getInstant()     { return instant;  }
    public int      getLargeur()   { return largeur;  }
    public long   getPoids()       { return poids;  }

    public Photo() { }

    public Photo(String nom, long poids) {
        id = nom;
        instant = new Date();
        this.poids = poids;
    }

    public void setDimensions(BufferedImage image) {
        largeur = image.getWidth();
        hauteur = image.getHeight();
    }

    @Override
    public String toString() {
        return id+" ("+largeur+", "+hauteur+")";
    }
}

Comme vous pouvez le constater, à part les annotations, cette entité ressemble exactement à n'importe quelle classe Java : elle possède plusieurs attributs (id, instant, largeur, hauteur et poids) de différents types (String, Date, int et long), plusieurs constructeurs dont celui par défaut, des getters pour chaque attribut avec un seul setter. Dans cette exemple là, l'état de l'objet est rapidement renseigné à l'aide du deuxième constructeur et de la méthode setDimensions().

Les annotations permettent d'associer très simplement cette entité à une table dans une base de données.

1. Tout d'abord, la classe est annotée @javax.persistence.Entity, ce qui permet au fournisseur de persistance de la reconnaître comme une classe persistante et non comme une simple classe POJO.
2. Puis l'annotation @javax.persistence.Id définit l'identifiant unique de l'objet. JPA étant destiné à associer des objets à des tables relationnelles, les objets doivent posséder un identifiant qui sera associé à une clé primaire.
3. La plupart des autres attributs (largeur, hauteur et poids) ne sont pas annotés et seront donc stockés dans la table en appliquant une association standard.

Notez que cette entité Photo est une classe qui actuellement n'implémente aucune interface et qui n'hérite d'aucune classe. En fait, pour être une entité, une classe doit impérativement respecter les règles suivantes :

1. La classe de l'entité doit être annotée par @javax.persistence.Entity.
2. L'annotation @javax.persistence.Id doit être utilisée pour désigner une clé primaire simple.
3. La classe de l'entité doit posséder au moins un constructeur par défaut, public ou protégé. Bien entendu, elle peut également avoir d'autres constructeurs.
4. La classe de l'entité doit être une classe de premier niveau. Une énumération ou une interface ne peut pas être considérée comme une entité.
5. La classe de l'entité ne peut pas être finale et aucune méthode ou variable d'instance persistante ne peut être finale non plus.
6. Si une instance d'entité doit être passée par valeur sous forme d'objet détaché (via une interface distante, par exemple), la classe de l'entité doit alors implémenter l'interface Serializable (c'est très souvent le cas).

L'entité Photo respectant ces règles simples, le fournisseur de persistance peut synchroniser les données entre les attributs de l'entité et les colonnes de la table PHOTO. Par conséquent, si l'attribut largeur est modifié par l'application, la colonne LARGEUR le sera également (si l'entité est gérée, si le contexte de transaction est actif, etc.).

L'entité Photo est stockée dans une table PHOTO dont chaque colonne porte le nom de l'attribut correspondant de la classe (l'attribut largeur de type int est associée à une colonne LARGEUR de type INTEGER). Ces règles d'associations par défaut sont un aspect important du principe appelé "convention plutôt que configuration" (ou "configuration par exception").

Revenons à l'exemple précédent. Sans annotation, l'entité Photo serait traitée comme n'importe quel POJO et ne serait pas persistante - c'est la règle : sans configuration spéciale, le comportement par défaut s'applique et il consiste évidemment à considérer que la classe Photo est une classe comme les autres.

1. Comme nous souhaitons modifier ce comportement, nous annotons la classe avec @Entity.
2. Il en va de même pour l'identifiant : nous avons absolument besoin d'indiquer au fournisseur de persistance que cet attribut doit être associé à une clé primaire, et c'est la raison pour laquelle nous l'annotons avec @Id.

Ce type de décision caractérise bien la politique de configuration par exception : les annotations ne sont pas nécessaires dans le cas général ; elles ne sont utilisées que pour outrepasser une convention. Ceci signifie donc que tous les autres attributs de notre classe (sauf instant) seront associés selon les règles par défaut :

1. Le nom de l'entité est associé à un nom de table relationnelle (l'entité Photo sera donc associée à une table PHOTO). Si vous désirez l'associer à une autre table, vous devrez utiliser l'annotation @Table, comme nous le découvrirons dans un des chapitres qui suit).
2. Le nom des attributs sont associés à des noms de colonnes (l'attribut id, ou la méthode getId(), est associé à une colonne ID). Si vous changez ce comportement, vous devrez utiliser l'annotation @Column.
3. Ce sont les règles JDBC qui s'appliquent pour associer les types primitifs de Java aux types de données de la base. Ainsi :
   • Un String sera associé à un VARCHAR,
   • Un Long à un BIGINT,
   • Un Boolean à un SMALLINT, etc.
   • La taille par défaut d'une colonne associée à un String est de 255 caractères - VARCHAR(255).

Ces règles par défaut peuvent éventuellement varier en fonction du SGBDR : un String est associé avec un VARCHAR avec Derby, mais à un VARCHAR2 avec Oracle ; de la même façon, un Integer est associé à un INTEGER avec Derby, mais à un NUMBER avec Oracle.

La plupart des fournisseurs de persistance, dont EclipseLink, permettent de produire automatiquement la base de données directement à partir des entités. Cette fonctionnalité est tout spécialement pratique lorsque nous sommes en phase de développement car, avec uniquement les règles par défaut, nous pouvons associer très simplement les données en se contentant des annotations @Entity et @Id.

Indépendamment de notre application d'entreprise, il peut arriver que nous souhaitions nous connecter au SGBDR de façon classique, à l'aide notamment de requête SQL. Dans ce cas de figure, pour que les développeurs de base de données classiques puissent s'y retrouver, JPA définit un nombre important d'annotations qui vont permettrent de personnaliser chaque partie de l'association (les noms des tables et des colonnes, les clés primaires, la taille des colonnes, les colonnes NULL ou NOT NULL, etc. ).

Le code source suivant montre comment associer la table T_PHOTO à l'entité Photo.

entité.Photo.java

@Entity
@Table(name="t_photo")
public class Photo implements java.io.Serializable {
    @Id
    private String id;
    @Temporal(TemporalType.TIMESTAMP)
    private Date instant;
    private int largeur;
    private int hauteur;
    private long poids;
...
}

Dans l'annotation @Table, le nom de la table est en minuscule (t_photo). Par défaut, la plupart des SGBDR lui feront correspondre un nom en majuscules (c'est notamment le cas de Derby), sauf si vous les configurez pour qu'ils respectent la casse.

Le code source suivant montre comment répartir les attributs d'une entité Adresse entre une table primaire et deux tables secondaires :

Adresse.java

@Entity
@SecondaryTables({
    @SecondaryTable(name="ville"),
    @SecondaryTable(name="pays")
})
public class Adresse implements java.io.Serializable {

    @Id   @GeneratedValue
    private long id;
    private String rue1;
    private String rue2;
    @Column(table="ville")
    private String ville;
    @Column(table="ville")
    private String département;
    @Column(table="ville")
    private int codepostal;
    @Column(table="pays")
    private String pays;
...
}

Par défaut, les attributs de l'entité Adresse seraient associés à la table primaire ADRESSE. L'annotation @SecondaryTables précise qu'il existe deux tables secondaires supplémentaires : VILLE et PAYS. Vous devez ensuite respectivement indiquer dans quelle table secondaire stocker chaque attribut - à l'aide de l'annotation @Column(table="ville") ou @Column(table="pays").

Le résultat d'une telle écriture est ainsi la création de trois tables distinctes se partageant les différents attributs d'une même entité, en ayant toutefois la même clé primaire (afin, bien entendu, de pouvoir les joindre).

Comme vous l'avez sûrement compris, la même entité peut contenir plusieurs annotations. Ainsi, si vous désirez renommer la table primaire, vous pouvez donc ajouter une annotation @Table à celles déjà existantes :

Adresse.java

@Entity
@Table(name="t_adresse")
@SecondaryTables({
    @SecondaryTable(name="ville"),
    @SecondaryTable(name="pays")
})
public class Adresse implements java.io.Serializable {

    @Id   @GeneratedValue
    private long id;
    private String rue1;
    private String rue2;
    @Column(table="ville")
    private String ville;
    @Column(table="ville")
    private String département;
    @Column(table="ville")
    private int codepostal;
    @Column(table="pays")
    private String pays;
...
}

Vous devez être concient de l'impact des tables secondaires sur les performances car, à chaque fois que vous accéder à une entité, le fournisseur de persistance devra accéder à plusieurs tables et les joindre. En revanche, les tables secondaires peuvent être intéressantes si vous avez des attributs de grande taille, comme les BLOB (Binary Large Objects), car vous pourrez les isoler dans une table à part.

Lorsque nous créons une entité, la valeur de cet identifiant peut être produite manuellement par l'application, ou automatiquement par le fournisseur de persistance si nous précisons l'annotation @GeneratedValue. Celle-ci peut accepter l'une des quatre valeurs suivantes :

1. IDENTITY : Ce type indique au fournisseur de persistance d'assigner la valeur de la clé primaire en utilisant la colonne identité de la base de données. Sous MySQL, par exemple, la clé primaire auto-générée est marquée avec AUTO_INCREMENT.

   @Id
   @GeneratedValue(strategy = GenerationType.IDENTITY)
   private int id;

2. SEQUENCE : Ce type, comme son nom l'indique, oblige le fournisseur de persistance à utiliser une séquence de la base de données. Celle-ci peut être déclarée au niveau de la classe ou au niveau du package grâce à l'annotation @SequenceGenerator et ses attributs :
   • name (requis) : définit un nom unique pour la séquence qui peut être référencée par une ou plusieurs classes (suivant le niveau utilisé pour la déclaration de l'annotation).
   • sequenceName (optionnel) : définit le nom de l'objet séquence de la base de données qui sera utilisé pour récupérer les valeurs des clés primaires liées.
   • initialValue (optionnel) : définit la valeur à laquelle doit démarrer la séquence.
   • allocationSize (optionnel) : définit le nombre utilisé pour l'incrémentation de la séquence lorsque le fournisseur de persistance y accède. Attention, la valeur par défaut est 50.

   @Entity
   @SequenceGenerator(name = "SEQ_USER", sequenceName = "SEQ_USER")
   public class Utilisateur implements Serializable {
      @Id
      @GeneratedValue(strategy = GenerationType.SEQUENCE, generator = "SEQ_USER")
      public int id;

   Ce type de génération est utile lorsque la base de données offre un système natif de séquence et qu'il est conseillé de l'utiliser par le fournisseur de celle-ci.

3. TABLE : Ce type demande au fournisseur de persistance de stocker le nom de la séquence et sa valeur courante dans une table et d'incrémenter cette valeur à chaque fois qu'une nouvelle instance de l'entité est stockée dans la base.

   Derby, par exemple, crée une table SEQUENCE de deux colonnes : une pour le nom de la séquence (qui est arbitraire) et l'autre pour la valeur (un entier incrémenté automatiquement par Derby).

   De façon annecdotique, nous pouvons pousser plus loin notre investigation en proposant l'annotation @TableGenerator qui permet de préciser les paramètres de création de la table annexe de génération dont les attributs sont les suivants :
   • name : définit un nom pour cette définition de table annexe.
   • table : définit le nom de la table dans la base de données.
   • pkColumnName : spécifie le nom de la colonne qui contient le compteur de clé primaire.
   • pkColumnValue : spécifie la colonne de la clé primaire liée.
   • allocationSize : définit le nombre d'incrémentations effectuées lorsque le fournisseur demande à la table une nouvelle valeur. Cela permet au fournisseur d'utiliser un système de cache afin de ne pas demander une nouvelle valeur à chaque demande d'un nouvel id.

   @Entity
   @TableGenerator(
   	name="C0NTACT_GEN", 
   	table="GENERATEUR_TABLE", 
   	pkColumnName="clé",
   	valueColumnName="haut",
   	pkColumnValue="id",
   	allocationSize=25
   )
   public class Utilisateur implements Serializable {
      @Id
      @GeneratedValue(strategy = GenerationType.TABLE, generator = "CONTACT_GEN")
      public int id;

4. AUTO : Ce type demande que la génération d'une clé s'effectue automatiquement par la base de données sous-jacente, qui est libre de choisir la technique la plus appropriée. C'est la valeur par défaut de l'annotation @GeneratedValue.

   Ainsi, ce type indique au fournisseur de persistance d'utiliser la meilleure stratégie (entre ENTITY, TABLE, SEQUENCE) suivant la base de données utilisée. Le générateur AUTO est le type préféré pour avoir une application portable.

   Même si l'incrémentation automatique de la clé primaire soulage le développeur, elle doit être utilisée avec parcimonie. En effet, il est préférable d'utiliser un attribut de l'entité plutôt que d'en rajouter un, spécialement pour la clé primaire. Par exemple, l'entité Compte peut contenir une propriété numéroCompte qui se veut unique par la logique bancaire. Cette propriété est alors la meilleure candidate pour la clé primaire.

En l'absence de @GeneratedValue, l'application est responsable de la production des identifiants à l'aide d'un algorithme qui devra renvoyer une valeur unique.

Le code source suivant montre comment obtenir automatiquement un identifiant :

Livre.java

@Entity
public class Livre implements java.io.Serializable {
    @Id   @GeneratedValue(strategy = GenerationType.AUTO)
    private long id;
    private String titre;
    private double prix;
    private String description;
    private String isbn;
    private int nombreDePages;
    private boolean illustrations;
...
}

GenerationType.AUTO étant la valeur par défaut de l'annotation, nous aurions pu omettre l'élément strategy. Notez également dans tous nos exemples que l'attribut id est annoté deux fois : avec @Id et avec @GeneratedValue.

CREATE TABLE emprunte 
( 
    nopers integer not null, 
    noliv    integer not null, 
    sortie   date default current_date, 
    retour  date, 
    primary key (noliv, nopers, sortie), 
    foreign key (noliv) references Livre(noliv), 
    foreign key (nopers) references Personne(nopers) 
); 

Le code source suivant présente la classe NewsId comme une classe intégrable (embeddable). Il s'agit simplement d'un objet intégré (annoté @Embeddable) composé de deux attributs (titre et langue). Cette classe doit :

1. Redéfinir les méthodes equals() et hashCode() ;
2. En outre, leurs attributs doivent être de l'un des types déjà mentionnés.
3. Elles doivent également être publiques et implémenter l'interface Serializable si elles doivent traverser les couches de l'architecture (elles peuvent être gérées dans la couche de peristance et être utilisées dans la couche de présentation, par exemple).
4. Enfin, comme d'habitude, elles doivent posséder un constructeur par défaut.

Le code source suivant présente la classe NewsId comme une classe intégrable (embeddable). Il s'agit simplement d'un objet intégré (annoté @Embeddable) composé de deux attributs (titre et langue). Cette classe doit avoir un constructeur par défaut, des getters() et redéfinir la méthode equals() et hashCode(). Vous remarquez que la classe n'a pas d'identité par elle-même (aucune annotation @Id : c'est ce qui caractérise un objet intégrable.

entité.NewsId.java

package entité;

import java.io.Serializable;
import javax.persistence.Embeddable;

@Embeddable
public class NewsId implements Serializable {
    private String titre;
    private String langue;

    public NewsId() { }

    public NewsId(String titre, String langue) {
        this.titre = titre;
        this.langue = langue;
    }

    public String getLangue() { return langue; }
    public String getTitre()     { return titre; }

    @Override
    public boolean equals(Object obj) { // généré automatiquement par NetBeans
        if (obj == null) {
            return false;
        }
        if (getClass() != obj.getClass()) {
            return false;
        }
        final NewsId other = (NewsId) obj;
        if ((this.titre == null) ? (other.titre != null) : !this.titre.equals(other.titre)) {
            return false;
        }
        if ((this.langue == null) ? (other.langue != null) : !this.langue.equals(other.langue)) {
            return false;
        }
        return true;
    }

    @Override
    public int hashCode() { // généré automatiquement par NetBeans
        int hash = 7;
        hash = 89 * hash + (this.titre != null ? this.titre.hashCode() : 0);
        hash = 89 * hash + (this.langue != null ? this.langue.hashCode() : 0);
        return hash;
    }
} 

L'entité News, présentée dans le code source qui suit, doit maintenant intégrer la classe de clé primaire NewsId à l'aide de l'annotation @EmbeddedId. Toutes les annotations @EmbeddedId doivent désigner une classe intégrable annotée par @Embeddable.

entité.News.java

package entité;

import java.io.Serializable;
import javax.persistence.*;

@Entity
public class News implements Serializable {
    @EmbeddedId
    private NewsId id;
    private String contenu;

    public News() { }
    
    public News(String titre, String langue, String contenu) {
        id = new NewsId(titre, langue);
        this.contenu = contenu;
    }
    
    public NewsId getId()        { return id;  }
    public String getContenu() { return contenu;  }
} 

Lors d'une prochaine étude, nous verrons plus précisément comment retrouver les entités à l'aide de leur clé primaire, mais l'exemple ci-dessous présente le principe général : La clé primaire étant une classe avec un constructeur, vous devez d'abord l'instancier avec les valeurs qui forment la clé, puis passer cet objet au gestionnaire d'entités :

session.Gestion.java

package session;

import entité.*;
import javax.ejb.*;
import javax.persistence.*;

@Stateless
@LocalBean
public class Gestion {
    @PersistenceContext
    private EntityManager persistance;
    
    public News recherche(String titre, String langue) {
        return persistance.find(News.class, new NewsId(titre, langue));
    }
...
}

La clé primaire NewsId du code source suivant est maintenant un objet classique qui ne nécessite aucune annotation particulière :

entité.NewsId.java

package entité;

import java.io.Serializable;
import javax.persistence.Embeddable;

public class NewsId implements Serializable {  // la classe de la clé primaire n'est pas annotée
    private String titre;
    private String langue;

    public NewsId() { }

    public NewsId(String titre, String langue) {
        this.titre = titre;
        this.langue = langue;
    }

    public String getLangue() { return langue; }
    public String getTitre()     { return titre; }

    @Override
    public boolean equals(Object obj) { // généré automatiquement par NetBeans
        if (obj == null) {
            return false;
        }
        if (getClass() != obj.getClass()) {
            return false;
        }
        final NewsId other = (NewsId) obj;
        if ((this.titre == null) ? (other.titre != null) : !this.titre.equals(other.titre)) {
            return false;
        }
        if ((this.langue == null) ? (other.langue != null) : !this.langue.equals(other.langue)) {
            return false;
        }
        return true;
    }

    @Override
    public int hashCode() { // généré automatiquement par NetBeans
        int hash = 7;
        hash = 89 * hash + (this.titre != null ? this.titre.hashCode() : 0);
        hash = 89 * hash + (this.langue != null ? this.langue.hashCode() : 0);
        return hash;
    }
} 

L'entité News doit simplement définir la classe de la clé primaire à l'aide de l'annotation @IdClass et annoter chaque attribut de la clé avec @Id. Pour stocker l'entité News, vous devrez maintenant donner une valeur aux attributs titre et langue.

entité.News.java

package entité;

import java.io.Serializable;
import javax.persistence.*;

@Entity
@IdClass(NewsId.class)
public class News implements Serializable {
    @Id    
    private String titre;
    @Id  
    private String langue;
    private String contenu;

    public News() { }
    
    public News(String titre, String langue, String contenu) {
		   this.titre = titre;
        this.langue = langue;
        this.contenu = contenu;
    }
    
    public NewsId getId()        { return id;  }
    public String getContenu() { return contenu;  }
} 

Les deux approches, @EmbeddedId et @IdClass, donneront la même structure de table. Les attributs de l'entité et de la clé primaire se retrouveront bien dans la même table et la clé primaire sera formée des attributs de la classe clé primaire (titre et langue).

CREATE TABLE emprunte 
( 
    CONTENU varchar(255), 
    TITRE       varchar(255) not null, 
    LANGUE  varchar(255) not null, 
    primary key (TITRE, LANGUE) 
); 

L'approche par @IdClass est plus sujette aux erreurs car vous devez définir chaque attribut de la clé primaire à la fois dans la classe de clé primaire et dans l'entité, en vous assurant d'utiliser les mêmes noms et les mêmes types.

La seule différence visible est la façon dont vous ferez référence à l'entité dans JQPL.

@IdClass : SELECT n.titre FROM News n
@EmbeddedId : SELECT n.newsId.titre FROM News n

Considérons, par exemple, l'entité Piste du code source suivant. Un CD est en effet constitué de plusieurs pistes ayant chacune un titre, une description et un fichier .wav d'une certaine durée. Ce dernier est un BLOB qui peut occuper plusieurs mégaoctets. Lorsque nous accédons à l'entité Piste, nous ne voulons pas charger immédiatement le fichier WAV : nous annotons donc l'attribut avec @Basic(fetch = FetchType.LAZY) pour que ces données ne soient lues dans la base que lorsqu'elles seront vraiment nécessaires (lorsque nous accéderons, par exemple, à l'attribut wav via son getter)

Piste.java

public class Piste {
    @Id    
    private long id;
    private String titre;
    private double durée;
    @Lob  
    @Basic(fetch = FetchType.LAZY)
    private byte[] wav;
    @Basic(optional = true)
    private String description;
...
} 

Notez que l'attribut wav de type byte[] est également annoté @Lob afin que sa valeur soit stockée comme un LOB (Large Object) - les colonnes pouvant stocker ces types de gros objets nécessitent des appels JDBC spéciaux pour être accessibles à partir de Java. Pour en informer le fournisseur, il faut donc ajouter une annotation @Lob à l'association de base.

@Lob :

Ainsi, l'annotation @Lob s'avère utile lorsque vous souhaitez stocker des tableaux de bytes (byte[] ou Byte[]) pour représenter le contenu d'un fichier par exemple :

@Lob
@Basic(fetch=FetchType.LAZY)
public byte[] fichierImage;

L'annotation @Lob s'applique également sur des propriétés de type java.sql.Clob (Character Large Object) ou java.sql.Blob (Binary Large Object). Nous avons volontairement ajouté le mode paressseux. Effectivement, le contenu de cette propriété risque d'être de grande taille.

Pour redéfinir l'association par défaut de l'entité Livre initiale, nous pouvons utiliser de différentes façons l'annotation @Column. Ci-dessous, nous modifions les noms des colonnes associées aux attributs titre et nombreDePages, pour lesquels nous n'autorisons pas les valeurs NULL ; nous précisons également la longueur de la colonne associée à description. et enfin nous proposons un affichage spécifique pour le prix au niveau de la table si nous désirons la consulter extérieurement :

Livre.java

@Entity
public class Livre implements java.io.Serializable {
    @Id   
    @GeneratedValue(strategy = GenerationType.AUTO)
    private long id;
    @Column(name = "titre_livre", nullable = false, updatable = false)
    private String titre;
    @Column(precision = 5, scale = 2)
    private double prix;
    @Column(length = 2000)
    private String description;
    private String isbn;
    @Column(name = "nombre_pages", nullable = false)
    private int nombreDePages;
    private boolean illustrations;
...
}

Table associée

CREATE TABLE LIVRE 
( 
    ID                           BIGINT not null, 
    TITRE_LIVRE          VARCHAR(255) not null, 
    PRIX                       DOUBLE(5, 2), 
    DESCRIPTION         VARCHAR(2000), 
    ISBN                       VARCHAR(255), 
    NOMBRE_PAGES   INTEGER not null, 
    ILLUSTRATION       SMALLINT, 
    primary key (ID) 
); 

1. La plupart des éléments de l'annotation @Column influent sur l'association. Si nous fixons à 2000 la longueur de l'attribut description, par exemple, la taille de la colonne correspondante sera également de 2000.
2. Par défaut updatable et insertable valent true, ce qui signifie que nous pouvons insérer ou modifier n'importe quel attribut dans la base de données. En les positionnant à false, nous demandons au fournisseur de garantir qu'il n'insérera ni ne modifiera les données des colonnes associées à ces attributs lorsque l'entité sera elle-même modifiée.

   Notez que ceci n'implique pas que l'entité ne pourra être modifiée en mémoire - elle pourra l'être mais, en ce cas, elle ne sera plus synchronisée avec la base car l'instruction SQL qui sera produite (INSERT ou UPDATE) ne portera pas sur ces colonnes.

@Temporal(TemporalType.DATE)
private Calendar dateDeNaissance;

L'entité Photo du code source ci-dessous sera associé à la table décrite plus bas. L'attribut instant est associé à une colonne de type TIMESTAMP :

entité.Photo.java

@Entity
public class Photo implements java.io.Serializable {
    @Id
    private String id;
    @Temporal(TemporalType.TIMESTAMP)
    private Date instant;
    private int largeur;
    private int hauteur;
    private long poids;
...
}  

Table associée

CREATE TABLE PHOTO 
( 
    ID                      VARCHAR(255) not null, 
    INSTANT           TIMESTAMP, 
    LARGEUR         INTEGER, 
    HAUTEUR         INTEGER, 
    POIDS               BIGINT, 
    primary key (ID) 
);

Au travers d'une entité Personnel, nous pouvons avoir besoin éventuellement d'un attribut âge, qui est tributaire d'un calcul en rapport avec la date de naissance, mais qui ne nécessite pas spécialement d'être stocké dans la base de données. Il peut donc être déclaré comme transitoire à l'aide de l'annotation @Transient.

Personnel.java

@Entity
public class Personnel implements java.io.Serializable {
    @Id
    @GeneratedValue
    private long id;
    private String nom;
    private String prénom;
    private String email;
    private String téléphone;
    @Temporal(TemporalType.DATE)
    private Date naissance;
    @Transient
    private int âge; // cet attribut n'aura pas de colonne AGE associée
...
}  

Table associée

CREATE TABLE PERSONNEL
( 
    ID                     BIGINT not null, 
    NOM                VARCHAR(255), 
    PRENOM         VARCHAR(255), 
    EMAIL             VARCHAR(255), 
    TELEPHONE    VARCHAR(255), 
    NAISSANCE    DATE,
    primary key (ID) 
);

@Entity
public class Utilisateur implements Serializable {
   public enum Sexe {Masculin, Féminin};

   @Enumerated(value=EnumType.STRING)
   public Sexe sexe;
...
}

Les valeurs d'une énumération sont en réalité des constantes auxquelles est implicitement associée un numéro déterminé par leur ordre d'apparition dans l'énumération. Ce numéro ne peut pas être modifié en cours d'exécution mais sert à stocker la valeur du type énuméré dans la base de données. Voici, par exemple, le code source représentant une énumération de type cartes de crédit :

TypeCarteCrédit.java

public enum TypeCarteCrédit  {
   Visa,
   MasterCard,
   AmericanExpress
}  

Les numéros affectés lors de la compilation aux valeurs de ce type énuméré seront respectivement :

• 0 pour Visa,
• 1 pour MasterCard,
• 2 pour AmericanExpress.

Par défaut, les fournisseurs de persistance associerons ce type énuméré à la base de données en supposant que la colonne est de type INTEGER. Le code source suivant montre l'entité CarteCrédit qui utilise l'énumération précédente avec une association par défaut :

CarteCrédit.java

@Entity
public class CarteCrédit {
    @Id
    private String numéro;
    private String dateExpiration;
    private int numéroControl;
    private TypeCarteCrédit typeCarte;
...
}  

Les règles par défaut feront que l'énumération sera associée à une colonne de type entier et tout ira bien. Imaginons maintenant que nous ajoutions une nouvelle constante au début de l'énumération. L'affectation des numéros dépendant de l'ordre d'apparition des constantes, les valeurs déjà stockées dans la base de données ne correspondront plus à l'énumération.

Une meilleure solution consiste donc à stocker le nom de la constante à la place de son numéro d'ordre. C'est ce que nous proposons avec l'annotation @Enumerated avec la valeur STRING (sa valeur par défaut est ORDINAL).

CarteCrédit.java

@Entity
public class CarteCrédit {
    @Id
    private String numéro;
    private String dateExpiration;
    private int numéroControl;
    @Enumerated(value=EnumType.STRING)
    private TypeCarteCrédit typeCarte;
...
}  

Désormais, la colonne TYPECARTE de la table sera de type VARCHAR et une carte Visa sera stockée sous la forme "Visa".

Reprenons une nouvelle fois l'entité Personnel et modifions l'attribut téléphones qui donnera, comme son nom l'indique, la liste des numéros de téléphones. Nous avons donc besoin de mettre en place une collection de chaînes pour stocker tous ces numéros :

Personnel.java

@Entity
public class Personnel implements java.io.Serializable {
    @Id
    @GeneratedValue
    private long id;
    private String nom;
    private String prénom;
    private String email;
    private ArrayList<String> téléphones = new ArrayList<String>();
    @Temporal(TemporalType.DATE)
    private Date naissance;
    @Transient
    private int âge;
...
}  

La première démarche consiste à ne placer aucune annotation sur l'attribut téléphones. La base de données considère alors, vu qu'il s'agit d'une collection et qu'il peut y avoir un nombre conséquent de valeurs, qu'il est préférable de prendre le type BLOB au niveau de la colonne représentant ces informations.

En effet, java.util.ArrayList implémente l'interface Serializable et JPA sait associer automatiquement des objets sérializables à des BLOB. En revanche, si vous utilisez une collection java.util.List, vous obtiendrez alors une exception car List n'implémente justement pas Serializable.

Cela fonctionne parfaitement. Le problème de ce choix toutefois, c'est qu'il est alors très difficile de consulter au niveau de la table le contenu d'une telle colonne.

Personnel.java

@Entity
public class Personnel implements java.io.Serializable {
    @Id
    @GeneratedValue
    private long id;
    private String nom;
    private String prénom;
    private String email;
    @ElementCollection
    private ArrayList<String> téléphones = new ArrayList<String>();
    @Temporal(TemporalType.DATE)
    private Date naissance;
    @Transient
    private int âge;
...
}  

L'annotation @ElementCollection informe le fournisseur de persistance que l'attribut téléphones est une liste de chaînes qui devra être enregistrée dans une table séparée dont le nom est par défaut PERSONNEL_TELEPHONES avec deux colonnes, d'une part PERSONNEL_ID qui représente la clé primaire de la table PERSONNEL et TELEPHONES qui stocke l'ensemble des numéros.

L'annotation @ElementCollection est un moyen plus élégant et plus pratique de stocker les types primitifs puisque cette fois-ci nous visualisons parfaitement chacun des numéros de téléphone alors que le stockage sous un format binaire opaque aux requêtes les rends inaccessibles.

Personnel.java

@Entity
public class Personnel implements java.io.Serializable {
    @Id
    @GeneratedValue
    private long id;
    private String nom;
    private String prénom;
    private String email;
    @ElementCollection(fetch = FetchType.EAGER)
    private ArrayList<String> téléphones = new ArrayList<String>();
    @Temporal(TemporalType.DATE)
    private Date naissance;
    @Transient
    private int âge;
...
}  

Attention, les collections sont gérées de façon paresseuse au niveau de la base de données. Si vous voulez être sûr que vos numéros soient immédiatement enregistrés, il serait alors préférable de stipuler la valeur FetchType.EAGER sur l'attribut fetch de @ElementCollection.

Personnel.java

@Entity
public class Personnel implements java.io.Serializable {
    @Id
    @GeneratedValue
    private long id;
    private String nom;
    private String prénom;
    private String email;
    @ElementCollection(fetch = FetchType.EAGER)
    @CollectionTable(name = "Téléphones")
    @Column(name = "Numéro")
    private ArrayList<String> téléphones = new ArrayList<String>();
    @Temporal(TemporalType.DATE)
    private Date naissance;
    @Transient
    private int âge;
...
}  

En l'absence de @CollectionTable, nous l'avons vu, le nom de la table est PERSONNEL_TELEPHONES. Grâce à cette annotation, il est tout-à-fait possible de choisir explicitement le nom de la table représentant la collection juste en spécifiant l'attribut name. Vous remarquez que j'ai ajouté une annotation @Column supplémentaire afin de renommer également la colonne en Numéro au lieu de Téléphones.

Voici le résultat obtenu en tenant compte de ces modifications. Personnellement, je trouve que les noms proposés par défaut sont assez évocateurs et j'utilise assez rarement cette annotation @CollectionTable.

Prenons l'exemple d'un CD contenant un certain nombre de pistes. Une piste peut être considérée comme un titre et une position (la première piste de l'album, la seconde, etc.). Vous pourriez alors utiliser des cartes de pistes utilisant un entier pour représenter la position (la clé) et une chaîne pour représenter le titre (la valeur) :

CD.java

@Entity
public class CD implements java.io.Serializable {
    @Id
    @GeneratedValue
    private long id;
    private String titre;
    private double prix;
    @Lob
    private byte[] jacquette;
    private String description;
    private HashMap<Integer, String> pistes = new HashMap<Integer, String>();
...
}  

Comme précédemment, je propose de ne spécifier aucune annotation particulière sur l'attribut pistes. Là aussi, la colonne représentative PISTES de la table CD est alors de type BLOB :

Là aussi, nous obtenons qu'une seule table qui possède alors toutes les caractéristiques. Cela peut suffire et fonctionne parfaitement. Ceci dit, encore une fois, la colonne représentant les pistes est totalement illisible (mais ce n'est peut-être pas un problème).

CD.java

@Entity
public class CD implements java.io.Serializable {
    @Id
    @GeneratedValue
    private long id;
    private String titre;
    private double prix;
    @Lob
	   private byte[] jacquette;
    private String description;
    @ElementCollection(fetch = FetchType.EAGER)
    @CollectionTable(name = "Piste")
    @MapKeyColumn(name = "Position")
    @Column(name = "Titre")
    private HashMap<Integer, String> pistes = new HashMap<Integer, String>();
...
}  

1. Comme nous l'avons déjà indiqué, l'annotation @ElementCollection permet d'indiquer que les cartes seront stockées dans une table à part. L'annotation optionnelle @CollectionTable, quant à elle, est encore une fois utilisée pour modifier le nom par défaut de la table de collection en PISTE.
2. La différence avec les collections est que nous introduisons ici une nouvelle annotation, @MapKeyColumn, pour préciser l'association correspondant à la colonne clé de la carte. En son absence, le nom de cette colonne est formé par concaténation du nom de l'attribut qui référence la relation et du suffixe _KEY. Le code source précédent utilise cette annotation pour la renommer POSITION afin qu'elle porte un nom plus lisible.
3. L'annotation @Column indique que la colonne contenant les valeurs des cartes sera nommée TITRE.
   
   

Prenons l'exemple d'un client possédant un identifiant, un nom, un e-mail et une adresse. Tous ces attributs pourrait se trouver dans une seule entité Client, mais, pour des raisons de modélisation, ils sont répartis en deux classes Client et Adresse. Cette dernière n'ayant pas d'identité propre mais étant simplement une composante de l'état du client, c'est une bonne candidate au status de classe intégrable.

Adresse.java

@Embeddable
public class Adresse {
    private String rue;
    private String ville;
    private int codepostal;
    private String pays;
...
}

Comme vous pouvez le constater à la lecture de ce code source, la classe Adresse est annotée comme étant non pas une entité mais une classe intégrable - l'annotation @Embeddable indique qu'Adresse peut être intégrée dans une entité (ou dans une autre classe intégrable). A l'autre extrémité de la composition, l'entité Client doit utiliser l'annotation @Embedded pour indiquer qu'Adresse est un attribut persistant qui sera stockée comme composante interne et qu'il partage son identité.

Client.java

@Entity
public class Client implements java.io.Serializable {
    @Id
    @GeneratedValue
    private long id;
    private String nom;
    private String prénom;
    private String email;
    private String téléphone;
    @Embedded
    private Adresse adresse;
...
}  

Chaque attribut d'Adresse est associé à la table de l'entité Client. Nous disposerons ainsi d'une seule table qui fusionne l'ensemble des attributs des deux classes.

Une relation possède une direction. Elle peut être unidirectionnelle (un objet peut utiliser un autre objet) ou bidirectionnelle (un objet peut interroger un autre objet et vice versa). En Java, nous utilisons le point (.) pour naviguer entre les objets. Ainsi, lorsque nous écrivons, par exemple :

client.getAdresse().getPays();

nous navigons d'un objet de type Client vers un objet de type Adresse puis vers un objet de type Pays.

Afin d'illustrer tout ceci, comparons ensemble le code Java de sa traduction dans la base de données. Comme vous pouvez le constater dans le codage, les deux entités pointent l'une vers l'autre au moyen des attributs respectifs : Client possède un attribut adresse annoté par @OneToOne et l'entité Adresse possède l'attribut client également annoté. Au niveau de la base de données se trouvent les deux tables respectives CLIENT et ADRESSE. CLIENT est la table propriétaire de la relation car elle contient la clé étrangère vers ADRESSE.

1. L'entité Adresse utilise mappedBy de son annotation @OneToOne. Ici, mappedBy indique que la colonne de jointure (adresse) est déclarée à l'autre extrémité de la relation.
2. De son côté, l'entité Client définit la colonne de jointure avec l'annotation @JoinColumn et renomme la clé étrangère en AdresseId.
3. Client est l'extrémité propriétaire de le relation et, en tant que telle, est la seule à définir l'association de la colonne de jointure.
4. Adresse est l'extrémité opposée et c'est donc la table de l'entité propriétaire qui contient la clé étrangère (la table CLIENT possède bien une colonne ADRESSEID).

Il existe un élément mappedBy pour les annotations @OneToOne, @OneToMany et @ManyToMany, mais pas pour @ManyToOne.
.

Reprenons l'exemple d'un client et de son adresse en supposant qu'il ne dispose que d'une seule adresse (cardinalité 1). Il faut pouvoir naviguer du client (la source) vers l'adresse (la cible) pour connaître où habite le client. Dans ce cas de figure, nous n'avons pas besoin de faire le trajet inverse (cela suppose que nous n'avons pas besoin de retrouver quel client habite à une adresse donnée).

En Java, ceci signifie que la classe Client possède tout simplement un attribut adresse.
.

Client.java

@Entity
public class Client implements java.io.Serializable {
    @Id
    @GeneratedValue
    private long id;
    private String nom;
    private String prénom;
    private String email;
    private String téléphone;
    private Adresse adresse;
...
}  

Adresse.java

@Entity
public class Adresse {
    @Id
    @GeneratedValue
    private long id;
    private String rue;
    private String ville;
    private int codepostal;
    private String pays;
...
}

Comme vous pouvez le constater à la lecture de ces différents codes sources, ces deux entités utilisent un nombre minimal d'annotations - @Entity plus @Id et @GeneratedValue pour la clé primaire, c'est tout ...

Grâce à la configuration par exception, le fournisseur de persistance les associera à deux tables et ajoutera une clé étrangère pour représenter la relation (allant du client à l'adresse). Cette relation 1-1 est déclenchée par le fait qu'Adresse est déclarée comme une entité et qu'elle est incluse dans l'entité Client sous forme d'un attribut. Nous n'avons donc pas besoin d'annotation @OneToOne parce que le comportement par défaut suffit.

Comme vous le savez, si un attribut n'est pas annoté, JPA lui applique les règles d'association par défaut. Ainsi, la colonne de la clé étrangère s'appelera donc ADRESSE_ID, qui est la concaténation du nom de l'attribut (adresse, ici), d'un underscore et du nom de la clé primaire de la table de destination (ici, la colonne ID de la table ADRESSE). Notez également que, dans le langage de définition des données, la colonne ADRESSE_ID peut, par défaut, recevoir des valeurs NULL : par défaut, une relation 1-1 est donc associée à zéro (NULL) ou une valeur :

Le codage suivant présente un exemple d'utilisation de ces deux méthodes :

Client.java

@Entity
public class Client implements java.io.Serializable {
    @Id
    @GeneratedValue
    private long id;
    private String nom;
    private String prénom;
    private String email;
    private String téléphone;
    @OneToOne(cascade=CascadeType.PERSIST)
    @JoinColumn(name="AdresseId", nullable=false)
    private Adresse adresse;
...
}   

Le code précédent, grâce à l'annotation @JoinColumn permet de renommer la colonne de la clé étrangère en ADRESSEID et rendre la relation obligatoire en refusant les valeurs NULL. L'annotation @OneToOne quant à elle, demande au fournisseur de persistance d'enregistrer automatiquement l'adresse lorsque nous rendons persistant un client.

Revenons un instant sur le projet concernant l'archivage des photos. Il peut être judicieux de rajouter des fonctionnalités et de prévoir des retouches possibles sur un certain nombre de photos tout en conservant les originales. La photo renvoyée au client serait alors la version retouchée dont le traitement serait exécutée juste au moment de la requête. Pour cela, il serait utile de prévoir une persistance qui conserverait les réglages propre à la retouche, comme l'intensité, le contraste, etc.

Photo.java

@Entity
public class Photo implements java.io.Serializable {
    @Id
    private String id;
    private int largeur;
    private int hauteur;
    private long poids;
    @OneToOne(cascade=CascadeType.PERSIST)
    @PrimaryKeyJoinColumn
    private Retouche retouche;
...
}

Retouche.java

@Entity
public class Retouche implements java.io.Serializable {
    @Id
    private String id;
    private int intensité;
    private int contraste;
...
}

J'aimerais faire quelques remarques quand à la persistance de deux entités quelque soit la stratégie de l'élaboration de chacune des tables :

1. Nous devons systématiquement créer deux objets entités séparemment, un pour la Retouche et un pour la Photo.
2. Dans cet exemple précis, pour ces deux objets, vous devez définir la clé primaire qui doit être identique.
3. Le plus important encore, c'est que vous devez rendre persistant chacun de ces beans entités (sauf dans le cas d'une stratégie en cascade).

Attention, dans ce genre de situation, vous devez gérer vous-même l'identifiant commun. Vous ne pouvez pas demander une génération automatique de vos clés primaires à l'aide de l'annotation @GeneratedValue.

Voici la constitution des deux tables au niveau de la base de données associées à ces deux entités respectives :

En reprenant notre exemple, une photo n'est pas obligée d'avoir une retouche si le cliché est de bonne facture.

Pour transformer une relation Un à Un en une relation Un à Zéro, il suffit d'autoriser la valeur null dans la colonne implémentant la relation. Pour cela, il est nécessaire de positionner l'attribut nullable de l'annotation @JoinColumn à true. En réalité, c'est la valeur par défaut. Nous n'avons donc pas besoin de le spécifier.

Attention, l'annotation @PrimaryKeyJoinColumn ne possède pas un tel attribut, ce qui sous-entends que l'aspect facultatif ne peut pas être prise en compte et que la seule relation possible dans ce cas là, ne peut être qu'une relation de type 1-1. Finalement, si vous désirez intégrer le caractère facultatif d'un élément, vous êtes obligé de passer par une clé étrangère.

Photo.java

@Entity
public class Photo implements java.io.Serializable {
    @Id
    private String id;
    private int largeur;
    private int hauteur;
    private long poids;
    @OneToOne(cascade=CascadeType.PERSIST)
    @JoinColumn(nullable=true)
    private Retouche retouche;
...
}

Retouche.java

@Entity
public class Retouche implements java.io.Serializable {
    @Id  @GeneratedValue
    private long id;
    private int intensité;
    private int contraste;
...
}

Attention, dans l'entité Retouche, il est préférable de prendre un identifiant de type long avec une génération automatique.
.

Voici la constitution des deux tables dans la base de données associées à ces deux entités respectives :

Dans le diagramme UML ci-dessous, l'entité Commande est l'extrémité "One" (la source) de la relation (composition), et l'entité Article est son extrémité "Many" (la cible).

La cardinalité est multiple et la navigation ne se fait que dans le sens Commande vers Article. En Java, cette multiplicité est décrite par les interfaces Collection, List et Set du paquetage java.util.

Commande.java

@Entity
public class Commande implements java.io.Serializable {
    @Id
    @GeneratedValue
    private long id;
    @Temporal(TemporalType.TIMESTAMP)
    private Date dateCréation;
    private List<Article> articles = new ArrayList<Article>();
...
}  

Article.java

@Entity
public class Article implements java.io.Serializable {
    @Id
    @GeneratedValue
    private long id;
    private String intitulé;
    private double prixUnitaire;
    private int quantité;
...
}

Comme vous pouvez le constater à la lecture du code relatif à l'entité Commande, nous n'avons placé aucune annotation particulière sur la collection d'articles. Comme toujours, cela veut dire que nous restons dans une configuration par exception.

1. Ainsi, lorsqu'une entité possède un attribut qui est une collection d'une autre entité, le système déclenche automatiquement une association de type OneToMany par défaut.
2. Toujours par défaut, les relations 1-N unidirectionnelles utilisent une table de jointure pour représenter la relation. Cette table est une liste de couples de clés étrangères : une clé fait référence à la table COMMANDE avec le même type que sa clé primaire, l'autre désigne la table ARTICLE. Cette table de jointure s'appelle par défaut COMMANDE_ARTICLE.
   
   

Comme précédemment, si vous n'aimez pas le nom de la table de jointure ou celui des clés étrangères, ou si vous désirez associer la relation à une table existante, vous pouvez vous servir des annotations JPA pour redéfinir ces valeurs par défaut.

1. Le nom d'une colonne de jointure est formée par défaut par la concaténation du nom de l'entité, de l'underscore et du nom de la clé primaire désignée par la clé étrangère (COMMANDE_ID et ARTICLE_ID).
2. Comme l'annotation @JoinColumn permet de modifier le nom des colonnes de clés étrangères, @JoinTable fait de même pour la table de jointure.
3. Vous pouvez également utiliser l'annotation @OneToMany, qui, comme @OneToOne, permet de personnaliser la relation elle-même.

   API de l'annotation @JoinTable

   package javax.persistence;
   
   import java.lang.annotation.*;
   
   @Target(value = {ElementType.METHOD, ElementType.FIELD})
   @Retention(value = RetentionPolicy.RUNTIME)
   public @interface JoinTable {
   
       public String name() default "";
       public String catalog() default "";
       public String schema() default "";
       public JoinColumn[ ] joinColumns() default { };
       public JoinColumn[ ] inverseJoinColumns() default { };
       public UniqueConstraint[ ] uniqueConstraints() default  { };
   }

   Dans l'API de l'annotation @JoinTable, vous pouvez remarquer deux attributs de type @JoinColumn : joinColumns et inverseJoinColumns. Ils permettent de différencier l'extrémité propriétaire de la relation et son extrémité opposée. L'extrémité propriétaire de la relation est décrite dans l'élément joinColumns et, dans notre exemple, désigne la table COMMANDE. L'extrémité opposée, la cible de la relation, est précisée par l'élément inverseJoinColumns et désigne la table ARTICLE.

   Commande.java

   @Entity
   public class Commande implements java.io.Serializable {
       @Id
       @GeneratedValue
       private long id;
       @Temporal(TemporalType.TIMESTAMP)
       private Date dateCréation;
       @JoinTable(name="ArticlesCommandés",
                           joinColumns=@JoinColumn(name="NuméroCommande"),
                           inverseJoinColumns=@JoinColumn(name="Article"))
       private List<Article> articles = new ArrayList<Article>();
   ...
   }  

   

Attention, le mode de parcours par défaut dans une relation 1-N est le mode paresseux. Si vous désirez systématiquement avoir à votre possession l'ensemble des articles constituant une commande en spécifiant le mode EAGER dans l'annotation @OneToMany. Comme précédemment, vous pouvez également en profiter pour imposer une persistance automatique de l'ensemble des articles au moment de la persistance de la commande.

Commande.java

@Entity
public class Commande implements java.io.Serializable {
    @Id
    @GeneratedValue
    private long id;
    @Temporal(TemporalType.TIMESTAMP)
    private Date dateCréation;
    @OneToMany(fetch=FetchType.EAGER, cascade=CascadeType.ALL)
    @JoinColumn(name="NuméroCommande")
    private List<Article> articles = new ArrayList<Article>();
...
}  

En supposant que l'entité Artiste est propriétaire de la relation, ceci implique que CD est l'extrémité opposée et qu'elle doit utiliser l'élément mappedBy de son annotation @ManyToMany. Ici, mappedBy indique au fournisseur de persistance que présentSurCDs est le nom de l'attribut correspondant dans l'entité propriétaire de la relation :

Artiste.java

@Entity
public class Artiste implements java.io.Serializable {
    @Id
    @GeneratedValue
    private long id;
    private String nom;
    private String prénom;
    @ManyToMany
    private List<CD> présentSurCDs = new ArrayList<CD>();
...
}  

CD.java

@Entity
public class CD implements java.io.Serializable {
    @Id
    @GeneratedValue
    private long id;
    private String titre;
    private double prix;
    private String description;
    @ManyToMany(mappedBy="présentSurCds")
    private List<Artiste> artistes = new ArrayList<Artiste>();
...
}

La structure de la base de données obtenue est la suivante :

Dans une relation N-M et 1-1 bidirectionnelle, chaque entité peut, en fait, être considérée comme la propriétaire de la relation. Quoi qu'il en soit, l'autre extrémité doit inclure l'élément mappedBy : dans le cas contraire, le fournisseur considérera que les deux extrémités sont propriétaires et traitera cette relation comme deux relations 1-N unidirectionnelles distinctes. Ici, cela produirait donc quatre tables : ARTISTE et CD et deux tables de jointures, ARTISTE_CD et CD_ARTISTE. Vous comprenez bien que nous ne pouvons pas non plus utiliser un élément mappedBy des deux côtés de la relation.

Ne pensez pas qu'EAGER est le mal et LAZY, le bien.

1. EAGER placera toutes les données en mémoire à l'aide d'un petit nombre d'accès à la base (le fournisseur de persistance utilisera sûrement des jointures pour extraire ces données).
2. Avec LAZY, vous ne risquez plus de remplir la mémoire puisque vous contrôlez les objets qui seront chargés, mais vous devrez faire plus d'accès à la base à chaque fois.

Le paramètre fetch est finalement très important car, mal utilisé, il peut pénaliser les performances.
.

Lorsque, par exemple, vous chargez une commande dans votre application, vous avez toujours besoin d'accéder aux différents articles de cette commande. Il est donc plutôt avantageux de changer le mode de chargement par défaut de l'annotation @OneToMany en EAGER.

Commande.java

@Entity
public class Commande implements java.io.Serializable {
    @Id
    @GeneratedValue
    private long id;
    @Temporal(TemporalType.TIMESTAMP)
    private Date dateCréation;
    @OneToMany(fetch=FetchType.EAGER, cascade=CascadeType.ALL)
    @JoinColumn(name="NuméroCommande")
    private List<Article> articles = new ArrayList<Article>();
...
}  

En reprenant l'exemple de l'application d'entreprise sur les commandes, nous pouvons rajouter une entité Client qui possède événtuellement plusieurs commandes qui seraient souhaitables qu'elles apparaissent chronologiquement.

Dans l'entité Client, nous trions la liste des commandes par ordre décroissant des dates de création de chaque commande, en combinant l'annotation @OrderBy avec l'annotation @OneToMany.

Client.java

@Entity
public class Client implements java.io.Serializable {
    @Id
    @GeneratedValue
    private long id;
    private String nom;
    private String prénom;
    private String email;
    private String téléphone;
    @OneToMany(fetch=FetchType.EAGER)
    @OrderBy("dateCréation desc")
    private Commande commandes;
...
}   

Commande.java

@Entity
public class Commande implements java.io.Serializable {
    @Id
    @GeneratedValue
    private long id;
    @Temporal(TemporalType.TIMESTAMP)
    private Date dateCréation;
    @OneToMany(fetch=FetchType.EAGER, cascade=CascadeType.ALL)
    @JoinColumn(name="NuméroCommande")
    private List<Article> articles = new ArrayList<Article>();
...
}  

L'annotation @OrderBy prend en paramètre les noms des attributs sur lesquels portera le tri (dateCréation, ici) et la méthode (représentée par la chaîne ASC ou DESC, pour signifier, respectivement, un tri croissant ou décroissant). Vous pouvez utiliser plusieurs paires attribut/méthode en les séparant par des virgules : immaginons, par exemple, qu'une entité supérieure ait besoin de trier les clients ; d'abord suivant leurs noms et ensuite suivant leurs prénoms. Voici ce que nous pourrions placer sur un attribut représentant une collection de clients.

@OrderBy("nom asc", "prénom asc")

Cette annotation n'a aucun impact sur l'association dans la base de données - le fournisseur de persistance est simplement informé qu'il doit utiliser une clause order by lorsque la collection est récupérée.

package javax.persistence;

import java.lang.annotation.*;

@Target(value = {ElementType.METHOD, ElementType.FIELD})
@Retention(value = RetentionPolicy.RUNTIME)
public @interface OrderColumn {

    public String name() default "";
    public boolean nullable() default true;
    public boolean insertable() default true;
    public boolean updatable() default true;
    public String columnDefinition() default "";
    public boolean contiguous() default true;
    public int base() default 0;
    public String table() default "";
}

Reprenons l'exemple mise en place précédemment avec la gestion des clients avec leurs commandes en le modifiant légèrement.

Dans l'entité Client, nous pouvons alors annoter la relation avec les commandes avec @OrderColumn afin que cette fois-ci le fournisseur de persistance associe l'entité Client à une table contenant une colonne supplémentaire pour stocker l'ordre.

Client.java

@Entity
public class Client implements java.io.Serializable {
    @Id
    @GeneratedValue
    private long id;
    private String nom;
    private String prénom;
    private String email;
    private String téléphone;
    @OneToMany(fetch=FetchType.EAGER)
    @OrderColumn
    private Commande commandes;
...
}   

Commande.java

@Entity
public class Commande implements java.io.Serializable {
    @Id
    @GeneratedValue
    private long id;
    @Temporal(TemporalType.TIMESTAMP)
    private Date dateCréation;
    @OneToMany(fetch=FetchType.EAGER, cascade=CascadeType.ALL)
    @JoinColumn(name="NuméroCommande")
    private List<Article> articles = new ArrayList<Article>();
...
}  

L'annotation @OrderColumn prend éventuellement en paramètre le nom de la nouvelle colonne. Si ce nom n'est pas redéfini, cette colonne porte alors le nom formé de la concaténation de l'entité référencée et la chaîne _ORDER (COMMANDES_ORDER, ici). Le type de cette colonne doit absolument être numérique.

Cette annotation a des conséquences sur les performances car le fournisseur de persistance doit maintenant également gérer les modifications de l'index. Il doit maintenir le tri après chaque insertion, suppression ou réordonnacement. Si les données sont insérées au milieu d'une liste triée, le fournisseur devra retrier tout l'index.

Pour réaliser un tri, vous avez donc le choix entre ces deux annotations @OrderColumn et @OrderBy. Pour ma part, je préfère largement cette dernière puisqu'elle prend moins de ressources au niveau de la base de données. Par ailleurs, avec @OrderColumn, vous ne pouvait pas spécifier le critère d'ordonancement. Attention, quelque soit votre choix, ces deux annotations ne peuvent pas être utilisées en même temps.

Afin d'expliquer chacune de ces stratégies, nous étudierons comment traduire les entités CD et Livre, qui héritent toutes les deux de l'entité Document.

Document est l'entité racine ; elle possède un identifiant unique qui servira de clé primaire pour l'ensemble de la hiérarchie. La clé primaire sera ainsi automatiquement récupérée par le mécanisme d'héritage. Chacune de ses classes filles ajoute également ses propres attributs supplémentaires comme genre pour l'entité Livre et duréeTotale pour l'entité CD.

Il n'est donc pas nécessaire d'utiliser l'annotation @Inheritance sur l'entité racine, comme le montre le code suivant :

Document.java

@Entity
public abstract class Document implements java.io.Serializable {
    @Id
    @GeneratedValue
    private long id;
    private String titre;
    private double prix;
    private String description;
    private Auteur auteur;
...
}  

Document est la classe parente des entités Livre et CD. Ces entités héritent des attributs de Document ainsi que de la stratégie d'héritage par défaut : elles n'ont donc pas besoin elles-même d'utiliser l'annotation @Inheritance.

Livre.java

@Entity
public class Livre extends Document {
    private String genre;
    private int nombrePages;
    private boolean illustration;
...
}

CD.java

@Entity
public class CD extends Document {
    private double duréeTotale;
    @ElementCollection
    private List<String> pistes = new ArrayList<String>();
...
}

Sans l'héritage, ces trois entités seraient traduites en trois tables distinctes. Avec la stratégie de traduction de l'héritage par une seule table, elles finiront toutes dans la table portant par défaut le nom de la classe racine : DOCUMENT.

Comme vous pouvez le constater, la table DOCUMENT rassemble tous les attributs des entités Document, Livre et CD. Cependant, elle contient une colonne supplémentaire qui n'est liée à aucun des attributs des entités : la colonne discriminante, DTYPE.

La table DOCUMENT sera remplie de livres et de CD. Lorsqu'il accède aux données, le fournisseur de persistance doit savoir à quelle entité appartient chaque ligne afin d'instancier la classe d'objet appropriée (Livre ou CD) : la colonne discriminante est donc là pour préciser explicitement le type de chaque colonne.

1. Cette stratégie fournit un gain de performance important, car aucune jointure n'est réalisée.
2. En même temps, comme vous pouvez le constater, la stratégie avec une table possède quelques défauts. Nous voyons, par exemple, que toutes les colonnes ne sont pas nécessairement utiles à toutes les entités (cases violettes). Suivant le cas, nous pouvons obtenir de gros gaspillages. Lorsque nous enregistrons, par exemple, un disque dans la base de données, les colonnes GENRE, NOMBREPAGES et ILLUSTRATION deviennent totalement inutiles.
   
   

Dans le code suivant, nous renommons la colonne discriminante en DOCUMENT (au lieu donc de DTYPE). Nous proposons également de changer le type de cette colonne pour qu'elle soit de type char en lieu et place du type String. Du coup, chaque entité concrète change également sa valeur discrimante par défaut et propose la lettre "L" pour indiquer qu'il s'agit d'un document de type Livre, et la lettre "C" pour indiquer qu'il s'agit d'un CD :

Document.java

@Entity
@DiscriminatorColumn(name="Document", discriminatorType=DiscriminatorType.CHAR)
public abstract class Document implements java.io.Serializable {
    @Id
    @GeneratedValue
    private long id;
    private String titre;
    private double prix;
    private String description;
    private Auteur auteur;
...
}  

L'entité racine Document définit la colonne discriminante pour toute la hiérarchie à l'aide de l'annotation @DiscriminatorColumn. Pour que cela fonctionne correctement, chaque entité fille doit uniquement redéfinir sa propre valeur discriminante au moyen de l'annotation @DiscriminatorValue.

Livre.java

@Entity
@DiscriminatorValue("L")
public class Livre extends Document {
    private String genre;
    private int nombrePages;
    private boolean illustration;
...
}

CD.java

@Entity
@DiscriminatorValue("C")
public class CD extends Document {
    private double duréeTotale;
    @ElementCollection
    private List<String> pistes = new ArrayList<String>();
...
}

Voici le résultat obtenu par rapport au choix que nous venons de réaliser :

Conclusion sur cette stratégie

1. Cette stratégie de table unique est donc la stratégie par défaut ; c'est la plus facile à comprendre et elle fonctionne très bien lorsque la hiérérachie est relativement simple et stable. En revanche, comme nous l'avons déjà évoqué, elle possède quelques défauts : notamment, l'ajout de nouvelles entités dans la hiérarchie ou d'attributs dans des entités existantes implique d'ajouter des colonnes à la table, de migrer les données et de modifier les index.
2. Cette stratégie exige également que les colonnes des entités filles puissent recevoir la valeur NULL : si GENRE de l'entité Livre n'était pas nullable, par exemple, nous serions dans l'incapacité de pouvoir insérer un CD puisque ce dernier ne possède pas cette rubrique.

Pour terminer, il est également possible de mapper cette colonne DOCUMENT sur un attribut (typeDocument) afin de pouvoir contrôler par programme les différents types d'objets enregistrés, à condition toutefois de bien préciser insertable=false et updatable=false :

Document.java

@Entity
@DiscriminatorColumn(name="Document", discriminatorType=DiscriminatorType.CHAR)
public abstract class Document implements java.io.Serializable {
    @Id
    @GeneratedValue
    private long id;
    private String titre;
    private double prix;
    private String description;
    private Auteur auteur;
    @Column(name="Document", insertable=false, updatable=false)
    private char typeDocument;
...
}  

Pour implémenter une stratégie par jointure, nous sommes cette fois-ci obligé d'utiliser l'annotation @Inheritance sur l'entité racine en spécifiant le bon paramètre au niveau de l'attribut.

Le seul attribut de cette annotation est strategy. Il permet de spécifier le type de stratégie à utiliser pour construire la ou les tables à mettre en oeuvre, via l'énumération InheritanceType.

Pour indiquer que nous désirons une stratégie par jointure, nous prenons le paramètre InheritanceType.JOINED dans l'annotation @Inheritance. Par contre, les classes filles n'ont pas besoin d'autre annotation que @Entity (sauf éventuellement l'annotation propre à la valeur du discriminant). A ce sujet, nous pouvons là aussi utiliser l'annotation @DiscriminatorColumn dans l'entité racine afin de personnaliser la colonne discriminante.

Document.java

@Entity
@Inheritance(strategy=InheritanceType.JOINED)
@DiscriminatorColumn(name="Document", discriminatorType=DiscriminatorType.CHAR)
public abstract class Document implements java.io.Serializable {
    @Id
    @GeneratedValue
    private long id;
    private String titre;
    private double prix;
    private String description;
    private Auteur auteur;
...
}  

Livre.java

@Entity
@DiscriminatorValue("L")
public class Livre extends Document {
    private String genre;
    private int nombrePages;
    private boolean illustration;
...
}

CD.java

@Entity
@DiscriminatorValue("C")
public class CD extends Document {
    private double duréeTotale;
    @ElementCollection
    private List<String> pistes = new ArrayList<String>();
...
}

Du point de vue du développeur, la stratégie par jointure est naturelle car chaque entité, qu'elle soit abstraite ou concrète, sera traduite dans une table distincte.

1. L'avantage de cette stratégie est d'avoir un modèle relationnel clair. C'est en quelque sorte le modèle idéal pour la base de données (pas de perte mémoire car tous les champs sont utilisés). La stratégie par jointure est également intuitive et proche de ce que nous connaissons du mécanisme de l'héritage. C'est un moyen de fournir un bon support au polymorphisme.
2. En contre parti, elle a un impact sur les performances des requêtes. En effet, pour recréer une simple instance d'une sous-classe, il faut joindre sa table à celle de la classe racine. Plus la hiérarchie est profonde, plus il faudra de jointures pour recréer l'entité feuille. Dans le cas de hiérarchies importantes (grande profondeur de l'héritage) cela peut entraîner de très mauvaises performances.

Pour spécifier cette stratégie, il faut juste choisir cette fois-ci InheritanceType.TABLE_PER_CLASS dans l'annotation @Inheritance. Encore une fois, les classes filles héritent simplement sans avoir besoin de préciser de spécifications supplémentaires autres que @Entity.

Document.java

@Entity
@Inheritance(strategy=InheritanceType.TABLE_PER_CLASS)
public abstract class Document implements java.io.Serializable {
    @Id
    @GeneratedValue
    private long id;
    private String titre;
    private double prix;
    private String description;
    private Auteur auteur;
...
}  

Livre.java

@Entity
public class Livre extends Document {
    private String genre;
    private int nombrePages;
    private boolean illustration;
...
}

CD.java

@Entity
public class CD extends Document {
    private double duréeTotale;
    @ElementCollection
    private List<String> pistes = new ArrayList<String>();
...
}

Voici les tables obtenues. Vous remarquez que LIVRE et CD dupliquent les colonnes ID, TITRE, PRIX, DESCRIPTION et AUTEUR_ID de la table DOCUMENT et que les tables ne sont plus liées entre elles.

1. Cette stratégie est très performante lorsque nous interrogeons des instances d'une seule entité car nous nous retrouvons dans un scénario comparable à l'utilisation de la stratégie à une seule table - la requête ne porte que sur une seule table.
2. L'inconvénient est que les requêtes polymorphiques à travers une hiérarchie de classes sont plus coûteuses que les deux autres stratégies. Par exemple, pour rechercher tous les articles, que ce soit des livres ou des CD, il faut alors interroger toutes les tables des sous-classes avec une opération utilisant une UNION, ce qui est coûteux lorsque nous avons beaucoup de données. L'autre inconvénient est la duplication des colonnes dans chacune des tables des beans entités.

Dans le code source ci-dessous, Document devient une simple classe transitoire.

Document.java

public abstract class Document implements java.io.Serializable {
    private String titre;
    private double prix;
    private String description;
    private Auteur auteur;
...
}  

L'entité Livre hérite toujours de Document ; le code Java peut donc accéder aux attributs titre, prix, description et auteur ainsi qu'à toutes les méthodes de Document. Que cette dernière soit concrète ou abstraite n'aura aucune influence sur la traduction finale.

Livre.java

@Entity
public class Livre extends Document {
    @Id
    @GeneratedValue
    private long id;
    private String genre;
    private int nombrePages;
    private boolean illustration;
...
} 

Livre est une entité qui hérite de Document, mais seuls les attributs de Livre seront stockés dans une table. Aucun attribut de Document n'apparaît dans la structure de la table ci-dessous. Pour qu'un Livre soit persistant, vous devez créer une instance de Livre, initialiser les attributs que vous souhaitez (titre, prix, description, etc.), mais seuls ceux de Livre (genre, nombrePages, etc.) seront stockés.

Dans le code source ci-dessous, la classe racine Document est annotée par @MappedSuperclass, pas par @Entity. Elle définit une stratégie de traduction de l'héritage (JOINED) et annote certains de ses attributs avec @Column. Cependant, les superclasses "mapped" n'étant pas associées à des tables, l'annotation @Table n'est pas autorisée.

Document.java

@MappedSuperclass
@Inheritance(strategy=InheritanceType.JOINED)
public abstract class Document implements java.io.Serializable {
    @Id
    @GeneratedValue
    private long id;
    @Column(length=50, nullable=false)
    private String titre;
    private double prix;
    @Column(length=2000)
    private String description;
...
}

L'entité Livre hérite toujours de Document ; le code Java peut donc accéder aux attributs titre, prix, description et auteur ainsi qu'à toutes les méthodes de Document. Que cette dernière soit concrète ou abstraite n'aura aucune influence sur la traduction finale.

Livre.java

@Entity
public class Livre extends Document {
    private String genre;
    private int nombrePages;
    private boolean illustration;
...
} 

Livre est une entité qui hérite encore de Document. Cette hiérarchie sera traduite en une seule table. Document n'est pas une entité et n'a donc aucune table associée. Les attributs de Document seront traduits en colonnes de la table LIVRE - les superclasses "mapped" partageant également leurs informations de traduction, les annotations @Column de Document seront donc également héritées.