EJB3.0-JPA实体的注解规范以及Hibernate特有的扩展（下）

[size=medium] 有时候,你想让数据库,而非JVM,来替你完成一些计算,也可能想创建某种虚拟列.
你可以使用SQL片段(亦称为公式),而不是将属性映射到(物理)列. 这种属性是只读的(属性值由公求得).
@Formula("obj_length * obj_height * obj_width")
public long getObjectVolume()

SQL片段可以是任意复杂的,甚至可包含子查询.

@org.hibernate.annotations.Type
覆盖了Hibernate所用的默认类型:这通常不是必须的,因为类型可以由Hibernate正确推得.
关于Hibernate类型的详细信息,请参考Hibernate使用手册.
@org.hibernate.annotations.TypeDef 和@org.hibernate.annotations.TypeDefs允许你来声明类型定义.
这些注解被置于类或包一级.注意,对session factory来说,这些定义将是全局的(即使定义于类一级),并且类型定义必须先于任何使用.
@TypeDefs(
{
@TypeDef(
name="caster",
typeClass = CasterStringType.class,
parameters = {
@Parameter(name="cast", value="lower")
}
)
}
)
package org.hibernate.test.annotations.entity;

...
public class Forest {
@Type(type="caster")
public String getSmallText() {
...
}

当使用组合的用户自定义类型时,你必须自己表示列的定义.
@Columns就是为了此目的而引入的.
@Type(type="org.hibernate.test.annotations.entity.MonetaryAmountUserType")
@Columns(columns = {
@Column(name="r_amount"),
@Column(name="r_currency")
})
public MonetaryAmount getAmount() {
return amount;
}

public class MonetaryAmount implements Serializable {
private BigDecimal amount;
private Currency currency;
...
}

通过在列属性(property)上使用@Index注解,可以在特定列上定义索引,columnNames属性(attribute)将随之被忽略.

@Column(secondaryTable="Cat1")
@Index(name="story1index")
public String getStoryPart1() {
return storyPart1;
}

在嵌入式对象内部,你可以在那些指向该嵌入式对象所属元素的属性上定义该注解.
@Entity
public class Person {
@Embeddable public Address address;
...
}

@Embeddable
public class Address {
@Parent public Person owner;
...
}

person == person.address.owner

某些属性可以在对数据库做插入或更新操作的时候生成.
Hibernate能够处理这样的属性,并触发一个后续的查询来读取这些属性.

@Entity
public class Antenna {
@Id public Integer id;
@Generated(GenerationTime.ALWAYS) @Column(insertable = false, updatable = false)
public String longitude;

@Generated(GenerationTime.INSERT) @Column(insertable = false)
public String latitude;
}

你可以将属性注解为@Generated.
但是你要注意insertability和updatability不要和你选择的生成策略冲突.
如果选择了GenerationTime.INSERT,该属性不能包含insertable列,
如果选择了GenerationTime.ALWAYS,该属性不能包含insertable和updatable列.

@Version属性不可以为
@Generated(INSERT)(设计时), 只能是
NEVER或ALWAYS.

SINGLE_TABLE 是个功能强大的策略,但有时,特别对遗留系统而言,
是无法加入一个额外的辨别符列.
由此,Hibernate引入了辨别符公式(discriminator formula)的概念:
@DiscriminatorFormula是@DiscriminatorColumn的替代品,
它使用SQL片段作为辨别符解决方案的公式( 不需要有一个专门的字段).

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

默认情况下查询顶级实体,Hibernate不会加入带鉴别器列的约束条件子句.
但是如果该列中还包含了和继承层次无关的值(通过@DiscriminatorValue)
就会很不方便.为了解决这个问题,你可以在类上使用@ForceDiscriminator注解
(将该注解放在@DiscriminatorColumn后面).
这样Hibernate在加载实体的时候就可以列出对应的值.

默认情况下,当预期的被关联元素不在数据库中(关乎关联列的错误id),致使Hiberante无法解决关联性问题时,Hibernate就会抛出异常.
这对遗留schema和历经拙劣维护的schema而言,这或有许多不便.
此时,你可用 @NotFound 注解让Hibernate略过这样的元素而不是抛出异常.
该注解可用于 @OneToOne (有外键)、 @ManyToOne 、
@OneToMany 或 @ManyToMany 关联.

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

有时候删除某实体的时候需要触发数据库的级联删除.

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

上面这个例子中,Hibernate将生成一个数据库级的级联删除约束.

Hibernate生成的外键约束的名字可读性相当差,
你可以使用@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

EJB3为延迟加载和获取模式提供了fetch选项,而Hibernate
这方面提供了更丰富的选项集.为了更好的调整延迟加载和获取策略,Hibernate引入了
一些附加的注解:
@LazyToOne: 定义了@ManyToOne 和 @OneToOne
关联的延迟选项. LazyToOneOption 可以是PROXY (例如:基于代理的延迟加载),NO_PROXY (例如:基于字节码增强的延迟加载 - 注意需要在构建期处理字节码)和 FALSE (非延迟加载的关联)

@LazyCollection: 定义了@ManyToMany和@OneToMany 关联的延迟选项. LazyCollectionOption可以是TRUE (集合具有延迟性,只有在访问的时候才加载), EXTRA (集合具有延迟性,并且所有的操作都会尽量避免加载集合,对于一个巨大的集合特别有用,因为这样的集合中的元素没有必要全部加载)和 FALSE(非延迟加载的关联)

@Fetch:
定义了加载关联关系的获取策略. FetchMode 可以是SELECT (在需要加载关联的时候触发select操作), SUBSELECT(只对集合有效,使用了子查询策略,详情参考Hibernate参考文档) or JOIN (在加载主实体(owner entity)的时候使用SQL JOIN来加载关联关系).
JOIN 将覆写任何延迟属性(通过JOIN策略加载的关联将不再具有延迟性).
The Hibernate annotations overrides the EJB3 fetching options.

Hibernate注解覆写了EJB3提供的获取(fetch)选项.

Annotations
Lazy
Fetch

@[One|Many]ToOne](fetch=FetchType.LAZY)
@LazyToOne(PROXY)
@Fetch(SELECT)
@[One|Many]ToOne](fetch=FetchType.EAGER)
@LazyToOne(FALSE)
@Fetch(JOIN)
@ManyTo[One|Many](fetch=FetchType.LAZY)
@LazyCollection(TRUE)
@Fetch(SELECT)
@ManyTo[One|Many](fetch=FetchType.EAGER)
@LazyCollection(FALSE)
@Fetch(JOIN)

以下是可能的设置方式
用@BatchSizebatch设置集合的batch大小
用@Where或@WhereJoinTable注解设置Where子句,
这两种注解分别应用于目标实体和关联表

用注解@Check来设置check子句
用注解@OrderBy来设置SQL的order by子句
利用@OnDelete(action=OnDeleteAction.CASCADE) 注解设置级连删除策略

你也可以利用@Sort注解定义一个排序比较器(sort comparator),表明希望的比较器类型,无序、自然顺序或自定义排序,三者择一.若你想用你自己实现的comparator,你还需要利用comparator属性(attribute)指明实现类.
注意你需要使用SortedSet或SortedMap接口

@OneToMany(cascade=CascadeType.ALL, fetch=FetchType.EAGER)
@JoinColumn(name="CUST_ID")
@Sort(type = SortType.COMPARATOR, comparator = TicketComparator.class)
@Where(clause="1=1")
@OnDelete(action=OnDeleteAction.CASCADE)
public SortedSet<Ticket> getTickets() {
return tickets;
}

关于这些注解更详细的信息,请参阅此前的描述.
Hibernate生成的外键约束的名字可读性相当差,你可以使用@ForeignKey注解覆盖自动生成的值. 注意该注解应该置于关联关系的主体端,inverseName
指向另一端的约束.
@Entity
public class Woman {
...
@ManyToMany(cascade = {CascadeType.ALL})
@ForeignKey(name = "TO_WOMAN_FK", inverseName = "TO_MAN_FK")
public Set<Man> getMens() {
return mens;
}
}

alter table Man_Woman add constraint TO_WOMAN_FK foreign key (woman_id) references Woman
alter table Man_Woman add constraint TO_MAN_FK foreign key (man_id) references Man

比EJB3更胜一筹的是,Hibernate Annotations支持真正的List和Array.
映射集合的方式和以前完全一样,只不过要新增@IndexColumn注解.
该注解允许你指明存放索引值的字段.你还可以定义代表数据库中首个元素的索引值(亦称为索引基数).
常见取值为0或1.
@OneToMany(cascade = CascadeType.ALL)
@IndexColumn(name = "drawer_position", base=1)
public List<Drawer> getDrawers() {
return drawers;
}

假如你忘了设置@IndexColumn,Hibernate会采用bag语义(译注:即允许重复元素的无序集合).
如果你既想使用bag语义,但是又不希望受制于其约束语义,可以考虑使用@CollectionId注解.

Hibernate注解支持true Map映射,如果没有设置@javax.persistence.MapKey,hibernate将key元素或嵌入式对象直接映射到他们所属的列.
要覆写默认的列,可以使用以下注解:
@org.hibernate.annotations.MapKey适用的key为基本类型
(默认为mapkey)或者嵌入式对象,
@org.hibernate.annotations.MapKey适用的key为实体.

双向关联的其中一端在使用@IndexColumn或者 @org.hibernate.annotations.MapKey[ManyToMany]注解需要考虑一些特殊的因素.如果子类存在某个属性映射到索引列,这种情况下是没有问题的,我们可以继续在集合映射的时候使用mappedBy,如下:
@Entity
public class Parent {
@OneToMany(mappedBy="parent")
@org.hibernate.annotations.MapKey(columns=@Column(name="name"))
private Map<String, Child> children;
...
}

@Entity
public class Parent {
...
@Basic
private String name;

@ManyToOne
@JoinColumn(name="parent_id", nullable=false)
private Parent parent;
...
}

但是,如果在子类中没有该属性,我们就不能认为这种关联是真正的双向关联(也就是在关联的一端有信息而另一端没有).因此在这种情况下,我们就不能使用mappedBy将其映射集合.取而代之为下面这种映射方式:
@Entity
public class Parent {
@OneToMany
@org.hibernate.annotations.MapKey(columns=@Column(name="name"))
@JoinColumn(name="parent_id", nullable=false)
private Map<String, Child> children;
...
}

@Entity
public class Parent {
...
@ManyToOne
@JoinColumn(name="parent_id", insertable=false, updatable=false, nullable=false)
private Parent parent;
...
}

注意在上面的映射中,关联的集合端负责更新外键.
另外一个有趣的特征就是可以给bag集合定义一个代理主键.通过这种方式优雅的去除了bag的缺点:update和remove操作更加有效率,每次查询或每个实体可以超过一个EAGER bag.该主键被保存在集合表的一个附加列,该列对于Java应用不可见.@CollectionId注解将一个集合标注为id bag,同时还可以覆写主键列,主键类型以及生成器策略.生成器策略可以是identity,也可以是应用中任何已定义的生成器的名字.

@Entity
@TableGenerator(name="ids_generator", table="IDS")
public class Passport {
...

@ManyToMany(cascade = CascadeType.ALL)
@JoinTable(name="PASSPORT_VISASTAMP")
@CollectionId(
columns = @Column(name="COLLECTION_ID"),
type=@Type(type="long"),
generator = "ids_generator"
)
private Collection<Stamp> visaStamp = new ArrayList();
...
}

Hibernate Annotations还支持核心类型集合(Integer, String, Enums, ......)、
可内嵌对象的集合,甚至基本类型数组.这就是所谓的元素集合.
元素集合可用@CollectionOfElements来注解(作为@OneToMany的替代).
为了定义集合表(译注:即存放集合元素的表,与下面提到的主表对应),要在关联属性上使用@JoinTable注解,joinColumns定义了介乎实体主表与集合表之间的连接字段(inverseJoincolumn是无效的且其值应为空).
对于核心类型的集合或基本类型数组,你可以在关联属性上用@Column来覆盖存放元素值的字段的定义.
你还可以用@AttributeOverride来覆盖存放可内嵌对象的字段的定义.
要访问集合元素,需要将该注解的name属性值设置为"element"("element"用于核心类型,而"element.serial"用于嵌入式对象的serial属性).要访问集合的index/key,则将该注解的name属性值设置为"key".
@Entity
public class Boy {
private Integer id;
private Set<String> nickNames = new HashSet<String>();
private int[] favoriteNumbers;
private Set<Toy> favoriteToys = new HashSet<Toy>();
private Set<Character> characters = new HashSet<Character>();

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

@CollectionOfElements
public Set<String> getNickNames() {
return nickNames;
}

@CollectionOfElements
@JoinTable(
table=@Table(name="BoyFavoriteNumbers"),
joinColumns = @JoinColumn(name="BoyId")
)
@Column(name="favoriteNumber", nullable=false)
@IndexColumn(name="nbr_index")
public int[] getFavoriteNumbers() {
return favoriteNumbers;
}

@CollectionOfElements
@AttributeOverride( name="element.serial", column=@Column(name="serial_nbr") )
public Set<Toy> getFavoriteToys() {
return favoriteToys;
}

@CollectionOfElements
public Set<Character> getCharacters() {
return characters;
}
...
}

public enum Character {
GENTLE,
NORMAL,
AGGRESSIVE,
ATTENTIVE,
VIOLENT,
CRAFTY
}

@Embeddable
public class Toy {
public String name;
public String serial;
public Boy owner;

public String getName() {
return name;
}

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

public String getSerial() {
return serial;
}

public void setSerial(String serial) {
this.serial = serial;
}

@Parent
public Boy getOwner() {
return owner;
}

public void setOwner(Boy owner) {
this.owner = owner;
}


public boolean equals(Object o) {
if ( this == o ) return true;
if ( o == null || getClass() != o.getClass() ) return false;

final Toy toy = (Toy) o;

if ( !name.equals( toy.name ) ) return false;
if ( !serial.equals( toy.serial ) ) return false;

return true;
}

public int hashCode() {
int result;
result = name.hashCode();
result = 29 * result + serial.hashCode();
return result;
}
}

在嵌入式对象的集合中,可以使用 @Parent注解嵌入式对象的某属性.
该属性指向该嵌入式对象所属的集合实体.

旧版的Hibernate Annotations用@OneToMany来标识集合元素.
由于语义矛盾,我们引入了@CollectionOfElements注解.
用@OneToMany来标识集合元素的这种旧有方式目前尚有效,
但是不推荐使用,而且在以后的发布版本中不再支持这种方式.

为了优化数据库访问,你可以激活所谓的Hibernate二级缓存.该缓存是可以按每个实体和集合进行配置的.
@org.hibernate.annotations.Cache定义了缓存策略及给定的二级缓存的范围.
此注解适用于根实体(非子实体),还有集合.

@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();
String region() default "";
String include() default "all";
)

usage: 给定缓存的并发策略(NONE,READ_ONLY, NONSTRICT_READ_WRITE, READ_WRITE, TRANSACTIONAL)

region (可选的):缓存范围(默认为类的全限定类名或是集合的全限定角色名)

include (可选的):值为all时包括了所有的属性(proterty),为non-lazy时仅含非延迟属性(默认值为all)

Hibernate具有在数据上应用任意过滤器的能力,可在运行期应用于一个给定的session.过滤器需要事先定义好.

@org.hibernate.annotations.FilterDef 或@FilterDefs 定义过滤器声明,为同名过滤器所用.
过滤器声明带有一个name()和一个parameters()数组. 参数提供了在运行时调整过滤器行为的能力,过滤器通过@ParamDef注解定义,该注解包含name和type,你还可以为给定的@FilterDef定义一个defaultCondition()参数,当所有的@Filter中没有任何定义时,可使用该参数定义缺省条件.
@FilterDef (s)可以在类或包一级进行定义.

现在我们来定义应用于实体或集合加载时的SQL过滤器子句.我们使用@Filter,并将其置于实体或集合元素上.

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

当这些集合使用关联表来表示关系的时候,你可能需要对于关联表或者目标实体表应用过滤条件.使用@Filter注解可以在目标实体上添加改类约束.
但是如果你打算在关联表上使用,就需要使用@FilterJoinTable注解.

@OneToMany
@JoinTable
//filter on the target entity table
@Filter(name="betweenLength", condition=":minLength <= length and :maxLength >= length")
//filter on the association table
@FilterJoinTable(name="security", condition=":userlevel >= requredLevel")
public Set<Forest> getForests() { ... }

由于Hibernate引入了
@org.hibernate.annotations.NamedQuery,
@org.hibernate.annotations.NamedQueries,
@org.hibernate.annotations.NamedNativeQuery 和
@org.hibernate.annotations.NamedNativeQueries 命名式查询,
因此Hibernate在命名式查询上比EBJ3规范中所定义的命名式查询提供了更多的特性.
他们在标准版中添加了可作为替代品的一些属性(attributes):
flushMode: 定义查询的刷新模式(Always, Auto, Commit或Never)
cacheable: 查询该不该被缓存
cacheRegion: 若查询已被缓存时所用缓存的范围
fetchSize: 针对该查询的JDBC statement单次获取记录的数目
timeout: 查询超时
callable: 仅用于本地化查询(native query),对于存储过程设为true
comment: 一旦激活注释功能,我们会在向数据库交送查询请求时看到注释
cacheMode: 缓存交护模式(get, ignore,normal,或refresh)
readOnly: 不管是否从查询获取元素都是在只读模式下

通过@QueryHint注解可以在
@javax.persistence.NamedQuery
中设置hints.另一个重要的优势是可以将这些注解应用到包上[/size]