Hibernate Annotations

@Table est positionnée au niveau de la classe ; cela vous permet de définir le nom de la table, du catalogue et du schéma pour le mapping de votre entity bean. Si aucune @Table n'est définie les valeurs par défaut sont utilisées : le nom de la classe de l'entité (sans le nom de package).

@Entity
@Table(name="tbl_sky")
public class Sky implements Serializable {
...
            

L'élément @Table contient aussi un attribut schema et un attribut catalog, si vous avez besoin de les définir. Vous pouvez aussi définir des contraintes d'unicité sur la table en utilisant l'annotation @UniqueConstraint en conjonction avec @Table (pour une contrainte d'unicité n'impliquant qu'une seule colonne, référez-vous à @Column).

@Table(name="tbl_sky",
    uniqueConstraints = {@UniqueConstraint(columnNames={"month", "day"})}
)

Une contrainte d'unicité est appliquée au tuple {month, day}. Notez que le tableau columnNames fait référence aux noms logiques des colonnes.

Vous pouvez ajouter un contrôle de concurrence optimiste à un entity bean en utilisant l'annotation @Version :

@Entity
public class Flight implements Serializable {
...
    @Version
    @Column(name="OPTLOCK")
    public Integer getVersion() { ... }
}           

La propriété de version sera mappée sur la colonne OPTLOCK, et le gestionnaire d'entités l'utilisera pour détecter des conflits lors des mises à jour (prévenant des pertes de données lors de mises à jours que vous pourriez voir avec la stratégie du last-commit-wins).

La colonne de version peut être un numérique (solution recommandée) ou un timestamp comme pour la spécification EJB3. Hibernate prend en charge n'importe quel type fourni que vous définissez et implémentez avec la classe UserVersionType appropriée.

Chaque propriété (champ ou méthode) non statique non transient d'un entity bean est considérée persistante, à moins que vous l'annotiez comme @Transient. Ne pas avoir d'annotation pour votre propriété est équivalent à l'annotation @Basic. L'annotation @Basic vous permet de déclarer la stratégie de récupération pour une propriété :

public transient int counter; // propriété transient

private String firstname; // propriété persistante

@Transient
String getLengthInMeter() { ... } // propriété transient

String getName() {... } // propriété persistante

@Basic
int getLength() { ... } // propriété persistante

@Basic(fetch = FetchType.LAZY)
String getDetailedComment() { ... } // propriété persistante

@Temporal(TemporalType.TIME)
java.util.Date getDepartureTime() { ... } // propriété persistante

@Enumerated(EnumType.STRING)
Starred getNote() { ... } // enum persistée en tant que String dans la base de données

counter, un champ transient, et lengthInMeter, une méthode annotée comme @Transient, seront ignorés par le gestionnaire d'entités. Les propriétés name, length, et firstname sont mappées comme persistantes et à charger immédiatement (ce sont les valeurs par défaut pour les propriétés simples). La valeur de la propriété detailedComment sera chargée à partir de la base de données dès que la propriété de l'entité sera accédée pour la première fois. En général vous n'avez pas besoin de marquer de simples propriétés comme "à charger à la demande" (NdT: lazy) (à ne pas confondre avec la récupération d'association "lazy").

L'alternative recommandée est d'utiliser la capacité de projection de JPA-QL ou des requêtes Criteria.

EJB3 prend en charge le mapping de propriété de tous les types élémentaires pris en charge par Hibernate (tous les types de base Java, leur wrapper respectif et les classes sérialisables). Hibernate Annotations prend en charge le mapping des types Enum soit vers une colonne ordinale (en stockant le numéro ordinal de l'enum), soit vers une colonne de type chaîne de caractères (en stockant la chaîne de caractères représentant l'enum) : la représentation de la persistance, par défaut ordinale, peut être surchargée grâce à l'annotation @Enumerated comme montré avec la propriété note de l'exemple.

Dans les APIs core de Java, la précision temporelle n'est pas définie. Lors du traitement de données temporelles vous pourriez vouloir décrire la précision attendue dans la base de données. Les données temporelles peuvent avoir une précision de type DATE, TIME, ou TIMESTAMP (c'est-à-dire seulement la date, seulement l'heure, ou les deux). Utilisez l'annotation @Temporal pour ajuster cela.

@Lob indique que la propriété devrait être persistée dans un Blob ou un Clob selon son type : java.sql.Clob, Character[], char[] et java.lang.String seront persistés dans un Clob. java.sql.Blob, Byte[], byte[] et les types sérialisables seront persistés dans un Blob.

@Lob
public String getFullText() {
    return fullText;
}

@Lob
public byte[] getFullCode() {
    return fullCode;
}
 

Si le type de la propriété implémente java.io.Serializable et n'est pas un type de base, et si la propriété n'est pas annotée avec @Lob, alors le type Hibernate serializable est utilisé.

La(les) colonne(s) utilisée(s) pour mapper une propriété peuvent être définies en utilisant l'annotation @Column. Utilisez-la pour surcharger les valeurs par défaut (voir la spécification EJB3 pour plus d'informations sur les valeurs par défaut). Vous pouvez utilisez cette annotation au niveau de la propriété pour celles qui sont :

@Entity
public class Flight implements Serializable {
...
@Column(updatable = false, name = "flight_name", nullable = false, length=50)
public String getName() { ... }
            

La propriété name est mappée sur la colonne flight_name, laquelle ne peut pas avoir de valeur nulle, a une longueur de 50 et ne peut pas être mise à jour (rendant la propriété immuable).

Cette annotation peut être appliquée aux propriétés habituelles ainsi qu'aux propriétés @Id ou @Version.

@Column(
    name="columnName";                                (1)
    boolean unique() default false;                   (2)
    boolean nullable() default true;                  (3)
    boolean insertable() default true;                (4)
    boolean updatable() default true;                 (5)
    String columnDefinition() default "";             (6)
    String table() default "";                        (7)
    int length() default 255;                         (8)
    int precision() default 0; // decimal precision   (9)
    int scale() default 0; // decimal scale

Il est possible de déclarer un composant embarqué à l'intérieur d'une entité et même de surcharger le mapping de ses colonnes. Les classes de composant doivent être annotées au niveau de la classe avec l'annotation @Embeddable. Il est possible de surcharger le mapping de colonne d'un objet embarqué pour une entité particulière en utilisant les annotations @Embedded et @AttributeOverride sur la propriété associée :

@Entity
public class Person implements Serializable {

    // Composant persistant utilisant les valeurs par défaut
    Address homeAddress;

    @Embedded
    @AttributeOverrides( {
            @AttributeOverride(name="iso2", column = @Column(name="bornIso2") ),
            @AttributeOverride(name="name", column = @Column(name="bornCountryName") )
    } )
    Country bornIn;
    ...
}
            

@Embeddable
public class Address implements Serializable {
    String city;
    Country nationality; // par de surcharge ici
}
            

@Embeddable
public class Country implements Serializable {
    private String iso2;
    @Column(name="countryName") private String name;

    public String getIso2() { return iso2; }
    public void setIso2(String iso2) { this.iso2 = iso2; }


    public String getName() { return name; }
    public void setName(String name) { this.name = name; }
    ...
}
            

Un objet embarquable hérite du type d'accès de son entité d'appartenance (notez que vous pouvez surcharger cela en utilisant les annotations spécifiques à Hibernate @AccessType, voir Extensions d'Hibernate Annotation).

L'entity bean Person a deux propriétés composant, homeAddress et bornIn. La propriété homeAddress n'a pas été annotée, mais Hibernate devinera que c'est un composant persistant en cherchant l'annotation @Embeddable dans la classe Address. Nous surchargeons aussi le mapping d'un nom de colonne (pour bornCountryName) avec les annotations @Embedded et @AttributeOverride pour chaque attribut mappé de Country. Comme vous pouvez le voir, Country est aussi un composant imbriqué de Address, utilisant de nouveau la détection automatique d'Hibernate et les valeurs par défaut EJB3. Surcharger des colonnes d'objets embarqués d'objets (eux-mêmes) embarqués n'est actuellement pas pris en charge par la spécification EJB3, cependant, Hibernate Annotations le prend en charge à travers des expressions séparées par des points.

    @Embedded
    @AttributeOverrides( {
            @AttributeOverride(name="city", column = @Column(name="fld_city") ),
            @AttributeOverride(name="nationality.iso2", column = @Column(name="nat_Iso2") ),
            @AttributeOverride(name="nationality.name", column = @Column(name="nat_CountryName") )
            // les colonnes de nationality dans homeAddress sont surchargées
    } )
    Address homeAddress;

Hibernate Annotations prend en charge une fonctionnalité de plus qui n'est pas explicitement prise en charge par la spécification EJB3. Vous pouvez annoter un objet embarqué avec l'annotation @MappedSuperclass pour rendre les propriétés de la classe parente persistantes (voir @MappedSuperclass pour plus d'informations).

Alors que ce n'est pas pris en charge par la spécification EJB3, Hibernate Annotations vous permet d'utiliser les annotations d'association dans un objet embarquable (ie @*ToOne ou @*ToMany). Pour surcharger les colonnes de l'association vous pouvez utiliser @AssociationOverride.

Si vous voulez avoir le même type d'objet embarquable deux fois dans la même entité, le nom de colonne par défaut ne fonctionnera pas : au moins une des colonnes devra être explicitée. Hibernate va au-delà de la spécification EJB3 et vous permet d'améliorer le mécanisme par défaut avec NamingStrategy. DefaultComponentSafeNamingStrategy est une petite amélioration par rapport à la stratégie par défaut EJB3NamingStrategy qui permet aux objets embarqués de fonctionner avec leur valeur par défaut même s'ils sont utilisés deux fois dans la même entité.

Si une propriété n'est pas annotée, les règles suivantes s'appliquent :

Cette stratégie a beaucoup d'inconvénients (surtout avec les requêtes polymorphiques et les associations) expliqués dans la spécification EJB3, la documentation de référence d'Hibernate, Hibernate in Action, et plusieurs autres endroits. Hibernate en contourne la plupart en implémentant cette stratégie en utilisant des requêtes SQL UNION. Elle est habituellement utilisée pour le niveau le plus haut d'une hiérarchie d'héritage :

@Entity
@Inheritance(strategy = InheritanceType.TABLE_PER_CLASS)
public class Flight implements Serializable {
            

Cette stratégie prend en charge les associations de un vers plusieurs bidirectionnelles. Cette stratégie ne prend pas en charge la stratégie de générateur IDENTITY : l'identifiant doit être partagé par plusieurs tables. Par conséquent, lors de l'utilisation de cette stratégie, vous ne devriez pas utilisez AUTO ni IDENTITY.

Toutes les propriétés de toutes les classes parentes et classes filles sont mappées dans la même table, les instances sont différenciées par une colonne spéciale discriminante :

@Entity
@Inheritance(strategy=InheritanceType.SINGLE_TABLE)
@DiscriminatorColumn(
    name="planetype",
    discriminatorType=DiscriminatorType.STRING
)
@DiscriminatorValue("Plane")
public class Plane { ... }

@Entity
@DiscriminatorValue("A320")
public class A320 extends Plane { ... }
            

Plane est la classe parente, elle définit la stratégie d'héritage InheritanceType.SINGLE_TABLE. Elle définit aussi la colonne discriminante avec l'annotation @DiscriminatorColumn, une colonne discriminante peut aussi définir le type du discriminant. Finalement, l'annotation @DiscriminatorValue définit la valeur utilisée pour différencier une classe dans la hiérarchie. Tous ces attributs ont des valeurs par défaut sensées. Le nom par défaut de la colonne discriminante est DTYPE. La valeur discriminante par défaut est le nom de l'entité (comme défini dans @Entity.name) avec le type DiscriminatorType.STRING. A320 est une classe fille ; vous devez seulement définir la valeur discriminante si vous ne voulez pas utiliser la valeur par défaut. La stratégie et le type du discriminant sont implicites.

@Inheritance et @DiscriminatorColumn devraient seulement être définies sur l'entité la plus haute de la hiérarchie.

Les annotations @PrimaryKeyJoinColumn et @PrimaryKeyJoinColumns définissent la (les) clef(s) primaire(s) de la table de la classe fille jointe :

@Entity
@Inheritance(strategy=InheritanceType.JOINED)
public class Boat implements Serializable { ... }

@Entity
public class Ferry extends Boat { ... }

@Entity
@PrimaryKeyJoinColumn(name="BOAT_ID")
public class AmericaCupClass  extends Boat { ... }
            

Toutes les entités ci-dessus utilisent la stratégie JOINED, la table Ferry est jointe avec la table Boat en utilisant les mêmes noms de clef primaire. La table AmericaCupClass est jointe avec Boat en utilisant la condition de jointure Boat.id = AmericaCupClass.BOAT_ID.

Il est parfois utile de partager des propriétés communes à travers une classe technique ou métier sans l'inclure comme une entité habituelle (c'est-à-dire aucune table spécifique pour cette entité). Pour cela, vous pouvez les mapper comme @MappedSuperclass.

@MappedSuperclass
public class BaseEntity {
    @Basic
    @Temporal(TemporalType.TIMESTAMP)
    public Date getLastUpdate() { ... }
    public String getLastUpdater() { ... }
    ...
}

@Entity class Order extends BaseEntity {
    @Id public Integer getId() { ... }
    ...
}

En base de données, cette hiérarchie sera représentée comme une table Order ayant les colonnes id, lastUpdate et lastUpdater. Les mappings de propriété de la classe parente embarquée sont copiés dans les classes filles de l'entité. Souvenez-vous que la classe parente embarquable n'est cependant pas la racine de la hiérarchie.

Vous pouvez surcharger des colonnes définies dans des entités parentes au niveau de l'entité racine en utilisant l'annotation @AttributeOverride.

@MappedSuperclass
public class FlyingObject implements Serializable {

    public int getAltitude() {
        return altitude;
    }

    @Transient
    public int getMetricAltitude() {
        return metricAltitude;
    }

    @ManyToOne
    public PropulsionType getPropulsion() {
        return metricAltitude;
    }
    ...
}

@Entity
@AttributeOverride( name="altitude", column = @Column(name="fld_altitude") )
@AssociationOverride( name="propulsion", joinColumns = @JoinColumn(name="fld_propulsion_fk") )
public class Plane extends FlyingObject {
    ...
}

La propriété altitude sera persistée dans la colonne fld_altitude de la table Plane et l'association propulsion sera matérialisée dans la colonne de clef étrangère fld_propulsion_fk.

Vous pouvez définir @AttributeOverride(s) et @AssociationOverride(s) sur des classes @Entity, des classes @MappedSuperclass et des propriétés pointant vers un objet @Embeddable.

Vous pouvez associer des entity beans avec une relation one-to-one en utilisant @OneToOne. Il y a trois cas pour les associations one-to-one : soit les entités associées partagent les mêmes valeurs de clef primaire, soit une clef étrangère est détenue par une des entités (notez que cette colonne de clef étrangère dans la base de données devrait être avoir une contrainte d'unicité pour simuler la cardinalité one-to-one), soit une table d'association est utilisée pour stocker le lien entre les 2 entités (une contrainte d'unicité doit être définie sur chaque clef étrangère pour assurer la cardinalité un à un).

Tout d'abord, nous mappons une véritable association one-to-one en utilisant des clefs primaires partagées :

@Entity
public class Body {
    @Id
    public Long getId() { return id; }

    @OneToOne(cascade = CascadeType.ALL)
    @PrimaryKeyJoinColumn
    public Heart getHeart() {
        return heart;
    }
    ...
}
            

@Entity
public class Heart {
    @Id
    public Long getId() { ...}
}
            

L'association un à un est activée en utilisant l'annotation @PrimaryKeyJoinColumn.

Dans l'exemple suivant, les entités associées sont liées à travers une clef étrangère :

@Entity
public class Customer implements Serializable {
    @OneToOne(cascade = CascadeType.ALL)
    @JoinColumn(name="passport_fk")
    public Passport getPassport() {
        ...
    }

@Entity
public class Passport implements Serializable {
    @OneToOne(mappedBy = "passport")
    public Customer getOwner() {
    ...
}
            

Un Customer est lié à un Passport, avec une colonne de clef étrangère nommée passport_fk dans la table Customer. La colonne de jointure est déclarée avec l'annotation @JoinColumn qui ressemble à l'annotation @Column. Elle a un paramètre de plus nommé referencedColumnName. Ce paramètre déclare la colonne dans l'entité cible qui sera utilisée pour la jointure. Notez que lors de l'utilisation de referencedColumnName vers une colonne qui ne fait pas partie de la clef primaire, la classe associée doit être Serializable. Notez aussi que referencedColumnName doit être mappé sur une propriété ayant une seule colonne lorsqu'elle pointe vers une colonne qui ne fait pas partie de la clef primaire (d'autres cas pourraient ne pas fonctionnner).

L'association peut être bidirectionnelle. Dans une relation bidirectionnelle, une des extrémités (et seulement une) doit être la propriétaire : la propriétaire est responsable de la mise à jour des colonnes de l'association. Pour déclarer une extrémité comme non responsable de la relation, l'attribut mappedBy est utilisé. mappedBy référence le nom de la propriété de l'association du côté du propriétaire. Dans notre cas, c'est passport. Comme vous pouvez le voir, vous ne devez (absolument) pas déclarer la colonne de jointure puisqu'elle a déjà été déclarée du côté du propriétaire.

Si aucune @JoinColumn n'est déclarée du côté du propriétaire, les valeurs par défaut s'appliquent. Une(des) colonne(s) de jointure sera(ont) créée(s) dans la table propriétaire, et son(leur) nom sera la concaténation du nom de la relation du côté propriétaire, _ (underscore), et le nom de la (des) colonne(s) de la clef primaire du propriétaire. Dans cet exemple passport_id parce que le nom de la propriété est passport et la colonne identifiante de Passport est id.

La troisième possibilité (utilisant une table d'association) est très exotique.

@Entity
public class Customer implements Serializable {
    @OneToOne(cascade = CascadeType.ALL)
    @JoinTable(name = "CustomerPassports",
        joinColumns = @JoinColumn(name="customer_fk"),
        inverseJoinColumns = @JoinColumn(name="passport_fk")
    )
    public Passport getPassport() {
        ...
    }

@Entity
public class Passport implements Serializable {
    @OneToOne(mappedBy = "passport")
    public Customer getOwner() {
    ...
}
            

Un Customer est lié à un Passport à travers une table d'association nommée CustomerPassports ; cette table d'association a une colonne de clef étrangère nommée passport_fk pointant vers la table Passport (matérialisée par l'attribut inverseJoinColumn), et une colonne de clef étrangère nommée customer_fk pointant vers la table Customer (matérialisée par l'attribut joinColumns).

Vous devez déclarer le nom de la table de jointure et les colonnes de jointure explicitement dans un tel mapping.

Les associations Many-to-one sont déclarées au niveau de la propriété avec l'annotation @ManyToOne :

@Entity()
public class Flight implements Serializable {
    @ManyToOne( cascade = {CascadeType.PERSIST, CascadeType.MERGE} )
    @JoinColumn(name="COMP_ID")
    public Company getCompany() {
        return company;
    }
    ...
}
            

L'attribut @JoinColumn est optionnel, la valeur par défaut est comme l'association un à un, la concaténation du nom de la relation du côté propriétaire, _ (underscore), et le nom de la colonne de la clef primaire du côté propriétaire. Dans cet exemple, company_id parce que le nom de la propriété est company et la colonne identifiante de Company est id.

@ManyToOne a un paramètre nommé targetEntity qui décrit le nom de l'entité cible. Généralement, vous ne devriez pas avoir besoin de ce paramètre puisque la valeur par défaut (le type de la propriété qui stocke l'association) est correcte dans la plupart des cas. Il est cependant utile lorsque vous souhaitez retourner une interface plutôt qu'une entité normale.

@Entity()
public class Flight implements Serializable {
    @ManyToOne( cascade = {CascadeType.PERSIST, CascadeType.MERGE}, targetEntity=CompanyImpl.class )
    @JoinColumn(name="COMP_ID")
    public Company getCompany() {
        return company;
    }
    ...
}

public interface Company {
    ...
            

Vous pouvez sinon mapper une association plusieurs à un avec une table d'association. Cette association décrite par l'annotation @JoinTable contiendra une clef étrangère référençant la table de l'entité (avec @JoinTable.joinColumns) et une clef étrangère référençant la table de l'entité cible (avec @JoinTable.inverseJoinColumns).

@Entity()
public class Flight implements Serializable {
    @ManyToOne( cascade = {CascadeType.PERSIST, CascadeType.MERGE} )
    @JoinTable(name="Flight_Company",
        joinColumns = @JoinColumn(name="FLIGHT_ID"),
        inverseJoinColumns = @JoinColumn(name="COMP_ID")
    )
    public Company getCompany() {
        return company;
    }
    ...
}
            

Vous avez probablement remarqué l'attribut cascade prenant comme valeur un tableau de CascadeTypes. Le concept de cascade dans EJB3 est similaire à la persistance transitive et les opérations en cascade dans Hibernate, mais avec une sémantique légèrement différente et les types de cascade suivants :

Veullez vous référer au chapitre 6.3 de la spécification EJB3 pour plus d'informations sur les opérations en cascade et la sémantique des opérations de création/fusion.

Vous avez la possibilité de récupérer les entités associées soit immédiatement ("eager"), soit à la demande ("lazy"). Le paramètre fetch peut être positionné à FetchType.LAZY ou à FetchType.EAGER. EAGER essaiera d'utiliser une jointure externe pour rappatrier l'objet associé, alors que LAZY est la valeur par défaut et rapportera les données lorsque l'objet associé sera accédé pour la première fois. JPA-QL a aussi un mot clef fetch qui vous permet de surcharger le type de récupération pour une requête particulière. C'est très utile pour améliorer les performances et décider au cas par cas.

Le type d'accès est déduit de la position de @Id ou de @EmbeddedId dans la hiérarchie de l'entité. Les entités filles, les objets embarqués et les entités parentes mappés héritent du type d'accès de l'entité racine.

Dans Hibernate, vous pouvez surcharger le type d'accès pour :

Une annocation @AccessType a été présentée pour prendre en charge ce comportement. Vous pouvez définir le type d'accès sur :