EJB3 简化的API规范（第十章注释符）

1    注释符

1.1          特定类型bean的注释符

1.1.1        无状态会话bean

Stateless 用于标明企业bean 是一个无状态会话bean 。Stateless 注释符用于bean 的class 。

@Target(TYPE) @Retention(RUNTIME)

public @interface Stateless {

String name() default "";

String mappedName() default "";

String description() default "";

}

元素name 缺省是bean 类的简称（不带包名）。不管事是显式指定的还是缺省的名字，这个名字在ejb-jar 中必须是唯一的。

元素mappedName 是特定产品的名字，这个名字用于映射会话bean 。使用映射名字的应用是不可移植的。

1.1.2        有状态会话bean

Stateful 注释符指明企业bean 是有状态会话bean 。Stateful 注释符应用于bean 的class 上。

@Target(TYPE) @Retention(RUNTIME)

public @interface Stateful {

String name() default "";

String mappedName() default "";

String description() default "";

}

元素name 缺省是bean 类的简称（不带包名）。不管事是显式指定的还是缺省的名字，这个名字在ejb-jar 中必须是唯一的。

元素mappedName 是特定产品的名字，这个名字用于映射会话bean 。使用映射名字的应用是不可移植的。

1.1.2.1         有状态会话bean的Init注释符

Init 注释符用于指定bean 类中与EJB2.1 EJBHome 和/ 或EJBLocalHome 的create 等价的方法，用于适配EJB2.1 EJBHome 和/ 或EJBLocalHome 。Init 方法的返回类型必须是void ，而且它的参数类型必须和引用的create 方法的参数完全一致。

@Target(METHOD) @Retention(RUNTIME)

public @interface Init{

String value() default "";

}

当Init 注释符用于适配有多个create 方法的有状态会话bean 的home 接口时，必须指定value 元素。它指定了适配的home 接口的对应的create 方法的名字。

只有当有状态会话bean 有RemoteHome 或LocalHome 接口时才需要指定Init 方法。如果有产生混淆的可能性，则必须指定适配的create 方法的名字。

1.1.2.2         有状态会话bean的Remove注释符

Remove 注释符用于指定有状态会话bean 的清除方法。这个方法完成后容器会销毁这个bean ，在调用这个方法之前会调用bean 的PreDestroy 方法。retainIfException 元素可以防止这个方法由于应用异常而异常终止。

@Target(METHOD) @Retention(RUNTIME)

public @interface Remove{

boolean retainIfException() default false;

}

1.1.3        消息驱动bean

MessageDriven 注释符指明一个企业bean 是一个消息驱动bean 。这个注释符应用到bean 的class 。

元素name 缺省是bean 类的简称（不带包名）。不管事是显式指定的还是缺省的名字，这个名字在ejb-jar 中必须是唯一的。

元素mappedName 是特定产品的名字，这个名字用于映射会话bean 。使用映射名字的应用是不可移植的。

元素messageListenerInterface 指定bean 的消息监听器接口。如果bean 没有实现消息监听期接口或实现了除java.io.Serializable ，java.io.Externalizable 和javax.ejb 包内的接口外的多个接口，则必须指定messageListenerInterface 。

@Target(TYPE) @Retention(RUNTIME)

public @interface MessageDriven {

String name() default "";

Class messageListenerInterface() default Object.class;

ActivationConfigProperty[] activationConfig() default {};

String mappedName() default "";

String description() default "";

}

@Target({}) @Retention(RUNTIME)

public @interface ActivationConfigProperty {

 String propertyName();

 String propertyValue();

}

1.2          指定Local或Remote接口的注释符

Remote 和Local 注释符只用于会话bean 和他们的接口。

Remote 注释符用于会话bean 或远程业务接口。

Local 注释符用于会话bean 或本地业务接口。

当bean 实现了除了java.io.Serializable ，java.io.Externalizable 一家javax.ejb 包的接口外多个接口时，才需要使用Local 。

只有在bean 上使用注释符的时候才指定元素value 。只有当bean 实现了除了java.io.Serializable ，java.io.Externalizable 和javax.ejb 包内的接口外多个接口时才需要指定value 。

@Target(TYPE) @Retention(RUNTIME)

public @interface Remote {

Class[]value()default{};//listofremotebusinessinterfaces

}

@Target(TYPE) @Retention(RUNTIME)

public @interface Local {

Class[] value() default {}; // list of local business interfaces

}

1.3          支持EJB2.1和早期客户端实图的注释符

RemoteHome 和LocalHome 只可以应用到会话bean 。

这些注释符只应用于EJB3.0 ，用于适配EJB2.1 。也可以用于使用EJB2.1 API 的bean 。

@Target(TYPE) @Retention(RUNTIME)

public @interface RemoteHome {

 Class value();   // home interface

}

@Target(TYPE) @Retention(RUNTIME)

public @interface LocalHome {

 Class value();   // local home interface

}

1.4          TransactionManagement

TransactionManagement 注释符指定会话bean 或消息驱动bean 的事务管理分隔类型。如果会话bean 或消息驱动bean 没有指定TransactionManagement ，那么使用容器管理的事务分隔。

@Target(TYPE) @Retention(RUNTIME)

public @interface TransactionManagement {

TransactionManagementType value()

default TransactionManagementType.CONTAINER;

}

枚举TransactionManagementType 用于指定使用容器管理的事务管理还是bean 管理的事务管理。

public enum TransactionManagementType {

 CONTAINER,

 BEAN

}

1.5          务属性

TransactionAttribute 注释符指定容器是否在事务上下文中调用业务方法。事务属性的语义在“EJB Core 协议和需求”的“支持事务”一章中描述。

TransactionAttribute 只能在使用容器管理的事务分隔时指定。这个注释符可以指定在bean 的class 和/ 或类的业务接口方法上。在bean 的class 上指定TransactionAttribute 意味着事务属性应用到所有的业务接口方法。指定在方法上则意味着只应用到该方法上。如果两个地方都指定了TransactionAttribute ，且属性值不同，那么方法上的TransactionAttribute 覆盖类上的事务属性。

TransactionAttribute 注释符的值由枚举TransactionAttributeType 指定。

如果没有指定TransactionAttribute ，并且bean 使用容器管理事务分隔，那么使用REQUIRED 事务属性。

public enum TransactionAttributeType {

   MANDATORY,

   REQUIRED,

   REQUIRES_NEW,

   SUPPORTS,

   NOT_SUPPORTED,

   NEVER

}

@Target({METHOD, TYPE}) @Retention(RUNTIME)

public @interface TransactionAttribute {

 TransactionAttributeType value()

default TransactionAttributeType.REQUIRED;

}

1.6          拦截器和生命周期回调

Javax.interceptor.Interceptors 注释符用于为bean 指定一个或多个拦截器类。Interceptiors 注释符应用bean 的class 或bean 的业务方法上。

package javax.interceptor;

@Target({TYPE, METHOD}) @Retention(RUNTIME)

public @interface Interceptors {

Class[] value();

}

Javax.interceptor.AroundInvoke 注释符用于指定拦截器方法。

package javax.interceptor;

@Target({METHOD}) @Retention(RUNTIME)

public @interface AroundInvoke {}

当在bean 上使用javax.interceptor.ExcludeDefaultInterceptors 注释符时，是指为bean 的所有业务方法排除缺省的拦截器调用。当在业务方法上指定时，只是为这个方法排除缺省的拦截器。

package javax.interceptor;

@Target({TYPE, METHOD}) @Retention(RUNTIME)

public @interface ExcludeDefaultInterceptors {}

javax.interceptor.ExcludeClassInterceptors 注释符为方法排除类级别上的拦截器调用（但不是缺省拦截器）。

package javax.interceptor;

@Target({METHOD}) @Retention(RUNTIME)

public @interface ExcludeClassInterceptors {}

javax.annotation.PostConstruct ，javax.annotation.PreDestroy 和javax.ejb.PostActivate 和javax.ejb.PrePassivate 注释符指定生命周期回调方法。

package javax.annotation;

@Target({METHOD}) @Retention(RUNTIME)

public @interface PostConstruct {}

package javax.annotation;

@Target({METHOD}) @Retention(RUNTIME)

public @interface PreDestroy {}

package javax.ejb;

@Target({METHOD}) @Retention(RUNTIME)

public @interface PostActivate {}

package javax.ejb;

@Target({METHOD}) @Retention(RUNTIME)

public @interface PrePassivate {}

1.7          Timeout

Timeout 注释符用于指定企业bean 的超时方法。

@Target({METHOD}) @Retention(RUNTIME)

public @interface Timeout {}

1.8          异常

ApplicationException 注释符用于指定一个应该被直接报告给客户端的应用异常（例如，解压）。ApplicationException 既可以是可被检查的也可以是不被检查的异常。rollback 元素用于指明容器是否必须在异常抛出时回滚事务。

@Target(TYPE) @Retention(RUNTIME)

public @interface ApplicationException {

boolean rollback() default false;

}

1.9          安全和方法授权

下面所述的与安全相关的注释符在javax.annotation.security 包内。它们在【JSR-250:java 平台的共用注释符。http://jcp.org/en/jsr/detail?id=250 】中详细描述，放在这里只是一个参考。

1.9.1        安全角色引用

DeclareRoles 注释符用于生命在企业bean 的代码中引用的安全角色。

package javax.annotation.security;

@Target({TYPE}) @Retention(RUNTIME)

public @interface DeclareRoles {

String[] value();

}

1.9.2        方法授权

RolesAllowed 注释符指定安全角色可以调用的bean 方法。RolesAllowed 注释符的值是一个安全角色名称的列表。

这个注释符可以指定在bean 的类上，也可以指定属于业务接口方法的方法上。在bean 的类上指定RolesAllowed 注释符意味着适用于这个类上所有接口方法。如果在方法上指定则只使用于该方法。如果在类上和方法上都指定了RolesAllowed ，则方法上的值覆盖类上的值。如果在类上使用PermitAll 注释符，并且在单个方法上也指定了RolesAllowed ，那么RolesAllowed 的值覆盖类上的值。

package javax.annotation.security;

@Target({TYPE, METHOD}) @Retention(RUNTIME)

public @interface RolesAllowed {

 String[] value();

 }

1.9.3        PermitAll

PermitAll 注释符指明所有的角色都可以调用指定的方法——例如，指定的方法事“unchecked ”。这个注释符可以指定在bean 类上，也可以指定在bean 的业务方法上。在类上指定PermitAll 意味着应用到这个类的所有可应用的业务方法上。在方法上指定，则意味着只适用于该方法，而且会覆盖类一级的任何设置。

package javax.annotation.security;

@Target ({TYPE, METHOD}) @Retention(RUNTIME)

public @interface PermitAll {}

1.9.4        DenyAll

DenyAll 注释符指明任何角色都不允许调用指定的方法——例如，从执行中排除指定的方法。

package javax.annotation.security;

@Target (METHOD) @Retention(RUNTIME)

public @interface DenyAll {}

1.9.5        RunAs

RunAs 注释符用于指定bean 的run-as 属性。这个注释符应用于bean 类。它的值事安全角色的名字。

package javax.annotation.security;

@Target(TYPE) @Retention(RUNTIME)

public @interface RunAs {

   String value();

 }

1.10      引用EJB

EJB 注释符指定一个对EJB 业务接口或home 接口的引用。

元素name 指的是在环境中用于查找的名字。元素beanInterface 是引用的接口类型——业务接口或home 接口。

元素beanName 引用Stateful 或Stateless 注释符的name 的值，不管是缺省的还是显式指定的（或者事ejb-name 元素的值）。如果ejb-jar 中的会话bean 实现了同一个接口，那么beanName 元素可以用来削除歧义。为了引用在同一个应用的其他ejb-jar 文件，可以用ejb-jar 包的名字+ “# ”+bean 名字的方式来引用。路径名相对于要引用其他包内bean 的bean 所在的jar 文件。

元素mappedName 是特定产品的名字，这个名字用于映射会话bean 。使用映射名字的应用是不可移植的。

@Target({TYPE, METHOD, FIELD}) @Retention(RUNTIME)

public @interface EJB {

String name() default "";

Class beanInterface() default Object.class;

String beanName() default "";

String mappedName() default "";

String description() default "";

}

@Target(TYPE) @Retention(RUNTIME)

public @interface EJBs {

 EJB[] value();

}

1.11      引用资源

Resource 注释符用于表达对外部资源的依赖。属性name 指向在环境中用于查找的名称；type 是资源管理器连接工厂类型。authenticationType 指明容器或bean 是否执行授权。shareable 元素指定自由管理器连接是否共享。mpapedName 元素是资源在特定产品下的映射名称。使用映射名称的应用是不可移植的。

package javax.annotation;

@Target({TYPE, METHOD, FIELD}) @Retention(RUNTIME)

public @interface Resource {

public enum AuthenticationType {

CONTAINER,

APPLICATION

}

String name() default "";

Class type() default Object.class;

AuthenticationType authenticationType()

default AuthenticationType.CONTAINER;

boolean shareable() default true;

String mappedName() default "";

String description() default "";

}

package javax.annotation;

@Target(TYPE) @Retention(RUNTIME)

public @interface Resources {

 Resource[] value();

}