Mapping entity bean associations/relationships

One-to-one

You can associate entity beans through a one-to-one relationship
using @OneToOne. There are two cases for one-to-one
associations: either the associated entities share the same primary
keys values or a foreign key is held by one of the entities (note that
this FK column in the database should be constrained unique to
simulate one-to-one multiplicity).

使用@OneToOne注解可以建立实体bean之间的一对一的关联。
一对一关联有两种情况：
一是关联的实体都共享同样的主键，
二是其中一个实体通过外键关联到另一个实体的主键
（注意要模拟一对一关联必须在外键字段上添加唯一性约束）.

First, we map a real one-to-one association using shared primary
keys:

首先，我们通过共享主键来进行一对一关联映射:

programlisting

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

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

programlisting

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

The one to one is marked as true by using the
@PrimaryKeyJoinColumn annotation.

通过使用 @PrimaryKeyJoinColumn 注解定义了一对一关联。

In the following example, the associated entities are linked
through a foreign key column:

下面这个例子使用外键进行实体的关联。

programlisting

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

A Customer is linked to a
Passport, with a foreign key column named
passport_fk in the Customer
table. The join column is declared with the
@JoinColumn annotation which looks like the
@Column annotation. It has one more parameters
named referencedColumnName. This parameter declares
the column in the targeted entity that will be used to the join. Note
that when using
referencedColumnName to a non
primary key column, the associated class has to be
Serializable. Also note that the
referencedColumnName to a non
primary key column has to be mapped to a property having a single
column (other cases might not work).

上面这个例子中，Customer 通过Customer
表中名为的passport_fk 外键和 Passport关联。
@JoinColumn注解定义了关联字段。
该注解和@Column注解有点类似，
但是多了一个名为referencedColumnName的参数。
该参数定义了所关联目标实体中的关联字段。
注意，当referencedColumnName关联到非主键字段的时候，
关联的目标类必须实现Serializable，
还要注意的是所映射的属性只有单个字段(否则映射无效)。
.

The association may be bidirectional. In a bidirectional
relationship, one of the sides (and only one) has to be the owner: the
owner is responsible for the association column(s) update. To declare
a side as not responsible for the relationship,
the attribute mappedBy is used.
mappedBy refers to the property name of the
association on the owner side. In our case, this is
passport. As you can see, you don't have to (must
not) declare the join column since it has already been declared on the
owners side.

一对一关联可能是双向的。在双向关联中，
有且仅有一端是作为owner存在的：owner负责维护关联字段（即更新）。
对于不需要维护这种关系的一端则通过mappedBy属性进行声明。
mappedBy的值指向owner端的关联属性。
在上面这个例子中，mappedBy的值为 passport。
最后，不必也不能再在另外一端（非owner端）定义关联字段了，
因为已经在owner端进行了声明。

If no @JoinColumn is declared on the owner
side, the defaults apply. A join column(s) will be created in the
owner table and its name will be the concatenation of the name of the
relationship in the owner side, _ (underscore), and
the name of the primary key column(s) in the owned side. In this
example passport_id because the property name is
passport and the column id of Passport
is id.

如果在owner端没有声明@JoinColumn，系统自动进行处理：
在owner表中将创建关联字段，
字段名为：owner端的关联属性名＋下划线＋被关联端的主键字段名。
在上面这个例子中是passport_id，
因为Customer中关联属性名为passport，
Passport的主键是id。

Many-to-one

Many-to-one associations are declared at the property level with
the annotation @ManyToOne:

在实体属性一级使用@ManyToOne注解来定义多对一关联:

programlisting

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

The @JoinColumn attribute is optional, the
default value(s) is like in one to one, the concatenation of the name
of the relationship in the owner side, _
(underscore), and the name of the primary key column in the owned
side. In this example company_id because the
property name is company and the column id of
Company is id.

其中@JoinColumn是可选的，关联字段默认值和一对一
（one to one）关联的情况相似，
也是"owner端的关联属性名＋下划线＋被关联端的主键字段名"。
在这个例子中是company_id，
因为关联的属性是company，
Company的主键是id。

@ManyToOne has a parameter named
targetEntity which describes the target entity
name. You usually don't need this parameter since the default value
(the type of the property that stores the association) is good in
almost all cases. However this is useful when you want to use
interfaces as the return type instead of the regular entity.

@ManyToOne注解有一个名为targetEntity的参数，
该参数定义了目标实体名。通常不需要定义该参数，
因为在大部分情况下默认值（表示关联关系的属性类型）就可以很好的满足要求了。
不过下面这种情况下这个参数就显得有意义了：使用接口作为返回值而不是常见的实体。

programlisting

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

public interface Company {
...

Collections

Overview

You can map Collection,
List (ie ordered lists, not indexed lists),
Map and Set. The EJB3
specification describes how to map an ordered list (ie a list
ordered at load time) using
@javax.persistence.OrderBy annotation: this
annotation takes into parameter a list of comma separated (target
entity) properties to order the collection by (eg firstname
asc, age desc), if the string is empty, the collection will
be ordered by id. @OrderBy currently works only
on collections having no association table. For true indexed
collections, please refer to the .
EJB3 allows you to map Maps using as a key one of the target entity
property using @MapKey(name="myProperty")
(myProperty is a property name in the target entity). When using
@MapKey (without property name), the target
entity primary key is used. 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 (Map support the way Hibernate 3 does is currently not
supported in this release).

你可以对 Collection ，List
（指有序list, 而不是索引式list），
Map和Set这几种类型进行映射。
EJB3规范定义了怎么样使用@javax.persistence.OrderBy
注解来对有序list进行映射：
该注解接受的参数格式：用逗号隔开的（目标实体）属性名及排序指令，
如firstname asc, age desc，如果该参数为空，则默认以id对该集合进行排序。
对于true indexed collections，请参考。
EJB3允许使用@MapKey(name="myProperty")
来把Map映射为目标实体的属性（myProperty是目标实体的一个属性）。
如果使用@MapKey注解的时候不提供属性名，
系统默认使用目标实体的主键。
注意一旦加载，key不再和属性保持同步，
也就是说，如果你改变了该属性的值，在你的java模型中的key不会自动更新。
(Hibernate 3中Map支持的方式在当前的发布版中还未得到支持).

Hibernate has several notions of collections.

Hibernate将集合分以下几类.

Collections semantics

Semantic 语义	java representation 实现	annotations 注解

Bag semantic

java.util.List, java.util.Collection

@org.hibernate.annotations.CollectionOfElements,
@OneToMany, @ManyToMany

List semantic

java.util.List

@org.hibernate.annotations.CollectionOfElements,
@OneToMany, @ManyToMany + @OrderBy,
@org.hibernate.annotations.IndexColumn

Set semantic

java.util.Set

@org.hibernate.annotations.CollectionOfElements,
@OneToMany, @ManyToMany

Map semantic

java.util.Map

@org.hibernate.annotations.CollectionOfElements,
@OneToMany, @ManyToMany + @MapKey

remark
So specifically, java.util.List collections wo @OrderBy nor
@org.hibernate.annotations.IndexColumn are going to be considered as
bags.

remark
从上面可以明确地看到，带有@OrderBy 和
@org.hibernate.annotations.IndexColumn 注解的java.util.List集合将不被看作bag类.

Collection of primitive, core type or embedded objects is not
supported by the EJB3 specification. Hibernate Annotations allows
them however (see ).

EJB3规范不支持原始类型，核心类型，嵌入式对象的集合。但是Hibernate对此提供了支持
(详情参考 ).

programlisting

@Entity public class City {
@OneToMany(mappedBy="city")
@OrderBy("streetName")
public List<Street> getStreets() {
return streets;
}
...
}

@Entity public class Street {
public String getStreetName() {
return streetName;
}

@ManyToOne
public City getCity() {
return city;
}
...
}

@Entity
public class Software {
@OneToMany(mappedBy="software")
@MapKey(name="codeName")
public Map<String, Version> getVersions() {
return versions;
}
...
}

@Entity
@Table(name="tbl_version")
public class Version {
public String getCodeName() {...}

@ManyToOne
public Software getSoftware() { ... }
...
}

So City has a collection of
Streets that are ordered by
streetName (of Street) when
the collection is loaded. Software has a map of
Versions which key is the
Version codeName.

上面这个例子中，City
中包括了以streetName排序的Street的集合。
而Software中包括了以codeName作为
key和以Version作为值的Map。

Unless the collection is a generic, you will have to define
targetEntity. This is a annotation attribute that
take the target entity class as a value.

除非集合为generic类型，否则你需要指定targetEntity。
这个注解属性接受的参数为目标实体的class。

One-to-many

One-to-many associations are declared at the property level
with the annotation @OneToMany. One to many
associations may be bidirectional.

在属性级使用 @OneToMany注解可定义一对多关联。一对多关联可以是双向关联。

Bidirectional

Since many to one are (almost) always the owner side of a
bidirectional relationship in the EJB3 spec, the one to many
association is annotated by @OneToMany( mappedBy=...
)

在EJB3规范中多对一这端几乎总是双向关联中的owner端，
而一对多这端的关联注解为@OneToMany( mappedBy=...
)

programlisting

@Entity
public class Troop {
@OneToMany(mappedBy="troop")
public Set<Soldier> getSoldiers() {
...
}

@Entity
public class Soldier {
@ManyToOne
@JoinColumn(name="troop_fk")
public Troop getTroop() {
...
}

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.

Troop 通过troop 属性和Soldier建立了一对多的双向关联.
在mappedBy端不必也不能再定义任何物理映射

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 obviously not optimized from the number of
needed statements.

对于一对多的双向映射,如果要一对多这一端维护关联关系,
你需要删除mappedBy元素并将多对一这端的
@JoinColumn的insertable和updatable设置为false.
很明显，这种方案在最终生成的sql语句的数量上不会得到任何优化.

programlisting

@Entity
public class Troop {
@OneToMany
@JoinColumn(name="troop_fk") //we need to duplicate the physical information
public Set<Soldier> getSoldiers() {
...
}

@Entity
public class Soldier {
@ManyToOne
@JoinColumn(name="troop_fk", insertable=false, updatable=false)
public Troop getTroop() {
...
}

Unidirectional

A unidirectional one to many using a foreign key column in
the owned entity is not that common and not really recommended. We
strongly advise you to use a join table for this kind of
association (as explained in the next section). This kind of
association is described through a
@JoinColumn

通过在owner端增加一个外键字段来实现一对多单向关联是很少见的,也是不推荐的.
我们强烈建议通过一个join table来做这种关联(下一节会对此进行解释).
可以通过@JoinColumn注解来描述这种单向关联关系.

programlisting

@Entity
public class Customer implements Serializable {
@OneToMany(cascade=CascadeType.ALL, fetch=FetchType.EAGER)
@JoinColumn(name="CUST_ID")
public Set<Ticket> getTickets() {
...
}

@Entity
public class Ticket implements Serializable {
... //no bidir
}

Customer describes a unidirectional
relationship with Ticket using the join column
CUST_ID.

Customer 通过
CUST_ID字段和Ticket 建立了单向关联关系.

Unidirectional with join table

A unidirectional one to many with join table is much
preferred. This association is described through an
@JoinTable.

通过join table处理单向一对多关联是首选方式.这种关联通过@JoinTable注解来进行描述.

programlisting

@Entity
public class Trainer {
@OneToMany
@JoinTable(
name="TrainedMonkeys",
joinColumns = { @JoinColumn( name="trainer_id") },
inverseJoinColumns = @JoinColumn( name="monkey_id")
)
public Set<Monkey> getTrainedMonkeys() {
...
}

@Entity
public class Monkey {
... //no bidir
}

Trainer describes a unidirectional
relationship with Monkey using the join
table TrainedMonkeys, with a foreign key
trainer_id to Trainer
(joinColumns) and a foreign key
monkey_id to Monkey
(inversejoinColumns).

上面这个例子中，Trainer通过
TrainedMonkeys表和
Monkey 建立了单向关联.
其中外键trainer_id关联到Trainer
(joinColumns),
而外键monkey_id关联到 Monkey
(inversejoinColumns).

Defaults

Without describing any physical mapping, 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.

通过关联表来建立单向一对多关联不需要描述任何物理映射.
关联表的表名由以下三个部分组成:主表（owner table）表名+下划线+从表（the other side table）表名.
关联表中指向主表的外键名：主表（owner table）表名+下划线+主表（owner table）主键字段名
关联表中指向从表的外键名：从表（the other side table）表名+下划线+从表（the other side table）主键字段名
关联表中指向从表的外键定义为唯一性约束，用来表示一对多的关联关系。

programlisting

@Entity
public class Trainer {
@OneToMany
public Set<Tiger> getTrainedTigers() {
...
}

@Entity
public class Tiger {
... //no bidir
}

Trainer describes a unidirectional
relationship with Tiger using the join
table Trainer_Tiger, with a foreign key
trainer_id to Trainer (table
name, _, trainer id) and a foreign key
trainedTigers_id to Monkey
(property name, _, Tiger primary column).

上面这个例子中，Trainer和Tiger
通过关联表 Trainer_Tiger建立单向关联关系,
其中外键trainer_id关联到Trainer
(table name, _, trainer id),
而外键trainedTigers_id关联到Monkey
(property name, _, Tiger primary column).

Many-to-many

Definition

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):

通过@ManyToMany注解可定义逻辑上的多对多关联.
通过@JoinTable注解描述关联表和关联条件.
如果是双向关联,其中一段必须定义为owner,另一端必须定义为inverse:

programlisting

@Entity
public class Employer implements Serializable {
@ManyToMany(
targetEntity=org.hibernate.test.metadata.manytomany.Employee.class,
cascade={CascadeType.CREATE, CascadeType.MERGE}
)
@JoinTable(
name="EMPLOYER_EMPLOYEE",
joinColumns={@JoinColumn(name="EMPER_ID")},
inverseJoinColumns={@JoinColumn(name="EMPEE_ID")}
)
public Collection getEmployees() {
return employees;
}
...
}

programlisting

@Entity
public class Employee implements Serializable {
@ManyToMany(
cascade={CascadeType.CREATE, CascadeType.MERGE},
mappedBy="employees"
targetEntity=Employer.class
)
public Collection getEmployers() {
return employers;
}
}

We've already shown the many declarations and the detailed
attributes for associations. We'll go deeper in the
@JoinTable description, it defines a
name, an array of join columns (an array in
annotation is defined using { A, B, C }), 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").

至此已经展示了很多跟关联有关的声明定义以及属性细节.
下面我们将深入@JoinTable注解,该注解定义了关联表表名,
关联字段数组（注解中定义数组的格式为{ A, B, C }）,
以及inverse关联字段数组.
后者是是关联表中关联Employee的主键的字段. (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.

正如前面所示,被关联端不必也不能描述物理映射:
一个简单的包含了owner端的属性名的 mappedBy参数就绑定双方的关系。

Default values

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.

和其他许多注解一样,在多对多关联中很多值是自动生成.
在单向多对多关联中不需要描述任何物理映射,Hibernate根据以下规则生成相应的值.
关联表名:主表（owner table）表名+下划线+从表（the other side table）表名,
关联到主表（owner table）的外键名:主表（owner table）名+下划线+主表（owner table）中的主键字段名.
关联到从表（the other side table）的外键名:
主表（owner table）中用于关联的属性名+下划线+从表（the other side table）的主键字段名.
以上规则对于单向一对多关联同样有效.

programlisting

@Entity
public class Store {
@ManyToMany(cascade = CascadeType.PERSIST)
public Set<City> getImplantedIn() {
...
}
}

@Entity
public class City {
... //no bidirectional relationship
}

A Store_Table 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.

上面这个例子中，Store_Table作为关联表.
Store_id字段是关联到Store表的外键.
而implantedIn_id字段则关联到City表.

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.

在双向多对多关联中也不需要定义任何物理映射, Hibernate根据以下规则生成相应的值
关联表名: :主表（owner table）表名+下划线+从表（the other side table）表名,
关联到主表（owner table）的外键名:
从表（the other side table）用于关联的属性名+下划线+主表（owner table）中的主键字段名.
关联到从表（the other side table）的外键名:
主表（owner table）用于关联的属性名+下划线+从表（the other side table）的主键字段名.
以上规则对于单向一对多关联同样有效.

programlisting

@Entity
public class Store {
@ManyToMany(cascade = {CascadeType.PERSIST, CascadeType.MERGE})
public Set<Customer> getCustomers() {
...
}
}

@Entity
public class Customer {
@ManyToMany(mappedBy="customers")
public Set<Store> getStores() {
...
}
}

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
City table.

在上面这个例子中，Store_Customer作为关联表.
stores_id字段是关联到Store表的外键,
而customers_id字段关联到City表.

Transitive persistence with cascading

You probably have noticed the cascade
attribute taking an array of CascadeType as a
value. The cascade concept in EJB3 is very is similar to the
transitive persistence and cascading of operations in Hibernate, but
with slightly different semantics and cascading types:

也许你已经注意到了cascade属性接受的值为CascadeType数组.
在EJB3中的cascade的概念和Hibernate中的transitive持久化和cascade操作非常类似,
但是在语义上有细微的区别,支持的cascade类型也有点区别:

CascadeType.PERSIST: cascades the persist (create) operation to associated entities persist() is called or if the entity is managed

CascadeType.MERGE: cascades the merge operation to associated entities if merge() is called or if the entity is managed

CascadeType.REMOVE: cascades the remove operation to associated entities if delete() is called

CascadeType.REFRESH: cascades the refresh operation to associated entities if refresh() is called

CascadeType.ALL: all of the above

Please refer to the chapter 6.3 of the EJB3 specification for
more information on cascading and create/merge semantics.

关于cascading, create/merge的语义请参考EJB3规范的6.3章节.

Association fetching

You have the ability to either eagerly or lazily fetch
associated entities. The fetch parameter can be set
to FetchType.LAZY or
FetchType.EAGER. EAGER will try
to use an outer join select to retrieve the associated object, while
LAZY is the default and will only trigger a select
when the associated object is accessed for the first time. EJBQL also
has a fetch keyword that allows you to override
laziness when doing a particular query. This is very useful to improve
performance and is decided on a use case to use case basis.

通过Hibernate你可以获得直接或者延迟抓取关联实体的功能。
fetch参数可以设置为FetchType.LAZY
或者 FetchType.EAGER。
EAGER通过outer join select直接获取关联的对象，
而LAZY（默认值）在第一次访问关联对象的时候才会触发相应的select操作。
EJBQL提供了fetch关键字，该关键字可以在进行特殊查询的时候覆盖默认值。
这对于提高性能来说非常有效，应该根据实际的用例来判断是否选择fetch关键字。