Hibernate Annotations--实体Bean

这里整理下实体bean的注解规范以及Hibernate特有的扩展

现在EJB3实体Bean是纯粹的POJO.实际上这表达了和Hibernate持久化实体对象同样的概念. 它们的映射都通过JDK5.0注解来定义(EJB3规范中的XML描述语法至今还没有最终定下来). 注解分为两个部分,分别是逻辑映射注解和物理映射注解, 通过逻辑映射注解可以描述对象模型,类之间的关系等等, 而物理映射注解则描述了物理的schema,表,列,索引等等. 下面我们在代码中将混合使用这两种类型的注解.

EJB3注解的API定义在javax.persistence.*包里面. 大部分和JDK5兼容的IDE(象Eclipse, IntelliJ IDEA 和Netbeans等等)都提供了注解接口和属性的自动完成功能. (这些不需要IDE提供特别的EJB3支持模块,因为EJB3注解是标准的JDK5注解)

---------------------------------------------------------------------------

声明实体bean

每一个持久化的pojo类就是一个bean,我们通过在类中使用@Entity注释来进行声明！

例如：

package com.bubble.entity;

import javax.persistence.Entity;
import javax.persistence.Id;

/**
 * @author bubble
 *
 */
@Entity
public class Product {
	
	private int id;
	
	private String name;
	
	private String qq;
	

	public void setId(int id) {
		this.id = id;
	}
	@Id
	public int getId() {
		return id;
	}


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

	public String getName() {
		return name;
	}

	public void setQq(String qq) {
		this.qq = qq;
	}

	public String getQq() {
		return qq;
	}

}

这里Product即被注释为一个持久类！

在对一个类进行注解时,你可以选择对它的的属性或者方法进行注解,根据你的选择,Hibernate的访问类型分别为 field或property.（成员变量和属性）

EJ3规范要求在需要访问的元素上进行注解声明,例如,如果访问类型为 property就要在getter方法上进行注解声明,

如果访问类型为 field就要在字段上进行注解声明.应该尽量避免混合使用这两种访问类型. Hibernate根据@Id 或 @EmbeddedId的位置

来判断访问类型.

hibernate注解在field上还是property上好呢？

《中文版的 Expert one-on-one J2EE Development without EJB》第283页下面有这样的一句话：

根据译者的观察，如果将SETTER声明为PRIVATE，会导致HIBERNATE无法使用CGLIB优化的反射机制，只能通过标准的JAVA反射机制为持久对象-----请注意，是整个对象的所有字段，而非仅仅那个声明为PRIVATE的字段----赋值。如果持久对象有较多字段，这个过程将相当耗时。

--------------------------------------------------------

《中文版 POJOs in Action》第197页：

表6.1映射成员变量和属性的长处与短处

长处 短处

Property 封装，Accessor可转换值,默认支持 必须定义Accessor（但可以为private）

Field 无须定义Accessor----特别是setter方法 封装少，非默认支持，映射更烦琐

--------------------------------------------------------------------

如果hibernate实体有继承关系
那么父类中的标注写到方法上，子类写到属性上，那么则会hibernate映射会有问题，写到哪里都可以，但是千万要统一。

---------------------------------------------------------------------------------------

定义表(Table)

@Table属于类级别的注解，通过@Table可以指明该类对应的数据库中的表名，目录 (catalog)和schema的名字！

之前也提到过，如果没有定义@Table，则系统使用默认，即与类名相同。

例：在类名和表名不相同的情况下，你需要使用@Table来定义类对应的表

@Entity
@Table(name="t_product")
public class Product implements Serializable {
...
            

@Table元素包括了一个schema和一个catalog属性,如果需要可以指定相应的值. 结合使用@UniqueConstraint注解可以定义表的唯一约束(unique constraint) (对于绑定到单列的唯一约束,请参考@Column注解)

@Table(name="t_product",
		    uniqueConstraints = {@UniqueConstraint(columnNames={"id", "qq"})}
		)

以上代码中，为数据库表t_product定义了字段id,qq为唯一约束，columnName数组中定义为数据库中的字段名！

PS：Hibernate在NamingStrategy的实现中定义了逻辑列名. 默认的EJB3命名策略将物理字段名当作逻辑字段名来使用. 注意该字段名和它对应的属性名可能不同(如果字段名是显式指定的话). 除非你重写了NamingStrategy,否则不用担心这些区别.

乐观锁定版本控制

你可以在实体bean中使用@Version注解,通过这种方式可添加对乐观锁定的支持:

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

上面这个例子中,version属性将映射到OPTLOCK列, entity manager使用该字段来检测更新冲突(防止更新丢失,请参考last-commit-wins策略).

根据EJB3规范,version列可以是numeric类型(推荐方式)也可以是timestamp类型. Hibernate支持任何自定义类型,只要该类型实现了UserVersionType.

-------------------------------------------------------------------------

映射简单属性

声明基本的属性映射

Every non static non transient property (field or method) of an entity bean is considered persistent, unless you annotate it as@Transient. Not having an annotation for your property is equivalent to the appropriate@Basicannotation. The@Basicannotation allows you to declare the fetching strategy for a property:

实体bean中所有的非static非transient的属性都可以被持久化, 除非你将其注解为@Transient.所有没有定义注解的属性等价于在其上面添加了@Basic注解. 通过@Basic注解可以声明属性的获取策略(fetch strategy)：

public transient int counter; //transient property

private String firstname; //persistent property

@Transient
String getLengthInMeter() { ... } //transient property

String getName() {... } // persistent property

@Basic
int getLength() { ... } // persistent property

@Basic(fetch = FetchType.LAZY)
String getDetailedComment() { ... } // persistent property

@Temporal(TemporalType.TIME)
java.util.Date getDepartureTime() { ... } // persistent property           

@Enumerated(EnumType.STRING)
Starred getNote() { ... } //enum persisted as String in database

上面这个例子中,counter是一个transient的字段,lengthInMeter的getter方法被注解为@Transient, entity manager将忽略这些字段和属性. 而name,length,firstname这几个属性则是被定义为可持久化和可获取的.对于简单属性来说,默认的获取方式是即时获取(early fetch). 当一个实体Bean的实例被创建时,Hibernate会将这些属性的值从数据库中提取出来,保存到Bean的属性里. 与即时获取相对应的是延迟获取(lazy fetch).如果一个属性的获取方式是延迟获取 (比如上面例子中的detailedComment属性), Hibernate在创建一个实体Bean的实例时,不会即时将这个属性的值从数据库中读出. 只有在该实体Bean的这个属性第一次被调用时,Hibernate才会去获取对应的值. 通常你不需要对简单属性设置延迟获取(lazy simple property),千万不要和延迟关联获取(lazy association fetch)混淆了 (译注:这里指不要把lazy simple property和lazy association fetch混淆了).

注意

为了启用属性级的延迟获取,你的类必须经过特殊处理(instrumented)： 字节码将被织入原始类中来实现延迟获取功能, 详情参考Hibernate参考文档.如果不对类文件进行字节码特殊处理, 那么属性级的延迟获取将被忽略.

推荐的替代方案是使用EJB-QL或者Criteria查询的投影(projection)功能.

Hibernate和EJB3都支持所有基本类型的属性映射. 这些基本类型包括所有的Java基本类型,及其各自的wrapper类和serializable类. Hibernate Annotations还支持将内置的枚举类型映射到一个顺序列(保存了相应的序列值) 或一个字符串类型的列(保存相应的字符串).默认是保存枚举的序列值, 但是你可以通过@Enumerated注解来进行调整(见上面例子中的note属性).

在核心的Java API中并没有定义时间精度(temporal precision). 因此处理时间类型数据时,你还需要定义将其存储在数据库中所预期的精度. 在数据库中,表示时间类型的数据有DATE,TIME, 和TIMESTAMP三种精度(即单纯的日期,时间,或者两者兼备). 可使用@Temporal注解来调整精度.

@Lob注解表示属性将被持久化为Blob或者Clob类型, 具体取决于属性的类型,java.sql.Clob,Character[],char[]和java.lang.String这些类型的属性都被持久化为Clob类型, 而java.sql.Blob,Byte[],byte[]和 serializable类型则被持久化为Blob类型.

@Lob
public String getFullText() {
    return fullText;
}

@Lob 
public byte[] getFullCode() {
    return fullCode;
}
 

如果某个属性实现了java.io.Serializable同时也不是基本类型, 并且没有在该属性上使用@Lob注解, 那么Hibernate将使用自带的serializable类型.

声明列属性

使用@Column注解可将属性映射到列. 使用该注解来覆盖默认值(关于默认值请参考EJB3规范). 在属性级使用该注解的方式如下：

• 不进行注解

• 和@Basic一起使用

• 和@Version一起使用

• 和@Lob一起使用

• 和@Temporal一起使用

• 和@org.hibernate.annotations.CollectionOfElements一起使用 (只针对Hibernate )

@Entity
public class Flight implements Serializable {
...
@Column(updatable = false, name = "flight_name", nullable = false, length=50)
public String getName() { ... }
            

在上面这个例子中,name属性映射到flight_name列. 该字段不允许为空,长度为50,并且是不可更新的(也就是属性值是不变的).

上面这些注解可以被应用到正规属性上例如@Id或@Version属性.

@Column(
    name="columnName";                                (1)
    boolean unique() default false;                   (2)
    boolean nullable() default true;                  (3)
    boolean insertable() default true;                (4)
    boolean updatable() default true;                 (5)
    String columnDefinition() default "";             (6)
    String table() default "";                        (7)
    int length() default 255;                         (8)
    int precision() default 0; // decimal precision   (9)
    int scale() default 0; // decimal scale

(1)	name可选,列名(默认值是属性名)
(2)	unique可选,是否在该列上设置唯一约束(默认值false)
(3)	nullable可选,是否设置该列的值可以为空(默认值false)
(4)	insertable可选,该列是否作为生成的insert语句中的一个列(默认值true)
(5)	updatable可选,该列是否作为生成的update语句中的一个列(默认值true)
(6)	columnDefinition可选: 为这个特定列覆盖SQL DDL片段 (这可能导致无法在不同数据库间移植)
(7)	table可选,定义对应的表(默认为主表)
(8)	length可选,列长度(默认值255)
(8)	precision可选,列十进制精度(decimal precision)(默认值0)
(10)	scale可选,如果列十进制数值范围(decimal scale)可用,在此设置(默认值0)

---------------------------------------

嵌入式对象(又名组件)

在实体中可以定义一个嵌入式组件(embedded component), 甚至覆盖该实体中原有的列映射. 组件类必须在类一级定义@Embeddable注解. 在特定的实体的关联属性上使用@Embedded和@AttributeOverride注解可以覆盖该属性对应的嵌入式对象的列映射：

@Entity
public class Person implements Serializable {

    // Persistent component using defaults
    Address homeAddress;

    @Embedded
    @AttributeOverrides( {
            @AttributeOverride(name="iso2", column = @Column(name="bornIso2") ),
            @AttributeOverride(name="name", column = @Column(name="bornCountryName") )
    } )
    Country bornIn;
    ...
}
            

@Embeddable
public class Address implements Serializable {
    String city;
    Country nationality; //no overriding here
}
            

@Embeddable
public class Country implements Serializable {
    private String iso2;
    @Column(name="countryName") private String name;

    public String getIso2() { return iso2; }
    public void setIso2(String iso2) { this.iso2 = iso2; }

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

嵌入式对象继承其所属实体中定义的访问类型 (注意:这可以通过使用Hibernate提供的@AccessType注解来覆盖原有值)(请参考Hibernate Annotation Extensions).

在上面的例子中,实体beanPerson有两个组件属性, 分别是homeAddress和bornIn. 我们可以看到homeAddress属性并没有注解. 但是Hibernate自动检测其对应的Address类中的@Embeddable注解, 并将其看作一个持久化组件.对于Country中已映射的属性, 则使用@Embedded和@AttributeOverride注解来覆盖原来映射的列名. 正如你所看到的,Address对象中还内嵌了Country对象, 这里和homeAddress一样使用了Hibernate和EJB3自动检测机制. 目前EJB3规范还不支持覆盖多层嵌套(即嵌入式对象中还包括其他嵌入式对象)的列映射. 不过Hibernate通过在表达式中使用"."符号表达式提供了对此特征的支持.

    @Embedded
    @AttributeOverrides( {
            @AttributeOverride(name="city", column = @Column(name="fld_city") ),
            @AttributeOverride(name="nationality.iso2", column = @Column(name="nat_Iso2") ),
            @AttributeOverride(name="nationality.name", column = @Column(name="nat_CountryName") )
            //nationality columns in homeAddress are overridden
    } )
    Address homeAddress;

Hibernate注解支持很多EJB3规范中没有明确定义的特性. 例如,可以在嵌入式对象上添加@MappedSuperclass注解, 这样可以将其父类的属性持久(详情请查阅@MappedSuperclass).

Hibernate现在支持在嵌入式对象中使用关联注解(如@*ToOne和@*ToMany). 而EJB3规范尚不支持这样的用法。你可以使用@AssociationOverride注解来覆写关联列.

在同一个实体中使用两个同类型的嵌入对象, 其默认列名是无效的:至少要对其中一个进行明确声明. Hibernate在这方面走在了EJB3规范的前面, Hibernate提供了NamingStrategy, 在使用Hibernate时, 通过NamingStrategy你可以对默认的机制进行扩展.DefaultComponentSafeNamingStrategy在默认的EJB3NamingStrategy上进行了小小的提升, 允许在同一实体中使用两个同类型的嵌入对象而无须额外的声明.

无注解之属性的默认值

如果某属性没有注解,该属性将遵守下面的规则:

• 如果属性为单一类型,则映射为@Basic
• 否则,如果属性对应的类型定义了@Embeddable注解,则映射为@Embedded
• 否则,如果属性对应的类型实现了Serializable, 则属性被映射为@Basic并在一个列中保存该对象的serialized版本
• 否则,如果该属性的类型为java.sql.Clob 或 java.sql.Blob,则作为@Lob并映射到适当的LobType.

-------------------------------------

映射主键属性

使用@Id注解可以将实体bean中的某个属性定义为标识符(identifier). 该属性的值可以通过应用自身进行设置, 也可以通过Hiberante生成(推荐). 使用@GeneratedValue注解可以定义该标识符的生成策略:

• AUTO - 可以是identity column类型,或者sequence类型或者table类型,取决于不同的底层数据库.
• TABLE - 使用表保存id值
• IDENTITY - identity column
• SEQUENCE - sequence

和EJB3规范相比,Hibernate提供了更多的id生成器.详情请查阅Hibernate Annotation Extensions.

下面的例子展示了使用SEQ_STORE配置的sequence生成器

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

下面这个例子使用的是identity生成器

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

AUTO生成器适用于可移植的应用(在多个DB间切换). 多个@Id可以共享同一个identifier生成器,只要把generator属性设成相同的值就可以了. 通过@SequenceGenerator和@TableGenerator,你可以配置不同的identifier生成器. 每一个identifier生成器都有自己的适用范围,可以是应用级(application level)和类一级(class level). 类一级的生成器在外部是不可见的, 而且类一级的生成器可以覆盖应用级的生成器. 应用级的生成器则定义在包一级(package level)(如package-info.java):

@javax.persistence.TableGenerator(
    name="EMP_GEN",
    table="GENERATOR_TABLE",
    pkColumnName = "key",
    valueColumnName = "hi"
    pkColumnValue="EMP",
    allocationSize=20
)
@javax.persistence.SequenceGenerator(
    name="SEQ_GEN",
    sequenceName="my_sequence"
)
package org.hibernate.test.metadata;
         

如果在org.hibernate.test.metadata包下面的package-info.java文件用于初始化EJB配置, 那么该文件中定义的EMP_GEN和SEQ_GEN都是应用级的生成器.EMP_GEN定义了一个使用hilo算法 (max_lo为20)的id生成器(该生成器将id的信息存在数据库的某个表中.). id的hi值保存在GENERATOR_TABLE中. 在该表中pkColumnName"key"等价于pkColumnValue"EMP", 而valueColumnName"hi"中存储的是下一个要使用的最大值.

SEQ_GEN则定义了一个sequence 生成器, 其对应的sequence名为my_sequence. 注意目前Hibernate Annotations还不支持sequence 生成器中的initialValue和allocationSize参数.

下面这个例子展示了定义在类范围(class scope)的sequence生成器:

@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; }
}
         

在这个例子中,Store类使用名为my_sequence的sequence,并且SEQ_STORE 生成器对于其他类是不可见的. 注意在org.hibernate.test.metadata.id包下的测试代码有更多演示Hibernate Annotations用法的例子..

下面是定义组合主键的几种语法:

• 将组件类注解为@Embeddable,并将组件的属性注解为@Id
• 将组件的属性注解为@EmbeddedId
• 将类注解为@IdClass,并将该实体中所有属于主键的属性都注解为@Id

对于EJB2的开发人员来说@IdClass是很常见的, 但是对于Hibernate的用户来说就是一个崭新的用法. 组合主键类对应了一个实体类中的多个字段或属性, 而且主键类中用于定义主键的字段或属性和 实体类中对应的字段或属性在类型上必须一致.下面我们看一个例子:

@Entity
@IdClass(FootballerPk.class)
public class Footballer {
    //part of the id key
    @Id public String getFirstname() {
        return firstname;
    }

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

    //part of the id key
    @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;
    }

    //appropriate equals() and hashCode() implementation
}

@Embeddable
public class FootballerPk implements Serializable {
    //same name and type as in Footballer
    public String getFirstname() {
        return firstname;
    }

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

    //same name and type as in Footballer
    public String getLastname() {
        return lastname;
    }

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

    //appropriate equals() and hashCode() implementation
}

如上,@IdClass指向对应的主键类.

Hibernate支持在组合标识符中定义关联(就像使用普通的注解一样),而EJB3规范并不支持此类用法.

@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支持三种类型的继承映射:

• 每个类一张表(Table per class)策略: 在Hibernate中对应<union-class>元素:
• 每个类层次结构一张表(Single table per class hierarchy)策略:在Hibernate中对应<subclass>元素
• 连接的子类(Joined subclasses)策略:在Hibernate中对应 <joined-subclass>元素

你可以用@Inheritance注解来定义所选择的策略. 这个注解需要在每个类层次结构(class hierarchy) 最顶端的实体类上使用.

注意

目前还不支持在接口上进行注解.

-----------------------------------------------------------------

每个类一张表

这种策略有很多缺点(例如:多态查询和关联),EJB3规范, Hibernate参考手册, Hibernate in Action,以及其他许多地方都对此进行了描述和解释. Hibernate使用SQL UNION查询来实现这种策略. 通常使用场合是在一个继承层次结构的顶端:

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

这种策略支持双向的一对多关联. 这里不支持IDENTITY生成器策略,因为id必须在多个表间共享. 当然,一旦使用这种策略就意味着你不能使用AUTO生成器和IDENTITY生成器.

待续， http://docs.jboss.org/hibernate/annotations/3.4/reference/zh_cn/html_single/

用的时候再详细整理