Hibernate Annotations

Chaque classe POJO persistante liée est un entity bean et est déclarée en utilisant l'annotation @Entity (au niveau de la classe) :

@Entity
public class Flight implements Serializable {
    Long id;

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

    public void setId(Long id) { this.id = id; }
}

@Entity déclare la classe comme un entity bean (ie une classe POJO persistante), @Id déclare la propriété identifiante de cet entity bean. Les autres déclarations de mapping sont implicites. Ce concept de déclaration par exception est un composant essentiel de la nouvelle spécification EJB3 et une amélioration majeure. La classe Flight est mappée sur la table Flight, en utilisant la colonne id comme colonne de la clef primaire.

Selon que vous annotez des champs ou des méthodes, le type d'accès utilisé par Hibernate sera field ou property. La spécification EJB3 exige que vous déclariez les annotations sur le type d'élément qui sera accédé, c'est-à-dire le getter si vous utilisez l'accès property, le champ si vous utilisez l'accès field. Mélanger des EJB3 annotations dans les champs et les méthodes devrait être évité. Hibernate devinera le type d'accès de l'identifiant à partir de la position d'@Id ou d'@EmbeddedId.

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

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

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

L'annotation @Id vous permet de définir quelle propriété identifie votre entity bean. Cette propriété peut être positionnée par l'application elle-même ou générée par Hibernate (préféré). Vous pouvez définir la stratégie de génération de l'identifiant grâce à l'annotation @GeneratedValue :

Hibernate fournit plus de générateurs d'identifiant que les simples générateurs EJB3. Vérifiez Extensions d'Hibernate Annotation pour plus d'informations.

L'exemple suivant montre un générateur par séquence utilisant la configuration SEQ_STORE (voir plus bas) :

@Id @GeneratedValue(strategy=GenerationType.SEQUENCE, generator="SEQ_STORE")
public Integer getId() { ... }
         

L'exemple suivant utilise le générateur identity :

@Id @GeneratedValue(strategy=GenerationType.IDENTITY)
public Long getId() { ... }
         

Le générateur AUTO est le type préféré pour les applications portables (vers différentes base de données). La configuration de la génération d'identifiant peut être partagée par différents mappings @Id avec l'attribut du générateur. Il y a différentes configurations disponibles avec @SequenceGenerator et @TableGenerator. La portée d'un générateur peut être l'application ou la classe. Les générateurs définis dans les classes ne sont pas visibles à l'extérieur de la classe et peuvent surcharger les générateurs de niveau applicatif. Les générateurs de niveau applicatif sont définis au niveau XML (voir Chapitre 3, Surcharger des méta-données à travers du XML) :

<table-generator name="EMP_GEN"
            table="GENERATOR_TABLE"
            pk-column-name="key"
            value-column-name="hi"
            pk-column-value="EMP"
            allocation-size="20"/>

// et l'annotation équivalente

@javax.persistence.TableGenerator(
    name="EMP_GEN",
    table="GENERATOR_TABLE",
    pkColumnName = "key",
    valueColumnName = "hi"
    pkColumnValue="EMP",
    allocationSize=20
)

<sequence-generator name="SEQ_GEN"
    sequence-name="my_sequence"
    allocation-size="20"/>

// et l'annotation équivalente

@javax.persistence.SequenceGenerator(
    name="SEQ_GEN",
    sequenceName="my_sequence",
    allocationSize=20
)
         

Si JPA XML (comme META-INF/orm.xml) est utilisé pour définir les générateurs, EMP_GEN et SEQ_GEN sont des générateurs de niveau applicatif. EMP_GEN définit un générateur d'identifiant basé sur une table utilisant l'algorithme hilo avec un max_lo de 20. La valeur haute est conservée dans une table "GENERATOR_TABLE". L'information est gardée dans une ligne où la colonne pkColumnName ("clef") est égale à pkColumnValue "EMP" et une colonne valueColumnName "hi" contient la prochaine valeur haute utilisée.

SEQ_GEN définit un générateur par séquence utilisant une séquence nommée my_sequence. La taille d'allocation utilisée pour cet algorithme hilo basé sur une séquence est 20. Notez que cette version d'Hibernate Annotations ne gère pas initialValue dans le générateur par séquence. La taille par défaut de l'allocation est 50, donc si vous voulez utiliser une séquence et récupérer la valeur chaque fois, vous devez positionner la taille de l'allocation à 1.

Le prochain exemple montre la définition d'un générateur par séquence dans la portée d'une classe :

@Entity
@javax.persistence.SequenceGenerator(
    name="SEQ_STORE",
    sequenceName="my_sequence"
)
public class Store implements Serializable {
    private Long id;

    @Id @GeneratedValue(strategy=GenerationType.SEQUENCE, generator="SEQ_STORE")
    public Long getId() { return id; }
}
         

Cette classe utilisera une séquence nommée my_sequence et le générateur SEQ_STORE n'est pas visible dans les autres classes. Notez que vous pouvez regarder les tests unitaires d'Hibernate Annotations dans le package org.hibernate.test.metadata.id pour plus d'exemples.

Vous pouvez définir une clef primaire composée à travers différentes syntaxes :

Bien qu'assez commun pour le développeur EJB2, @IdClass est probablement nouveau pour les utilisateurs d'Hibernate. La classe de la clef primaire composée correspond aux multiples champs ou propriétés de l'entité ; de plus, les noms des champs ou propriétés de la clef primaire et ceux de l'entité doivent correspondre ; et enfin, leur type doit être le même. Regardons un exemple :

@Entity
@IdClass(FootballerPk.class)
public class Footballer {
    // partie de la clef
    @Id public String getFirstname() {
        return firstname;
    }

    public void setFirstname(String firstname) {
        this.firstname = firstname;
    }

    // partie de la clef
    @Id public String getLastname() {
        return lastname;
    }

    public void setLastname(String lastname) {
        this.lastname = lastname;
    }

    public String getClub() {
        return club;
    }

    public void setClub(String club) {
        this.club = club;
    }

    // implémentation appropriée de equals() et hashCode()
}

@Embeddable
public class FootballerPk implements Serializable {
    // même nom et même type que dans Footballer
    public String getFirstname() {
        return firstname;
    }

    public void setFirstname(String firstname) {
        this.firstname = firstname;
    }

    // même nom et même type que dans Footballer
    public String getLastname() {
        return lastname;
    }

    public void setLastname(String lastname) {
        this.lastname = lastname;
    }

    // implémentation appropriée de equals() et hashCode()
}

Comme vous pouvez le voir, @IdClass pointe vers la classe de la clef primaire correspondante.

Bien que ce ne soit pas pris en charge par la spécification EJB3, Hibernate vous permet de définir des associations à l'intérieur d'un identifiant composé. Pour cela, utilisez simplement les annotations habituelles.

@Entity
@AssociationOverride( name="id.channel", joinColumns = @JoinColumn(name="chan_id") )
public class TvMagazin {
    @EmbeddedId public TvMagazinPk id;
    @Temporal(TemporalType.TIME) Date time;
}

@Embeddable
public class TvMagazinPk implements Serializable {
    @ManyToOne
    public Channel channel;
    public String name;
    @ManyToOne
    public Presenter presenter;
}

EJB3 prend en charge les trois types d'héritage :

La stratégie choisie est déclarée au niveau de la classe de l'entité la plus haute dans la hiérarhie en utilisant l'annotation @Inheritance.

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

@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 { ... }
            

@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 { ... }
            

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

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

@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 {
    ...
}

Les clefs primaires composées utilisent une classe embarquée comme représentation de la clef primaire, donc vous devriez utiliser les annotations @Id et @Embeddable. Alternativement, vous pouvez utiliser l'annotation @EmbeddedId. Notez que la classe dépendante doit être sérialisable et implementer equals()/hashCode(). Vous pouvez aussi utiliser @IdClass comme décrit dans Mapper des propriétés identifiantes.

@Entity
public class RegionalArticle implements Serializable {

    @Id
    public RegionalArticlePk getPk() { ... }
}

@Embeddable
public class RegionalArticlePk implements Serializable { ... }
         

ou alternativement

@Entity
public class RegionalArticle implements Serializable {

    @EmbeddedId
    public RegionalArticlePk getPk() { ... }
}

public class RegionalArticlePk implements Serializable { ... }
         

@Embeddable hérite le type d'accès de son entité d'appartenance à moins que l'annotation spécifique Hibernate @AccessType soit utilisée. Les clefs étrangères composées (si les valeurs par défaut ne sont pas utilisées) sont définies sur les associations en utilisant l'élément @JoinColumns, lequel est simplement un tableau de @JoinColumns. Il est considéré comme une bonne pratique d'exprimer referencedColumnNames explicitement. Sinon, Hibernate supposera que vous utilisez le même ordre de colonnes que dans la déclaration de la clef primaire.

@Entity
public class Parent implements Serializable {
    @Id
    public ParentPk id;
    public int age;

    @OneToMany(cascade=CascadeType.ALL)
    @JoinColumns ({
        @JoinColumn(name="parentCivility", referencedColumnName = "isMale"),
        @JoinColumn(name="parentLastName", referencedColumnName = "lastName"),
        @JoinColumn(name="parentFirstName", referencedColumnName = "firstName")
    })
    public Set<Child> children; //unidirectionnelle
    ...
}
         

@Entity
public class Child implements Serializable {
    @Id @GeneratedValue
    public Integer id;

    @ManyToOne
    @JoinColumns ({
        @JoinColumn(name="parentCivility", referencedColumnName = "isMale"),
        @JoinColumn(name="parentLastName", referencedColumnName = "lastName"),
        @JoinColumn(name="parentFirstName", referencedColumnName = "firstName")
    })
    public Parent parent; // unidirectionnelle
}
         

@Embeddable
public class ParentPk implements Serializable {
    String firstName;
    String lastName;
    ...
}
         

Notez l'usage explicite de referencedColumnName.

Vous pouvez mapper un simple entity bean vers plusieurs tables en utilisant les annotations de niveau classe @SecondaryTable ou @SecondaryTables. Pour dire qu'une colonne est dans une table particulière, utlisez le paramètre table de @Column ou @JoinColumn.

@Entity
@Table(name="MainCat")
@SecondaryTables({
    @SecondaryTable(name="Cat1", pkJoinColumns={
        @PrimaryKeyJoinColumn(name="cat_id", referencedColumnName="id")
    ),
    @SecondaryTable(name="Cat2", uniqueConstraints={@UniqueConstraint(columnNames={"storyPart2"})})
})
public class Cat implements Serializable {

    private Integer id;
    private String name;
    private String storyPart1;
    private String storyPart2;

    @Id @GeneratedValue
    public Integer getId() {
        return id;
    }

    public String getName() {
        return name;
    }

    @Column(table="Cat1")
    public String getStoryPart1() {
        return storyPart1;
    }

    @Column(table="Cat2")
    public String getStoryPart2() {
        return storyPart2;
    }

Dans cet exemple, name sera dans MainCat. storyPart1 sera dans Cat1 et storyPart2 sera dans Cat2. Cat1 sera joint à MainCat avec cat_id comme clef étrangère, et Cat2 avec id (ie le même nom de colonne que la colonne identifiante de MainCat). De plus, une contrainte d'unicité sur storyPart2 a été renseignée.

Regardez le tutoriel EJB3 de JBoss ou la suite de tests unitaires d'Hibernate Annotations pour plus d'exemples.

Vous pouvez mapper des requêtes JPA-QL/HQL en utilisant les annotations. @NamedQuery et @NamedQueries peuvent être définies au niveau de la classe ou dans un fichier JPA XML. Cependant, leurs définitions sont globales au scope de la session factory/entity manager factory. Une requête nommée est définie par son nom et la chaîne de caractères de la requête réelle.

<entity-mappings>
    <named-query name="plane.getAll">
        <query>select p from Plane p</query>
    </named-query>
    ...
</entity-mappings>
...

@Entity
@NamedQuery(name="night.moreRecentThan", query="select n from Night n where n.date >= :date")
public class Night {
    ...
}

public class MyDao {
    doStuff() {
        Query q = s.getNamedQuery("night.moreRecentThan");
        q.setDate( "date", aMonthAgo );
        List results = q.list();
        ...
    }
    ...
}
        

Vous pouvez aussi fournir des indications de fonctionnement à une requête à travers un tableau de QueryHints avec l'attribut hints.

Les indications de fonctionnement Hibernate disponibles sont :

Vous pouvez aussi mapper une requête native (ie une requête SQL). Pour ce faire, vous devez décrire la structure de l'ensemble de résultat SQL en utilisant @SqlResultSetMapping (ou @SqlResultSetMappings si vous prévoyez de définir plusieurs mappings de résultats). Comme @NamedQuery, un @SqlResultSetMapping peut être défini au niveau de la classe ou dans un fichier XML JPA. Cependant sa portée est globale à l'application.

Comme vous le verrez, un paramètre de resultSetMapping est défini dans @NamedNativeQuery, il représente le nom du @SqlResultSetMapping défini. Le mapping de l'ensemble des résultats déclare les entités récupérées par cette requête native. Chaque champ de l'entité est lié à un alias SQL (nom de colonne). Tous les champs de l'entité (dont ceux des classes filles) et les colonnes des clefs étrangères relatives aux entités doivent être présents dans la requête SQL. Les définitions des champs sont optionnelles, si elles ne sont pas fournies, elles mappent le même nom de colonne que celui déclaré sur la propriété de la classe.

@NamedNativeQuery(name="night&area", query="select night.id nid, night.night_duration, "
    + " night.night_date, area.id aid, night.area_id, area.name "
    + "from Night night, Area area where night.area_id = area.id", resultSetMapping="joinMapping")
@SqlResultSetMapping(name="joinMapping", entities={
    @EntityResult(entityClass=org.hibernate.test.annotations.query.Night.class, fields = {
        @FieldResult(name="id", column="nid"),
        @FieldResult(name="duration", column="night_duration"),
        @FieldResult(name="date", column="night_date"),
        @FieldResult(name="area", column="area_id"),
        discriminatorColumn="disc"
    }),
    @EntityResult(entityClass=org.hibernate.test.annotations.query.Area.class, fields = {
        @FieldResult(name="id", column="aid"),
        @FieldResult(name="name", column="name")
    })
    }
)

Dans l'exemple ci-dessus, la requête nommée night&area utilise le mapping de résultats joinMapping. Ce mapping retourne 2 entités, Night et Area, chaque propriété est déclarée et associée à un nom de colonne, en fait le nom de colonne récupéré par la requête. Voyons maintenant une déclaration implicite de mapping propriété/colonne.

@Entity
@SqlResultSetMapping(name="implicit", entities=@EntityResult(entityClass=org.hibernate.test.annotations.query.SpaceShip.class))
@NamedNativeQuery(name="implicitSample", query="select * from SpaceShip", resultSetMapping="implicit")
public class SpaceShip {
    private String name;
    private String model;
    private double speed;

    @Id
    public String getName() {
        return name;
    }

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

    @Column(name="model_txt")
    public String getModel() {
        return model;
    }

    public void setModel(String model) {
        this.model = model;
    }

    public double getSpeed() {
        return speed;
    }

    public void setSpeed(double speed) {
        this.speed = speed;
    }
}

Dans cet exemple, nous décrivons seulement le membre de l'entité du mapping de résultats. Le mapping de propriété/colonne est fait en utilisant les valeurs de mapping de l'entité. Dans ce cas, la propriété model est liée à la colonne model_txt. Si l'association à une entité concernée implique une clef primaire composée, un élément @FieldResult devrait être utilisé pour chaque colonne de la clef étrangère. Le nom de @FieldResult est composé du nom de la propriété pour la relation, suivi par un point ("."), suivi par le nom ou le champ ou la propriété de la clef primaire.

@Entity
@SqlResultSetMapping(name="compositekey",
        entities=@EntityResult(entityClass=org.hibernate.test.annotations.query.SpaceShip.class,
            fields = {
                    @FieldResult(name="name", column = "name"),
                    @FieldResult(name="model", column = "model"),
                    @FieldResult(name="speed", column = "speed"),
                    @FieldResult(name="captain.firstname", column = "firstn"),
                    @FieldResult(name="captain.lastname", column = "lastn"),
                    @FieldResult(name="dimensions.length", column = "length"),
                    @FieldResult(name="dimensions.width", column = "width")
                    }),
        columns = { @ColumnResult(name = "surface"),
                    @ColumnResult(name = "volume") } )

@NamedNativeQuery(name="compositekey",
    query="select name, model, speed, lname as lastn, fname as firstn, length, width, length * width as surface from SpaceShip",
    resultSetMapping="compositekey")
} )
public class SpaceShip {
    private String name;
    private String model;
    private double speed;
    private Captain captain;
    private Dimensions dimensions;

    @Id
    public String getName() {
        return name;
    }

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

    @ManyToOne(fetch= FetchType.LAZY)
    @JoinColumns( {
            @JoinColumn(name="fname", referencedColumnName = "firstname"),
            @JoinColumn(name="lname", referencedColumnName = "lastname")
            } )
    public Captain getCaptain() {
        return captain;
    }

    public void setCaptain(Captain captain) {
        this.captain = captain;
    }

    public String getModel() {
        return model;
    }

    public void setModel(String model) {
        this.model = model;
    }

    public double getSpeed() {
        return speed;
    }

    public void setSpeed(double speed) {
        this.speed = speed;
    }

    public Dimensions getDimensions() {
        return dimensions;
    }

    public void setDimensions(Dimensions dimensions) {
        this.dimensions = dimensions;
    }
}

@Entity
@IdClass(Identity.class)
public class Captain implements Serializable {
    private String firstname;
    private String lastname;

    @Id
    public String getFirstname() {
        return firstname;
    }

    public void setFirstname(String firstname) {
        this.firstname = firstname;
    }

    @Id
    public String getLastname() {
        return lastname;
    }

    public void setLastname(String lastname) {
        this.lastname = lastname;
    }
}

Si vous récupérez une simple entité et si vous utilisez le mapping par défaut, vous pouvez utiliser l'attribut resultClass à la place de resultSetMapping :

@NamedNativeQuery(name="implicitSample", query="select * from SpaceShip",
    resultClass=SpaceShip.class)
public class SpaceShip {

Dans certaines de vos requêtes natives, vous devrez retourner des valeurs scalaires, par exemple lors de la construction de requêtes de rapport. Vous pouvez les mapper dans @SqlResultsetMapping avec @ColumnResult. En fait, vous pouvez même mélanger des retours d'entités et de valeurs scalaires dans la même requête native (ce n'est cependant probablement pas commun).

@SqlResultSetMapping(name="scalar", columns=@ColumnResult(name="dimension"))
@NamedNativeQuery(name="scalar", query="select length*width as dimension from SpaceShip", resultSetMapping="scalar")

Une autre indication de fonctionnement spécifique aux requêtes natives a été présentée : org.hibernate.callable laquelle peut être à true ou à false fausse selon que la requête est une procédure stockée ou pas.

Vous pouvez finement paramétrer certaines des actions faites par Hibernate sur les entités au-delà de ce qu'offre la spécification EJB3.

@org.hibernate.annotations.Entity ajoute des méta-données supplémentaires qui peuvent être nécessaires au-delà de ce qui est défini dans l'annotation @Entity standard :

Voici quelques extensions d'annotations Hibernate supplémentaires.

@org.hibernate.annotations.BatchSize vous permet de définir la taille du batch lors de la récupération d'instances de cette entité (p. ex. @BatchSize(size=4)). Lors du chargement d'une entité donnée, Hibernate chargera alors toutes les entités non initialisées du même type dans le contexte de la persistance jusqu'à la taille du batch.

@org.hibernate.annotations.Proxy définit les attributs de chargement de l'entité. lazy (valeur par défaut) définit si la classe est chargée à la demande ou non. proxyClassName est l'interface utilisée pour générer le proxy (par défaut, la classe elle-même).

@org.hibernate.annotations.Where définit une clause WHERE SQL optionnelle utilisée lorsque des instances de cette classe sont récupérées.

@org.hibernate.annotations.Check déclare une contrainte de vérification optionnelle définie dans l'expression DDL.

@OnDelete(action=OnDeleteAction.CASCADE) sur des classes filles jointes : utilise une commande SQL DELETE en cascade lors de la suppression plutôt que le mécanisme habituel d'Hibernate.

@Table(appliesTo="tableName", indexes = { @Index(name="index1", columnNames={"column1", "column2"} ) } ) crée les index définis sur les colonnes de la table tableName. Cela peut s'appliquer sur une table primaire ou une table secondaire. L'annotation @Tables vous permet d'avoir des index sur des tables différentes. Cette annotation est attendue là où @javax.persistence.Table ou @javax.persistence.SecondaryTable(s) sont déclarées.

@Entity
@BatchSize(size=5)
@org.hibernate.annotations.Entity(
        selectBeforeUpdate = true,
        dynamicInsert = true, dynamicUpdate = true,
        optimisticLock = OptimisticLockType.ALL,
        polymorphism = PolymorphismType.EXPLICIT)
@Where(clause="1=1")
@org.hibernate.annotations.Table(name="Forest", indexes = { @Index(name="idx", columnNames = { "name", "length" } ) } )
public class Forest { ... }

@Entity
@Inheritance(
    strategy=InheritanceType.JOINED
)
public class Vegetable { ... }

@Entity
@OnDelete(action=OnDeleteAction.CASCADE)
public class Carrot extends Vegetable { ... }

@org.hibernate.annotations.GenericGenerator vous permet de définir un générateur d'identifiants Hibernate spécifique.

@Id @GeneratedValue(generator="system-uuid")
@GenericGenerator(name="system-uuid", strategy = "uuid")
public String getId() {

@Id @GeneratedValue(generator="hibseq")
@GenericGenerator(name="hibseq", strategy = "seqhilo",
    parameters = {
        @Parameter(name="max_lo", value = "5"),
        @Parameter(name="sequence", value="heybabyhey")
    }
)
public Integer getId() {

strategy est le nom court de la stratégie du générateur Hibernate3 ou le nom pleinement qualifié de la classe d'une implémentation de IdentifierGenerator. Vous pouvez ajouter des paramètres avec l'attribut parameters.

Contrairement à son pendant standard, @GenericGenerator peut ête utilisée dans les annotations au niveau du package, en faisant ainsi un générateur de niveau applicatif (comme s'il était dans un fichier JPA XML).

@GenericGenerator(name="hibseq", strategy = "seqhilo",
    parameters = {
        @Parameter(name="max_lo", value = "5"),
        @Parameter(name="sequence", value="heybabyhey")
    }
)
package org.hibernate.test.model

SINGLE_TABLE est une stratégie très puissante mais parfois, et surtout pour des systèmes pré-existants, vous ne pouvez pas ajouter une colonne discriminante supplémentaire. Pour cela Hibernate a mis en place la notion de formule discriminante : @DiscriminatorFormula est une remplaçcant de @DiscriminatorColumn et utilise un fragment SQL en tant que formule pour la résolution du discriminant (pas besoin d'avoir une colonne dédiée).

@Entity
@DiscriminatorForumla("case when forest_type is null then 0 else forest_type end")
public class Forest { ... }

Par défaut, lors du requêtage sur les entités les plus hautes, Hibernate ne met pas de restriction sur la colonne discriminante. Ceci peut être un inconvénient si cette colonne contient des valeurs qui ne sont pas mappées dans votre hiérarchie (avec @DiscriminatorValue). Pour contourner ca, vous pouvez utilser @ForceDiscriminator (au niveau de la classe, à côté de @DiscriminatorColumn). Hibernate listera alors les valeurs disponibles lors du chargement des entités.

Par défaut, lorsqu'Hibernate ne peut pas résoudre l'association parce que l'élément associé attendu n'est pas dans la base de données (mauvais identifiant sur la colonne de l'association), une exception est levée par Hibernate. Cela pourrait être un inconvénient pour des schémas pré-existants et mal maintenus. Vous pouvez demander à Hibernate d'ignorer de tels éléments plutôt que de lever une exception en utilisant l'annotation @NotFound. Cette annotation peut être utilisée sur une association @OneToOne (avec une clef étrangère), @ManyToOne, @OneToMany ou @ManyToMany.

@Entity
public class Child {
    ...
    @ManyToOne
    @NotFound(action=NotFoundAction.IGNORE)
    public Parent getParent() { ... }
    ...
}

Parfois vous voulez déléguer à votre base de données la suppression en cascade lorsqu'une entité donnée est supprimée.

@Entity
public class Child {
    ...
    @ManyToOne
    @OnDelete(action=OnDeleteAction.CASCADE)
    public Parent getParent() { ... }
    ...
}

Dans ce cas, Hibernate génère une contrainte de suppression en cascade au niveau de la base de données.

Les contraintes de clef étrangère, bien que générées par Hibernate, ont un nom justement illisible. Vous pouvez surcharger le nom de la contrainte par l'utilisation de @ForeignKey.

@Entity
public class Child {
    ...
    @ManyToOne
    @ForeignKey(name="FK_PARENT")
    public Parent getParent() { ... }
    ...
}

alter table Child add constraint FK_PARENT foreign key (parent_id) references Parent

Pour optimiser vos accès à la base de données, vous pouvez activer le cache de second niveau d'Hibernate. Ce cache est configurable par entité et par collection.

@org.hibernate.annotations.Cache définit la stratégie de cache et la région du cache de second niveau donné. Cette annotation peut être appliquée à une entité racine (pas les entités filles), et sur les collections.

@Entity
@Cache(usage = CacheConcurrencyStrategy.NONSTRICT_READ_WRITE)
public class Forest { ... }

    @OneToMany(cascade=CascadeType.ALL, fetch=FetchType.EAGER)
    @JoinColumn(name="CUST_ID")
    @Cache(usage = CacheConcurrencyStrategy.NONSTRICT_READ_WRITE)
    public SortedSet<Ticket> getTickets() {
        return tickets;
    }

@Cache(
    CacheConcurrencyStrategy usage();                 (1)
    String region() default "";                       (2)
    String include() default "all";                   (3)
)

Hibernate a la capacité d'appliquer des filtres arbitraires à la partie supérieure de vos données. Ces filtres sont appliqués au moment de l'exécution sur une session donnée. Vous avez tout d'abord besoin de les définir.

@org.hibernate.annotations.FilterDef ou @FilterDefs déclarent des définitions de filtre utilisées par les filtres ayant le même nom. Une définition de filtre a un name() et un tableau de parameters(). Un paramètre vous permettra d'ajuster le comportement du filtre au moment de l'exécution. Chaque paramètre est défini par une @ParamDef qui a un nom et un type. Vous pouvez aussi définir un paramètre defaultCondition() pour une @ParamDef donnée pour positionner la condition par défaut à utiliser lorsqu'aucune n'est définie dans chaque @Filter individuelle. Une @FilterDef peut être définie au niveau de la classe ou du package.

Nous avons besoin de définir la clause du filtre SQL appliqué au chargement de l'entité ou au chargement de la collection. @Filter est utilisée et placée sur l'entité ou l'élément de la collection.

@Entity
@FilterDef(name="minLength", parameters=@ParamDef( name="minLength", type="integer" ) )
@Filters( {
    @Filter(name="betweenLength", condition=":minLength <= length and :maxLength >= length"),
    @Filter(name="minLength", condition=":minLength <= length")
} )
public class Forest { ... }

Lorsque la collection utilise une table d'association comme représentation relationnelle, vous pourriez vouloir appliquer la condition du filtre à la table de l'association elle-même ou à la table de l'entité cible. Pour appliquer la contrainte sur l'entité cible, utilisez l'annotation habituelle @Filter. Cependant, si vous voulez ciblez la table d'association, utilisez l'annotation @FilterJoinTable.

    @OneToMany
    @JoinTable
    // filtre sur la table de l'entité cible
    @Filter(name="betweenLength", condition=":minLength <= length and :maxLength >= length")
    // filtre sur la table d'association
    @FilterJoinTable(name="security", condition=":userlevel >= requredLevel")
    public Set<Forest> getForests() { ... }

Puisqu'Hibernate a plus de fonctionnalités sur les requêtes nommées que définies dans la spécification EJB3, @org.hibernate.annotations.NamedQuery, @org.hibernate.annotations.NamedQueries, @org.hibernate.annotations.NamedNativeQuery et @org.hibernate.annotations.NamedNativeQueries ont été mis en place. Elles ajoutent des attributs à la version standard et peuvent être utilisées comme remplaçant :

Ces indications de fonctionnement peuvent être positionnées sur les annotations standards @javax.persistence.NamedQuery avec l'annotation @QueryHint. Un autre avantage clef est la possibilité de positionner ces annotations au niveau du package.

Une contrainte est représentée par une annotation. Une contrainte a généralement des attributs utilisés pour paramétrer les limites des contraintes. La contrainte s'applique à l'élément annoté.

Hibernate Validator arrive avec des contraintes intégrées, lesquelles couvrent la plupart des vérifications de données de base. Comme nous le verrons plus tard, vous n'êtes pas limité à celles-ci, vous pouvez écrire vos propres contraintes en une minute.

Hibernate Validator arrive avec un ensemble de messages d'erreur par défaut traduits dans environ dix langues (si la vôtre n'en fait pas partie, veuillez nous envoyer un patch). Vous pouvez surcharger ces messages en créant un ValidatorMessages.properties (ou ValidatorMessages_loc.properties) et en surchargeant les clefs dont vous avez besoin. Vous pouvez même ajouter votre propre ensemble de messages supplémentaire lorsque vous écrivez vos annotations de validation. Si Hibernate Validator ne peut pas trouver une clef à partir de votre resourceBundle ou de votre ValidatorMessage, il se repliera sur les valeurs intégrées par défaut.

Alternativement vous pouvez fournir un ResourceBundle pendant la vérification par programmation des règles de validation sur un bean, ou si vous voulez un mécanisme d'interpolation complètement différent, vous pouvez fournir une implémentation de org.hibernate.validator.MessageInterpolator (lisez la JavaDoc pour plus d'informations).

Etendre l'ensemble de contraintes intégrées est extrêment facile. N'importe quelle contrainte est constituée deux morceaux : le descripteur de contrainte (l'annotation) et le validateur de contrainte (la classe d'implémentation). Voici un simple descripteur personnalisé :

@ValidatorClass(CapitalizedValidator.class)
@Target(METHOD)
@Retention(RUNTIME)
@Documented
public @interface Capitalized {
    CapitalizeType type() default Capitalize.FIRST;
    String message() default "has incorrect capitalization";
}

type est un paramètre décrivant comment la propriété devrait être mise en majuscule. Ceci est un paramètre utilisateur complètement dépendant du fonctionnement de l'annotation.

message est la chaîne de caractères par défaut utilisée pour décrire la violation de contrainte et est obligatoire. Vous pouvez mettre la chaîne de caractères dans le code ou bien l'externaliser en partie ou complètement avec le mécanisme ResourceBundle Java. Les valeurs des paramètres sont injectées à l'intérieur du message quand la chaîne de caractères {parameter} est trouvée (dans notre exemple Capitalization is not {type} générerait Capitalization is not FIRST), externaliser toute la chaîne dans ValidatorMessages.properties est considéré comme une bonne pratique. Voir Messages d'erreur.

@ValidatorClass(CapitalizedValidator.class)
@Target(METHOD)
@Retention(RUNTIME)
@Documented
public @interface Capitalized {
    CapitalizeType type() default Capitalize.FIRST;
    String message() default "{validator.capitalized}";
}

...
#in ValidatorMessages.properties
validator.capitalized=Capitalization is not {type}

Comme vous pouvez le voir la notation {} est récursive.

Pour lier un descripteur à l'implémentation de son validateur, nous utilisons la méta-annotation @ValidatorClass. Le paramètre de la classe du validateur doit nommer une classe qui implémente Validator<ConstraintAnnotation>.

Nous devons maintenant implémenter le validateur (ie l'implémentation vérifiant la règle). Une implémentation de validation peut vérifier la valeur d'une propriété (en implémentant PropertyConstraint) et/ou peut modifier les méta-données de mapping d'Hibernate pour exprimer la contrainte au niveau de la base de données (en implémentant PersistentClassConstraint).

public class CapitalizedValidator
        implements Validator<Capitalized>, PropertyConstraint {
    private CapitalizeType type;

    // partie du contrat de Validator<Annotation>,
    // permet d'obtenir et d'utiliser les valeurs de l'annotation
    public void initialize(Capitalized parameters) {
        type = parameters.type();
    }

    // partie du contrat de la contrainte de la propriété
    public boolean isValid(Object value) {
        if (value==null) return true;
        if ( !(value instanceof String) ) return false;
        String string = (String) value;
        if (type == CapitalizeType.ALL) {
            return string.equals( string.toUpperCase() );
        }
        else {
            String first = string.substring(0,1);
            return first.equals( first.toUpperCase();
        }
    }
}

La méthode isValid() devrait retourner false si la contrainte a été violée. Pour plus d'exemples, référez-vous aux implémentations intégrées du validateur.

Nous avons seulement vu la validation au niveau propriété, mais vous pouvez écrire une annotation de validation au niveau d'un bean. Plutôt que de recevoir l'instance de retour d'une propriété, le bean lui-même sera passé au validateur. Pour activer la vérification de validation, annotez juste le bean lui-même. Un petit exemple peut être trouvé dans la suite de tests unitaires.

Maintenant que vous vous êtes familiarisés avec les annotations, la syntaxe devrait être connue.

public class Address {
    private String line1;
    private String line2;
    private String zip;
    private String state;
    private String country;
    private long id;

    // une chaîne non nulle de 20 caractères maximum
    @Length(max=20)
    @NotNull
    public String getCountry() {
        return country;
    }

    // une chaîne de caractères non nulle
    @NotNull
    public String getLine1() {
        return line1;
    }

    // pas de contrainte
    public String getLine2() {
        return line2;
    }

    // une chaîne non nulle de 3 caractères maximum
    @Length(max=3) @NotNull
    public String getState() {
        return state;
    }

    // une chaîne non nulle de 5 caractères maximum représentant un nombre
    // si la chaîne de caractères est plus longue, le message sera recherché
    // dans le resource bundle avec la clef 'long'
    @Length(max=5, message="{long}")
    @Pattern(regex="[0-9]+")
    @NotNull
    public String getZip() {
        return zip;
    }

    // devrait toujours être vrai
    @AssertTrue
    public boolean isValid() {
        return true;
    }

    // un nombre entre 1 et 2000
    @Id @Min(1)
    @Range(max=2000)
    public long getId() {
        return id;
    }
}

Bien que l'exemple montre seulement la validation de propriétés publiques, vous pouvez aussi annoter des champs avec n'importe quelle visibilité.

@MyBeanConstraint(max=45)
public class Dog {
    @AssertTrue private boolean isMale;
    @NotNull protected String getName() { ... };
    ...
}

Vous pouvez aussi annoter des inferfaces. Hibernate Validator vérifiera toutes les classes parentes et les interfaces héritées ou implémentées par un bean donné pour lire les annotations appropriées du validateur.

public interface Named {
    @NotNull String getName();
    ...
}

public class Dog implements Named {

    @AssertTrue private boolean isMale;

    public String getName() { ... };

}

La propriété "name" sera vérifiée pour la nullité lorsque le bean Dog sera validé.

Par défaut, Hibernate Annotations traduira les contraintes que vous avez définies sur vos entités en méta-données de mapping. Par exemple, si une propriété de votre entité est annotée avec @NotNull, ses colonnes seront déclarées comme not null dans le schéma DDL généré par Hibernate.

Hibernate Validator a deux listeners d'événements Hibernate intégrés. Quand un PreInsertEvent ou un PreUpdateEvent survient, les listeners vérifieront toutes les contraintes de l'instance de l'entité et lèveront une exception si une contrainte est violée. Fondamentalement, les objets seront vérifiés avant les insertions et avant les mises à jour effectuées par Hibernate. C'est le plus commode et la manière la plus simple d'activer le processus de validation. Sur une violation de contrainte, l'événement lèvera une exception d'exécution InvalidStateException (NdT : c'est une RuntimeException) laquelle contient un tableau d'InvalidValues décrivant chaque échec.

<hibernate-configuration>
    ...
    <event type="pre-update">
        <listener
          class="org.hibernate.validator.event.ValidatePreUpdateEventListener"/>
    </event>
    <event type="pre-insert">
        <listener
          class="org.hibernate.validator.event.ValidatePreInsertEventListener"/>
    </event>
</hibernate-configuration>

Hibernate Validator peut être utilisé n'importe où dans le code de votre application.

ClassValidator personValidator = new ClassValidator( Person.class );
ClassValidator addressValidator = new ClassValidator( Address.class, ResourceBundle.getBundle("messages", Locale.ENGLISH) );

InvalidValue[] validationMessages = addressValidator.getInvalidValues(address);

Les deux premières lignes préparent Hibernate Validator pour la vérification de classes. La première s'appuie sur les messages d'erreur intégrés à Hibernate Validator (voir Messages d'erreur), la seconde utilise un resource bundle pour ses messages. Il est considéré comme une bonne pratique d'exécuter ces lignes une fois et de cacher les instances de validateur.

La troisième ligne valide en fait l'instance Address et retourne un tableau d'InvalidValues. Votre logique applicative sera alors capable de réagir aux échecs.

Vous pouvez aussi vérifier une propriété particulière plutôt que tout le bean. Ceci pourrait être utile lors d'interactions avec l'utilisateur propriété par propriété.

ClassValidator addressValidator = new ClassValidator( Address.class, ResourceBundle.getBundle("messages", Locale.ENGLISH) );

// récupère seulement les valeurs invalides de la propriété "city"
InvalidValue[] validationMessages = addressValidator.getInvalidValues(address, "city");

// récupère seulement les valeurs potentielles invalides de la propriété "city"
InvalidValue[] validationMessages = addressValidator.getPotentialInvalidValues("city", "Paris")

Comme un transporteur d'informations de validation, Hibernate fournit un tableau d'InvalidValues. Chaque InvalidValue a un groupe de méthodes décrivant les problèmes individuels.

getBeanClass() récupère le type du bean ayant échoué.

getBean() récupère l'instance du bean ayant échoué (s'il y en a, c'est-à-dire pas lors de l'utilisation de getPotentianInvalidValues()).

getValue() récupère la valeur ayant échouée.

getMessage() récupère le message d'erreur internationalisé.

getRootBean() récupère l'instance du bean racine ayant généré le problème (utile en conjonction avec @Valid), est nulle si getPotentianInvalidValues() est utilisée.

getPropertyPath() récupère le chemin (séparé par des points) de la propriété ayant échouée à partir du bean racine.