Hibernate requiert que les champs contenant des collections persistantes soient déclarés comme des types d'interface, par exemple :
public class Product {
private String serialNumber;
private Set parts = new HashSet();
public Set getParts() { return parts; }
void setParts(Set parts) { this.parts = parts; }
public String getSerialNumber() { return serialNumber; }
void setSerialNumber(String sn) { serialNumber = sn; }
}
L'interface réelle peut être java.util.Set, java.util.Collection, java.util.List, java.util.Map, java.util.SortedSet, java.util.SortedMap ou n'importe quoi d'autre ! (Où "n'importe quoi d'autre" signifie que vous devrez écrire une implémentation de org.hibernate.usertype.UserCollectionType.)
Notez comment nous avons initialisé la variable d'instance avec une instance de HashSet. C'est le meilleur moyen pour initialiser les collections d'instances nouvellement créées (non persistantes). Quand nous fabriquons l'instance persistante - en appelant persist(), par exemple - Hibernate remplacera réellement le HashSet par une instance d'une implémentation propre à Hibernate de Set. Prenez garde aux erreurs suivantes :
Cat cat = new DomesticCat();
Cat kitten = new DomesticCat();
....
Set kittens = new HashSet();
kittens.add(kitten);
cat.setKittens(kittens);
session.persist(cat);
kittens = cat.getKittens(); // Okay, kittens collection is a Set
(HashSet) cat.getKittens(); // Error!
Les collections persistantes injectées par Hibernate se comportent de la même manière que HashMap, HashSet, TreeMap, TreeSet ou ArrayList, selon le type de l'interface.
Les instances des collections ont le comportement habituel des types de valeurs. Elles sont automatiquement persistées quand elles sont référencées par un objet persistant et automatiquement effacées quand elles sont déréférencées. Si une collection est passée d'un objet persistant à un autre, ses éléments peuvent être déplacés d'une table à une autre. Deux entités ne peuvent pas partager une référence vers une même instance de collection. Dû au modèle relationnel sous-jacent, les propriétés contenant des collections ne supportent pas la sémantique de la valeur null ; Hibernate ne fait pas de distinction entre une référence de collection nulle et une collection vide.
Ne vous en souciez pas trop. Utilisez les collections persistantes de la même manière que vous utilisez des collections Java ordinaires. Assurez-vous de comprendre la sémantique des associations bidirectionnelles (traitée plus loin).
Astuce
Il y a une grande variété de mappages qui peuvent être générés pour les collections, couvrant beaucoup de nombreux modèles relationnels communs. Nous vous suggérons d'expérimenter avec l'outil de génération de schéma pour cerner comment les différentes déclarations de mappage se traduisent vers des tables de bases de données.
L'élément de mappage d'Hibernate utilisé pour mapper une collection dépend du type de l'interface. Par exemple, un élément <set> est utilisé pour mapper des propriétés de type Set.
<class name="Product">
<id name="serialNumber" column="productSerialNumber"/>
<set name="parts">
<key column="productSerialNumber" not-null="true"/>
<one-to-many class="Part"/>
</set>
</class
>
À part <set>, il y aussi les éléments de mappage <list>, <map>, <bag>, <array> et <primitive-array>. L'élément <map> est représentatif :
<map
name="prop
ertyName"
table="tab
le_name"
schema="sc
hema_name"
lazy="true
|extra|false"
inverse="t
rue|false"
cascade="a
ll|none|save-update|delete|all-delete-orphan|delete-orphan"
sort="unso
rted|natural|comparatorClass"
order-by="
column_name asc|desc"
where="arb
itrary sql where condition"
fetch="joi
n|select|subselect"
batch-size
="N"
access="fi
eld|property|ClassName"
optimistic
-lock="true|false"
mutable="t
rue|false"
node="element-name|."
embed-xml="true|false"
>
<key .... />
<map-key .... />
<element .... />
</map
>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Les instances d'une collection sont distinguées dans la base de données par la clé étrangère de l'entité qui possède la collection. Cette clé étrangère est référencée comme la(es) colonne(s) de la clé de la collection de la table de la collection. La colonne de la clé de la collection est mappée par l'élément <key>.
Il peut y avoir une contrainte de nullité sur la colonne de la clé étrangère. Pour les associations unidirectionnelles un-à-plusieurs, la colonne de la clé étrangère peut être nulle par défaut, donc vous pourriez avoir besoin de spécifier not-null="true".
<key column="productSerialNumber" not-null="true"/>
La contraite de la clé étrangère peut utiliser ON DELETE CASCADE.
<key column="productSerialNumber" on-delete="cascade"/>
Voir le chapitre précédent pour une définition complète de l'élément <key>.
Les collections peuvent contenir la plupart des autres types Hibernate, y compris tous les types basiques, les types utilisateur, les composants, et bien sûr, les références vers d'autres entités. C'est une distinction importante. Un objet dans une collection pourrait être géré avec une sémantique de "valeur" (sa durée de vie dépend complètement du propriétaire de la collection) ou il pourrait avoir une référence vers une autre entité, avec sa propre durée de vie. Dans le dernier cas, seul le "lien" entre les deux objets est considéré être l'état retenu par la collection.
Le type contenu est référencé comme le type de l'élément de la collection. Les éléments de la collections sont mappés par <element> ou <composite-element>, ou dans le cas des références d'entité, avec <one-to-many> ou <many-to-many>. Les deux premiers mappent des éléments avec une sémantique de valeur, les deux suivants sont utilisés pour mapper des associations d'entité.
Tous les mappages de collection, exceptés ceux avec les sémantiques d'ensemble (set) et de sac (bag), ont besoin d'une colonne d'index dans la table de la collection - une colonne qui mappe un index de tableau, ou un index de List, ou une clé de Map. L'index d'une Map peut être n'importe quel type basique, mappé avec <map-key>, ou peut être une référence d'entité mappée avec <map-key-many-to-many>, ou peut être un type composé, mappé avec <composite-map-key>. L'index d'un tableau ou d'une liste est toujours de type integer et est mappé en utilisant l'élément <list-index>. Les colonnes mappées contiennent des entiers séquentiels (numérotés à partir de zéro par défaut).
<list-index
column="column_name"
base="0|1|..."/>
| |
| |
<map-key
column="column_name"
formula="any SQL expression"
type="type_name"
node="@attribute-name"
length="N"/>
| |
| |
| |
<map-key-many-to-many
column="column_name"
formula="any SQL expression"
class="ClassName"
/>
| |
| |
| |
Si votre table n'a pas de colonne d'index, et que vous souhaitez tout de même utiliser List comme type de propriété, vous devriez mapper la propriété comme un <bag> Hibernate. Un sac (bag) ne garde pas son ordre quand il est récupéré de la base de données, mais il peut être optionnellement trié ou ordonné.
Toute collection de valeurs ou association plusieurs-à-plusieurs requiert une table de collection avec une(des) colonne(s) de clé étrangère, une(des) colonne(s) d'élément de la collection ou des colonnes et éventuellement une(des) colonne(s) d'index.
Pour une collection de valeurs, nous utilisons la balise <element>. Par exemple :
<element
column="column_name"
formula="any SQL expression"
type="typename"
length="L"
precision="P"
scale="S"
not-null="true|false"
unique="true|false"
node="element-name"
/>
| |
| |
| |
A many-to-many association is specified using the <many-to-many> element.
<many-to-many
column="column_name"
formula="any SQL expression"
class="ClassName"
fetch="select|join"
unique="true|false"
not-found="ignore|exception"
entity-name="EntityName"
property-ref="propertyNameFromAssociatedClass"
node="element-name"
embed-xml="true|false"
/>
| |
| |
| |
| |
| |
| |
| |
| |
Voici quelques exemples :
Un ensemble de chaînes de caractères :
<set name="names" table="person_names">
<key column="person_id"/>
<element column="person_name" type="string"/>
</set
>
Un sac contenant des entiers (avec un ordre d'itération déterminé par l'attribut order-by) :
<bag name="sizes"
table="item_sizes"
order-by="size asc">
<key column="item_id"/>
<element column="size" type="integer"/>
</bag
>
Un tableau d'entités - dans ce cas, une association plusieurs-à-plusieurs :
<array name="addresses"
table="PersonAddress"
cascade="persist">
<key column="personId"/>
<list-index column="sortOrder"/>
<many-to-many column="addressId" class="Address"/>
</array
>
Une map de chaînes de caractères vers des dates :
<map name="holidays"
table="holidays"
schema="dbo"
order-by="hol_name asc">
<key column="id"/>
<map-key column="hol_name" type="string"/>
<element column="hol_date" type="date"/>
</map
>
Une liste de composants (traité dans le prochain chapitre) :
<list name="carComponents"
table="CarComponents">
<key column="carId"/>
<list-index column="sortOrder"/>
<composite-element class="CarComponent">
<property name="price"/>
<property name="type"/>
<property name="serialNumber" column="serialNum"/>
</composite-element>
</list
>
Une association un-à-plusieurs lie les tables de deux classes par une clé étrangère, sans l'intervention d'une table de collection. Ce mappage perd certaines sémantiques des collections Java normales :
Une instance de la classe de l'entité contenue ne peut pas appartenir à plus d'une instance de la collection.
Une instance de la classe de l'entité contenue peut ne pas apparaître à plus plus d'une valeur d'index de la collection.
Une association de Product vers Part requiert l'existence d'une clé étrangère et éventuellement une colonne d'index pour la table Part. Une balise <one-to-many> indique que c'est une association un-à-plusieurs.
<one-to-many
class="ClassName"
not-found="ignore|exception"
entity-name="EntityName"
node="element-name"
embed-xml="true|false"
/>
|
|
|
|
|
|
Notez que l'élément <one-to-many> n'a pas besoin de déclarer de colonnes. Il n'est pas non plus nécessaire de spécifier le nom de la table à aucun endroit.
Avertissement
Note très importante : si la colonne de la clé d'une association <one-to-many> est déclarée NOT NULL, vous devez déclarer le mappage de <key> avec not-null="true" ou utiliser une association bidirectionnelle avec le mappage de la collection marqué inverse="true". Voir la discussion sur les associations bidirectionnelles plus tard dans ce chapitre.
Cet exemple montre une map d'entités Part par nom (où partName est une propriété persistante de Part). Notez l'utilisation d'un index basé sur une formule :
<map name="parts"
cascade="all">
<key column="productId" not-null="true"/>
<map-key formula="partName"/>
<one-to-many class="Part"/>
</map
>
Hibernate supporte des collections implémentant java.util.SortedMap et java.util.SortedSet. Vous devez spécifier un comparateur dans le fichier de mappage :
<set name="aliases"
table="person_aliases"
sort="natural">
<key column="person"/>
<element column="name" type="string"/>
</set>
<map name="holidays" sort="my.custom.HolidayComparator">
<key column="year_id"/>
<map-key column="hol_name" type="string"/>
<element column="hol_date" type="date"/>
</map
>
Les valeurs permises pour l'attribut sort sont unsorted, natural et le nom d'une classe implémentant java.util.Comparator.
Les collections triées se comportent réellement comme java.util.TreeSet ou java.util.TreeMap.
Si vous voulez que la base de données elle-même ordonne les éléments de la collection, utilisez l'attribut order-by des mappages set, bag ou map. Cette solution est seulement disponible à partir du JDK 1.4 (c'est implémenté en utilisant LinkedHashSet ou LinkedHashMap). Ceci exécute le tri dans la requête SQL, pas en mémoire.
<set name="aliases" table="person_aliases" order-by="lower(name) asc">
<key column="person"/>
<element column="name" type="string"/>
</set>
<map name="holidays" order-by="hol_date, hol_name">
<key column="year_id"/>
<map-key column="hol_name" type="string"/>
<element column="hol_date type="date"/>
</map
>
Note
Notez que la valeur de l'attribut order-by est un ordre SQL, et non pas un ordre HQL.
Les associations peuvent même être triées sur des critères arbitraires à l'exécution en utilisant un filter() de collection :
sortedUsers = s.createFilter( group.getUsers(), "order by this.name" ).list();
Une association bidirectionnelle permet la navigation à partir des deux extrémités de l'association. Deux types d'associations bidirectionnelles sont supportées :
- un-à-plusieurs (one-to-many)
ensemble ou sac à une extrémité, une seule valeur à l'autre
- plusieurs-à-plusieurs
ensemble ou sac aux deux extrémités
Vous pouvez spécifier une association bidirectionnelle plusieurs-à-plusieurs simplement en mappant deux associations plusieurs-à-plusieurs vers la même table de base de données et en déclarant une extrémité comme inverse (celle de votre choix, mais pas une collection indexée).
Voici un exemple d'association bidirectionnelle plusieurs-à-plusieurs ; chaque catégorie peut avoir plusieurs objets et chaque objet peut être dans plusieurs catégories :
<class name="Category">
<id name="id" column="CATEGORY_ID"/>
...
<bag name="items" table="CATEGORY_ITEM">
<key column="CATEGORY_ID"/>
<many-to-many class="Item" column="ITEM_ID"/>
</bag>
</class>
<class name="Item">
<id name="id" column="ITEM_ID"/>
...
<!-- inverse end -->
<bag name="categories" table="CATEGORY_ITEM" inverse="true">
<key column="ITEM_ID"/>
<many-to-many class="Category" column="CATEGORY_ID"/>
</bag>
</class
>
Les changements faits uniquement sur l'extrémité inverse de l'association ne sont pas persistés. Ceci signifie qu'Hibernate a deux représentations en mémoire pour chaque association bidirectionnelle, un lien de A vers B et un autre de B vers A. Ceci est plus facile à comprendre si vous pensez au modèle objet de Java et à la façon dont nous créons une relation plusieurs-à-plusieurs dans Java :
category.getItems().add(item); // The category now "knows" about the relationship
item.getCategories().add(category); // The item now "knows" about the relationship
session.persist(item); // The relationship won't be saved!
session.persist(category); // The relationship will be saved
La partie non-inverse est utilisée pour sauvegarder la représentation en mémoire dans la base de données.
Vous pouvez définir une association bidirectionnelle un-à-plusieurs en mappant une association un-à-plusieurs vers la(es) même(s) colonne(s) de table qu'une association plusieurs-à-un et en déclarant l'extrémité pluri-valuée inverse="true".
<class name="Parent">
<id name="id" column="parent_id"/>
....
<set name="children" inverse="true">
<key column="parent_id"/>
<one-to-many class="Child"/>
</set>
</class>
<class name="Child">
<id name="id" column="child_id"/>
....
<many-to-one name="parent"
class="Parent"
column="parent_id"
not-null="true"/>
</class
>
Mapper une extrémité d'une association avec inverse="true" n'affecte pas l'opération de cascades, ce sont des concepts orthogonaux.
Une association bidirectionnelle où une extrémité est représentée comme une <list> ou une <map> requiert une considération spéciale. S'il y a une propriété de la classe enfant qui mappe la colonne de l'index, pas de problème, nous pouvons continuer à utiliser inverse="true" sur le mappage de la collection :
<class name="Parent">
<id name="id" column="parent_id"/>
....
<map name="children" inverse="true">
<key column="parent_id"/>
<map-key column="name"
type="string"/>
<one-to-many class="Child"/>
</map>
</class>
<class name="Child">
<id name="id" column="child_id"/>
....
<property name="name"
not-null="true"/>
<many-to-one name="parent"
class="Parent"
column="parent_id"
not-null="true"/>
</class
>
Mais, si il n'y a pas de telle propriété sur la classe enfant, nous ne pouvons pas considérer l'association comme vraiment bidirectionnelle (il y a des informations disponibles à une extrémité de l'association qui ne sont pas disponibles à l'autre extrémité). Dans ce cas, nous ne pouvons pas mapper la collection inverse="true". Par contre, nous utiliserons le mappage suivant :
<class name="Parent">
<id name="id" column="parent_id"/>
....
<map name="children">
<key column="parent_id"
not-null="true"/>
<map-key column="name"
type="string"/>
<one-to-many class="Child"/>
</map>
</class>
<class name="Child">
<id name="id" column="child_id"/>
....
<many-to-one name="parent"
class="Parent"
column="parent_id"
insert="false"
update="false"
not-null="true"/>
</class
>
Note that in this mapping, the collection-valued end of the association is responsible for updates to the foreign key.
Il y a trois approches possibles pour mapper une association ternaire. L'une est d'utiliser une Map avec une association comme son index :
<map name="contracts">
<key column="employer_id" not-null="true"/>
<map-key-many-to-many column="employee_id" class="Employee"/>
<one-to-many class="Contract"/>
</map
>
<map name="connections">
<key column="incoming_node_id"/>
<map-key-many-to-many column="outgoing_node_id" class="Node"/>
<many-to-many column="connection_id" class="Connection"/>
</map
>
Une seconde approche est simplement de remodeler l'association comme une classe d'entité. C'est l'approche la plus commune.
Une alternative finale est d'utiliser des éléments composites, dont nous discuterons plus tard.
Si vous êtes bien d'accord avec nous sur le fait que les clés composées sont une mauvaise chose et que les entités devraient avoir des identifiants artificiels (des clés subrogées), vous pourrez trouver un peu curieux que les associations plusieurs-à-plusieurs et les collections de valeurs que nous avons montrées jusqu'ici, mappent toutes des tables avec des clés composées ! Il est vrai que ce point est ambigu ; une table d'association pure ne semble pas tirer avantage d'une clé subrogée (bien qu'une collection de valeur composées le pourrait). Néanmoins, Hibernate fournit une fonctionnalité qui vous permet de mapper des associations plusieurs-à-plusieurs et des collections de valeurs vers une table avec une clé subrogée.
L'élément <idbag> vous laisse mapper une List (ou une Collection) avec une sémantique de sac. Par exemple :
<idbag name="lovers" table="LOVERS">
<collection-id column="ID" type="long">
<generator class="sequence"/>
</collection-id>
<key column="PERSON1"/>
<many-to-many column="PERSON2" class="Person" fetch="join"/>
</idbag
>
Comme vous pouvez le constater, un <idbag> a un générateur d'id artificiel, exactement comme une classe d'entité ! Une clé subrogée différente est assignée à chaque ligne de la collection. Cependant, Hibernate ne fournit pas de mécanisme pour découvrir la valeur d'une clé subrogée d'une ligne particulière.
Notez que les performances de la mise à jour d'un <idbag> sont bien meilleures qu'un <bag> ordinaire ! Hibernate peut localiser des lignes individuelles efficacement et les mettre à jour ou les effacer individuellement, comme une liste, une map ou un ensemble.
Dans l'implémentation actuelle, la stratégie de la génération de l'identifiant native n'est pas supportée pour les identifiants de collection <idbag>.
Exemples de collections
La classe suivante possède une collection d'instances Child(filles) :
package eg;
import java.util.Set;
public class Parent {
private long id;
private Set children;
public long getId() { return id; }
private void setId(long id) { this.id=id; }
private Set getChildren() { return children; }
private void setChildren(Set children) { this.children=children; }
....
....
}
Si chaque instance fille a au plus un parent, le mappage le plus naturel est une association un-à-plusieurs :
<hibernate-mapping>
<class name="Parent">
<id name="id">
<generator class="sequence"/>
</id>
<set name="children">
<key column="parent_id"/>
<one-to-many class="Child"/>
</set>
</class>
<class name="Child">
<id name="id">
<generator class="sequence"/>
</id>
<property name="name"/>
</class>
</hibernate-mapping
>
Ceci mappe les définitions de tables suivantes :
create table parent ( id bigint not null primary key )
create table child ( id bigint not null primary key, name varchar(255), parent_id bigint )
alter table child add constraint childfk0 (parent_id) references parent
Si le parent est requis, utilisez une association bidirectionnelle un-à-plusieurs :
<hibernate-mapping>
<class name="Parent">
<id name="id">
<generator class="sequence"/>
</id>
<set name="children" inverse="true">
<key column="parent_id"/>
<one-to-many class="Child"/>
</set>
</class>
<class name="Child">
<id name="id">
<generator class="sequence"/>
</id>
<property name="name"/>
<many-to-one name="parent" class="Parent" column="parent_id" not-null="true"/>
</class>
</hibernate-mapping
>
Notez la contrainte NOT NULL :
create table parent ( id bigint not null primary key )
create table child ( id bigint not null
primary key,
name varchar(255),
parent_id bigint not null )
alter table child add constraint childfk0 (parent_id) references parent
Alternativement, si vous insistez absolument pour que cette association soit unidirectionnelle, vous pouvez déclarer la contrainte NOT NULL sur le mappage <key> :
<hibernate-mapping>
<class name="Parent">
<id name="id">
<generator class="sequence"/>
</id>
<set name="children">
<key column="parent_id" not-null="true"/>
<one-to-many class="Child"/>
</set>
</class>
<class name="Child">
<id name="id">
<generator class="sequence"/>
</id>
<property name="name"/>
</class>
</hibernate-mapping
>
D'autre part, si un enfant peut avoir plusieurs parents, une association plusieurs-à-plusieurs est plus appropriée :
<hibernate-mapping>
<class name="Parent">
<id name="id">
<generator class="sequence"/>
</id>
<set name="children" table="childset">
<key column="parent_id"/>
<many-to-many class="Child" column="child_id"/>
</set>
</class>
<class name="Child">
<id name="id">
<generator class="sequence"/>
</id>
<property name="name"/>
</class>
</hibernate-mapping
>
Définitions des tables :
create table parent ( id bigint not null primary key )
create table child ( id bigint not null primary key, name varchar(255) )
create table childset ( parent_id bigint not null,
child_id bigint not null,
primary key ( parent_id, child_id ) )
alter table childset add constraint childsetfk0 (parent_id) references parent
alter table childset add constraint childsetfk1 (child_id) references childFor more examples and a complete explanation of a parent/child relationship mapping, see Chapitre 22, Exemple : père/fils for more information.
Des mappages d'association plus exotiques sont possibles, nous cataloguerons toutes les possibilités dans le prochain chapitre.