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();

}