EJB3持久化规范（第八章元数据注释符）

1 元数据注释符
本章和第9章定义本规范引入的元数据注释符。
在第10章定义的XML Schema为元数据注释符的使用提供了可选方案。
注释符都在javax.persistence包内。
1.1 Entity
Entity注释符指明一个类是实体。这个注释符用于实体类。
name注释符元素缺省是实体类的名字（不是全称）。名称用于在查询中引用这个实体。这个名称不能是EJB QL的保留字。
@Target(TYPE) @Retention(RUNTIME)
public @interface Entity {
String name() default "";
}
1.2回调注释符
EntityListeners注释符指定实体类和被影射的超类的回调监听器。EntityListeners可以用于实体类和被映射的超类。
@Target({TYPE}) @Retention(RUNTIME)
public @interface EntityListeners {
Class[] value();
}
ExcludeSuperClassListeners注释符指定从实体类（或被映射超类）和它的子类中排除那些超类监听器。
@Target({TYPE}) @Retention(RUNTIME)
public @interface ExcludeSuperclassListeners {
}
ExcludeDefaultListeners指定从实体类（或被映射超类）和它的子类中排除缺省监听器。
@Target({TYPE}) @Retention(RUNTIME)
public @interface ExcludeDefaultListeners {
}
下面的注释符用于指定对应生命周期事件的回调方法。这些注释符可以用于任意实体类、被映射超类或实体监听器类的方法。
@Target({METHOD}) @Retention(RUNTIME)
public @interface PrePersist {}
@Target({METHOD}) @Retention(RUNTIME)
public @interface PostPersist {}
@Target({METHOD}) @Retention(RUNTIME)
public @interface PreRemove {}
@Target({METHOD}) @Retention(RUNTIME)
public @interface PostRemove {}
@Target({METHOD}) @Retention(RUNTIME)
public @interface PreUpdate {}
@Target({METHOD}) @Retention(RUNTIME)
public @interface PostUpdate {}
@Target({METHOD}) @Retention(RUNTIME)
public @interface PostLoad {}
1.3 用于查询的注释符
1.3.1 NamedQuery
NamedQuery注释符用于指定一个使用Java持久化查询语言的命名查询。当使用EntityManager的创建查询对象的方法时，元素name用于指向一个查询。NamedQuery和NamedQueries注释符可以用于实体类和被映射超类。
@Target({TYPE}) @Retention(RUNTIME)
public @interface NamedQuery {
String name();
String query();
QueryHint[] hints() default {};
}
@Target({}) @Retention(RUNTIME)
public @interface QueryHint {
String name();
String value();
}
@Target({TYPE}) @Retention(RUNTIME)
public @interface NamedQueries {
NamedQuery[] value ();
}
1.3.2 NamedNativeQuery
NamedNativeQuery用于指定一个本地SQL命名查询。当使用EntityManager的创建查询对象的方法时，元素name用于指向那个查询。元素resultClass指向结果类；元素resultSetMapping的值是定义在元数据中的SqlResultSetMapping的名字。NamedNativeQuery和NamedNativeQueries可以用于实体或被映射超类。
@Target({TYPE}) @Retention(RUNTIME)
public @interface NamedNativeQuery {
String name();
String query();
QueryHint[] hints() default {};
Class resultClass() default void.class;
StringresultSetMapping()default"";//nameofSqlResultSetMap-
ping
}
@Target({TYPE}) @Retention(RUNTIME)
public @interface NamedNativeQueries {
NamedNativeQuery[] value ();
}
1.3.3 用于SQL查询结果集映射的注释符
SqlResultMapping注释符用于指定本地SQL查询结果的映射。
@Target({TYPE}) @Retention(RUNTIME)
public @interface SqlResultSetMapping {
String name();
EntityResult[] entities() default {};
ColumnResult[] columns() default {};
}
@Target({TYPE}) @Retention(RUNTIME)
public @interface SqlResultSetMappings {
SqlResultSetMapping[] value();
}
元素name是结果集映射的名字，这个名字用于在Query API的方法内引用这个结果集。元素entities和columns用于指定实体映射并对应结果值。
@Target({}) @Retention(RUNTIME)
public @interface EntityResult {
Class entityClass();
FieldResult[] fields() default {};
String discriminatorColumn() default "";
}
元素entityClass指定结果集的类。
元素fields用于映射SELECT中的列和实体的属性或字段。
元素discriminatorColumn用于指定SELECT中用于区分实体类型的列的列名（或别名）。（译者注：对于继承关系的映射，父类和子类映射到一个数据表的情况）。
@Target({}) @Retention(RUNTIME)
public @interface FieldResult {
String name();
String column();
}
元素name是类的持久化字段或属性的名字。
在这些注释符内使用的列名都指向SELECT语句中的列名——也就是说，如果可以的话就是列的别名。
@Target({}) @Retention(RUNTIME)
public @interface ColumnResult {
String name();
}
1.4 引用EntityManager和EntityManagerFactory
这些注释符用于表达对实体管理器和实体管理器工厂的依赖。
1.4.1 PersistenceContext
PersistenceContext用于表达依赖容器管理的实体管理器持久化上下文。
元素name指的是在环境的引用上下文内中可以获得的实体管理器，但当使用依赖注入时不需要使用name。
可选元素unitName指向持久化单元的名字。如果指定了unitName元素，那么它的名字必须和在JNDI中的实体管理器的持久化单元的名字一致。
元素type指定使用的是事务范围的持久化上下文，还是扩展的持久化上下文。如果没有指定type，则使用事务范围的持久化上下文。
可选的元素properties可以用于指定容器或持久化提供者的属性。特定提供商的属性可以包含在属性集中，当容器创建实体管理器时，这些属性被容器传递到持久化提供商。提供商不能识别的属性必须被忽略。
@Target({TYPE, METHOD, FIELD}) @Retention(RUNTIME)
public @interface PersistenceContext{
String name() default "";
String unitName() default "";
PersistenceContextType type default TRANSACTION;
PersistenceProperty[] properties() default {};
}
public enum PersistenceContextType {
TRANSACTION,
EXTENDED
}
@Target({}) @Retention(RUNTIME)
public @interface PersistenceProperty {
String name();
String value();
}
@Target({TYPE}) @Retention(RUNTIME)
public @interface PersistenceContexts{
PersistenceContext[] value();
}
1.4.2 PersistenceUnit
PersistenceUnit用于表达依赖的实体管理器工厂。
元素name指向可以在环境引用上下文获得的实体管理器工厂。当使用依赖注入时，不需要指定name。
可选元素unitName指向在persistence.xml中定义的持久化单元的名字。如果指定unitName，则可以在JNDI中获得的实体管理器工厂的持久化单元必须和这个名字一致。
@Target({TYPE, METHOD, FIELD}) @Retention(RUNTIME)
public @interface PersistenceUnit{
String name() default "";
String unitName() default "";
}
@Target(TYPE) @Retention(RUNTIME)
public @interface PersistenceUnits{
PersistenceUnit[] value();
}