Hibernate.orgCommunity Documentation

第 7 章 集合映射(Collection mappings)

7.1. 持久化集合类(Persistent collections)
7.2. How to map collections
7.2.1. 集合外键(Collection foreign keys)
7.2.2. 索引集合类(Indexed collections)
7.2.3. Collections of basic types and embeddable objects
7.3. 高级集合映射(Advanced collection mappings)
7.3.1. 有序集合(Sorted collections)
7.3.2. 双向关联(Bidirectional associations)
7.3.3. 双向关联,涉及有序集合类
7.3.4. 三重关联(Ternary associations)
7.3.5. Using an <idbag>
7.4. 集合例子(Collection example)

Naturally Hibernate also allows to persist collections. These persistent collections can contain almost any other Hibernate type, including: basic types, custom types, components and references to other entities. The distinction between value and reference semantics is in this context very important. An object in a collection might be handled with "value" semantics (its life cycle fully depends on the collection owner), or it might be a reference to another entity with its own life cycle. In the latter case, only the "link" between the two objects is considered to be a state held by the collection.

As a requirement persistent collection-valued fields must be declared as an interface type (see 例 7.2 “Collection mapping using @OneToMany and @JoinColumn”). The actual interface might be java.util.Set, java.util.Collection, java.util.List, java.util.Map, java.util.SortedSet, java.util.SortedMap or anything you like ("anything you like" means you will have to write an implementation of org.hibernate.usertype.UserCollectionType).

Notice how in 例 7.2 “Collection mapping using @OneToMany and @JoinColumn” the instance variable parts was initialized with an instance of HashSet. This is the best way to initialize collection valued properties of newly instantiated (non-persistent) instances. When you make the instance persistent, by calling persist(), Hibernate will actually replace the HashSet with an instance of Hibernate's own implementation of Set. Be aware of the following error:

根据不同的接口类型,被 Hibernate 注射的持久化集合类的表现类似 HashMapHashSetTreeMapTreeSetArrayList

集合类实例具有值类型的通常行为。当被持久化对象引用后,他们会自动被持久化,当不再被引用后,自动被删除。假若实例被从一个持久化对象传递到另一个,它的元素可能从一个表转移到另一个表。两个实体不能共享同一个集合类实例的引用。因为底层关系数据库模型的原因,集合值属性无法支持空值语义;Hibernate 对空的集合引用和空集合不加区别。

Using annotations you can map Collections, Lists, Maps and Sets of associated entities using @OneToMany and @ManyToMany. For collections of a basic or embeddable type use @ElementCollection. In the simplest case a collection mapping looks like this:

Product describes a unidirectional relationship with Part using the join column PART_ID. In this unidirectional one to many scenario you can also use a join table as seen in 例 7.3 “Collection mapping using @OneToMany and @JoinTable”.

Without describing any physical mapping (no @JoinColumn or @JoinTable), a unidirectional one to many with join table is used. The table name is the concatenation of the owner table name, _, and the other side table name. The foreign key name(s) referencing the owner table is the concatenation of the owner table, _, and the owner primary key column(s) name. The foreign key name(s) referencing the other side is the concatenation of the owner property name, _, and the other side primary key column(s) name. A unique constraint is added to the foreign key referencing the other side table to reflect the one to many.

Lets have a look now how collections are mapped using Hibernate mapping files. In this case the first step is to chose the right mapping element. It depends on the type of interface. For example, a <set> element is used for mapping properties of type Set.

In 例 7.4 “Mapping a Set using <set>” a one-to-many association links the Product and Part entities. This association requires the existence of a foreign key column and possibly an index column to the Part table. This mapping loses certain semantics of normal Java collections:

  • 一个被包含的实体的实例只能被包含在一个集合的实例中。

  • 一个被包含的实体的实例只能对应于集合索引的一个值中。

Looking closer at the used <one-to-many> tag we see that it has the following options.

注意:<one-to-many> 元素不需要定义任何字段。也不需要指定表名。

Apart from the <set> tag as shown in 例 7.4 “Mapping a Set using <set>”, there is also <list>, <map>, <bag>, <array> and <primitive-array> mapping elements. The <map> element is representative:

例 7.6. Elements of the <map> mapping

    order-by="(8)column_name asc|desc"
    where="arb(9)itrary sql where condition"

    <key .... />
    <map-key .... />
    <element .... />






schema(可选):表的 schema 的名称,他将覆盖在根元素中定义的 schema


lazy(可选--默认为 true)可以用来关闭延迟加载(false):指定一直使用预先抓取,或者打开 "extra-lazy" 抓取,此时大多数操作不会初始化集合类(适用于非常大的集合)。


inverse(可选 — 默认为 false)标记这个集合作为双向关联关系中的方向一端。


cascade(可选 — 默认为 none)让操作级联到子实体。




order-by (optional): specifies a table column or columns that define the iteration order of the Map, Set or bag, together with an optional asc or desc.


where(可选):指定任意的 SQL where 条件,该条件将在重新载入或者删除这个集合时使用(当集合中的数据仅仅是所有可用数据的一个子集时这个条件非常有用)。


fetch(可选,默认为 select):用于在外连接抓取、通过后续 select 抓取和通过后续 subselect 抓取之间选择。


batch-size(可选,默认为 1):指定通过延迟加载取得集合实例的批处理块大小("batch size")。


access(可选-默认为属性 property):Hibernate 取得集合属性值时使用的策略。


乐观锁(可选 - 默认为 true):对集合的状态的改变会是否导致其所属的实体的版本增长(对一对多关联来说,关闭这个属性常常是有理的)。


mutable(可变)(可选 — 默认为 true):若值为 false,表明集合中的元素不会改变(在某些情况下可以进行一些小的性能优化)。

After exploring the basic mapping of collections in the preceding paragraphs we will now focus details like physical mapping considerations, indexed collections and collections of value types.

In the following paragraphs we have a closer at the indexed collections List and Map how the their index can be mapped in Hibernate.

Lists can be mapped in two different ways:

To order lists in memory, add @javax.persistence.OrderBy to your property. This annotation takes as parameter a list of comma separated properties (of the target entity) and orders the collection accordingly (eg firstname asc, age desc), if the string is empty, the collection will be ordered by the primary key of the target entity.

To store the index value in a dedicated column, use the @javax.persistence.OrderColumn annotation on your property. This annotations describes the column name and attributes of the column keeping the index value. This column is hosted on the table containing the association foreign key. If the column name is not specified, the default is the name of the referencing property, followed by underscore, followed by ORDER (in the following example, it would be orders_ORDER).


We recommend you to convert the legacy @org.hibernate.annotations.IndexColumn usages to @OrderColumn unless you are making use of the base property. The base property lets you define the index value of the first element (aka as base index). The usual value is 0 or 1. The default is 0 like in Java.

Looking again at the Hibernate mapping file equivalent, the index of an array or list is always of type integer and is mapped using the <list-index> element. The mapped column contains sequential integers that are numbered from zero by default.

假若你的表没有一个索引字段,当你仍然希望使用 List 作为属性类型,你应该把此属性映射为 Hibernate <bag>。从数据库中获取的时候,bag 不维护其顺序,但也可选择性的进行排序。

The question with Maps is where the key value is stored. There are everal options. Maps can borrow their keys from one of the associated entity properties or have dedicated columns to store an explicit key.

To use one of the target entity property as a key of the map, use @MapKey(name="myProperty"), where myProperty is a property name in the target entity. When using @MapKey without the name attribuate, the target entity primary key is used. The map key uses the same column as the property pointed out. There is no additional column defined to hold the map key, because the map key represent a target property. Be aware that once loaded, the key is no longer kept in sync with the property. In other words, if you change the property value, the key will not change automatically in your Java model.

Alternatively the map key is mapped to a dedicated column or columns. In order to customize the mapping use one of the following annotations:

  • @MapKeyColumn if the map key is a basic type. If you don't specify the column name, the name of the property followed by underscore followed by KEY is used (for example orders_KEY).

  • @MapKeyEnumerated / @MapKeyTemporal if the map key type is respectively an enum or a Date.

  • @MapKeyJoinColumn/@MapKeyJoinColumns if the map key type is another entity.

  • @AttributeOverride/@AttributeOverrides when the map key is a embeddable object. Use key. as a prefix for your embeddable object property names.

You can also use @MapKeyClass to define the type of the key if you don't use generics.

例 7.11. Map key as basic type using @MapKeyColumn


public class Customer {
   @Id @GeneratedValue public Integer getId() { return id; }
   public void setId(Integer id) { this.id = id; }
   private Integer id;
   @OneToMany @JoinTable(name="Cust_Order")
   public Map<String,Order> getOrders() { return orders; }
   public void setOrders(Map<String,Order> orders) { this.orders = orders; }
   private Map<String,Order> orders;
public class Order {
   @Id @GeneratedValue public Integer getId() { return id; }
   public void setId(Integer id) { this.id = id; }
   private Integer id;
   public String getNumber() { return number; }
   public void setNumber(String number) { this.number = number; }
   private String number;
   public Customer getCustomer() { return customer; }
   public void setCustomer(Customer customer) { this.customer = customer; }
   private Customer number;
-- Table schema
|-------------| |----------| |---------------|
| Order       | | Customer | | Cust_Order    |
|-------------| |----------| |---------------|
| id          | | id       | | customer_id   |
| number      | |----------| | order_id      |
| customer_id |              | orders_number |
|-------------|              |---------------|


We recommend you to migrate from @org.hibernate.annotations.MapKey / @org.hibernate.annotation.MapKeyManyToMany to the new standard approach described above

Using Hibernate mapping files there exists equivalent concepts to the descibed annotations. You have to use <map-key>, <map-key-many-to-many> and <composite-map-key>. <map-key> is used for any basic type, <map-key-many-to-many> for an entity reference and <composite-map-key> for a composite type.

In some situations you don't need to associate two entities but simply create a collection of basic types or embeddable objects. Use the @ElementCollection for this case.

The collection table holding the collection data is set using the @CollectionTable annotation. If omitted the collection table name defaults to the concatenation of the name of the containing entity and the name of the collection attribute, separated by an underscore. In our example, it would be User_nicknames.

The column holding the basic type is set using the @Column annotation. If omitted, the column name defaults to the property name: in our example, it would be nicknames.

But you are not limited to basic types, the collection type can be any embeddable object. To override the columns of the embeddable object in the collection table, use the @AttributeOverride annotation.

Such an embeddable object cannot contains a collection itself.


in @AttributeOverride, you must use the value. prefix to override properties of the embeddable object used in the map value and the key. prefix to override properties of the embeddable object used in the map key.


public class User {
      @AttributeOverride(name="key.street1", column=@Column(name="fld_street")),
      @AttributeOverride(name="value.stars", column=@Column(name="fld_note"))
   public Map<Address,Rating> getFavHomes() { ... }


We recommend you to migrate from @org.hibernate.annotations.CollectionOfElements to the new @ElementCollection annotation.

Using the mapping file approach a collection of values is mapped using the <element> tag. For example:

Hibernate supports collections implementing java.util.SortedMap and java.util.SortedSet. With annotations you declare a sort comparator using @Sort. You chose between the comparator types unsorted, natural or custom. If you want to use your own comparator implementation, you'll also have to specify the implementation class using the comparator attribute. Note that you need to use either a SortedSet or a SortedMap interface.

Using Hibernate mapping files you specify a comparator in the mapping file with <sort>:

sort 属性中允许的值包括 unsortednatural 和某个实现了 java.util.Comparator 的类的名称。


分类集合的行为事实上象 java.util.TreeSet 或者 java.util.TreeMap

If you want the database itself to order the collection elements, use the order-by attribute of set, bag or map mappings. This solution is implemented using LinkedHashSet or LinkedHashMap and performs the ordering in the SQL query and not in the memory.


注意:这个 order-by 属性的值是一个 SQL 排序子句而不是 HQL 的。

关联还可以在运行时使用集合 filter() 根据任意的条件来排序:

双向关联允许通过关联的任一端访问另外一端。在 Hibernate 中,支持两种类型的双向关联:

Often there exists a many to one association which is the owner side of a bidirectional relationship. The corresponding one to many association is in this case annotated by @OneToMany(mappedBy=...)

Troop has a bidirectional one to many relationship with Soldier through the troop property. You don't have to (must not) define any physical mapping in the mappedBy side.

To map a bidirectional one to many, with the one-to-many side as the owning side, you have to remove the mappedBy element and set the many to one @JoinColumn as insertable and updatable to false. This solution is not optimized and will produce additional UPDATE statements.

How does the mappping of a bidirectional mapping look like in Hibernate mapping xml? There you define a bidirectional one-to-many association by mapping a one-to-many association to the same table column(s) as a many-to-one association and declaring the many-valued end inverse="true".

在“一”这一端定义 inverse="true" 不会影响级联操作,二者是正交的概念。

A many-to-many association is defined logically using the @ManyToMany annotation. You also have to describe the association table and the join conditions using the @JoinTable annotation. If the association is bidirectional, one side has to be the owner and one side has to be the inverse end (ie. it will be ignored when updating the relationship values in the association table):

In this example @JoinTable defines a name, an array of join columns, and an array of inverse join columns. The latter ones are the columns of the association table which refer to the Employee primary key (the "other side"). As seen previously, the other side don't have to (must not) describe the physical mapping: a simple mappedBy argument containing the owner side property name bind the two.

As any other annotations, most values are guessed in a many to many relationship. Without describing any physical mapping in a unidirectional many to many the following rules applied. The table name is the concatenation of the owner table name, _ and the other side table name. The foreign key name(s) referencing the owner table is the concatenation of the owner table name, _ and the owner primary key column(s). The foreign key name(s) referencing the other side is the concatenation of the owner property name, _, and the other side primary key column(s). These are the same rules used for a unidirectional one to many relationship.

A Store_City is used as the join table. The Store_id column is a foreign key to the Store table. The implantedIn_id column is a foreign key to the City table.

Without describing any physical mapping in a bidirectional many to many the following rules applied. The table name is the concatenation of the owner table name, _ and the other side table name. The foreign key name(s) referencing the owner table is the concatenation of the other side property name, _, and the owner primary key column(s). The foreign key name(s) referencing the other side is the concatenation of the owner property name, _, and the other side primary key column(s). These are the same rules used for a unidirectional one to many relationship.

A Store_Customer is used as the join table. The stores_id column is a foreign key to the Store table. The customers_id column is a foreign key to the Customer table.

Using Hibernate mapping files you can map a bidirectional many-to-many association by mapping two many-to-many associations to the same database table and declaring one end as inverse.


You cannot select an indexed collection.

例 7.27 “Many to many association using Hibernate mapping files” shows a bidirectional many-to-many association that illustrates how each category can have many items and each item can be in many categories:

如果只对关联的反向端进行了改变,这个改变不会被持久化。 这表示 Hibernate 为每个双向关联在内存中存在两次表现,一个从 A 连接到 B,另一个从 B 连接到 A。如果你回想一下 Java 对象模型,我们是如何在 Java 中创建多对多关系的,这可以让你更容易理解:


There are some additional considerations for bidirectional mappings with indexed collections (where one end is represented as a <list> or <map>) when using Hibernate mapping files. If there is a property of the child class that maps to the index column you can use inverse="true" on the collection mapping:

但是,假若子类中没有这样的属性存在,我们不能认为这个关联是真正的双向关联(信息不对称,在关联的一端有一些另外一端没有的信息)。在这种情况下,我们不能使用 inverse="true"。我们需要这样用:


集合例子(Collection example)。

下面的代码是用来添加一个新的 Child

这个类有一个 Child 的实例集合。如果每一个子实例至多有一个父实例,那么最自然的映射是一个 one-to-many 的关联关系:


如果父亲是必须的,那么就可以使用双向 one-to-many 的关联了:

请注意 NOT NULL 的约束:

Alternatively, if this association must be unidirectional you can enforce the NOT NULL constraint.

On the other hand, if a child has multiple parents, a many-to-many association is appropriate.


For more examples and a complete explanation of a parent/child relationship mapping, see 第 24 章 示例:父子关系(Parent/Child) for more information. Even more complex association mappings are covered in the next chapter.