Skip Headers
Oracle® Containers for J2EE Enterprise JavaBeans Developer's Guide
10g (10.1.3.1.0)

Part Number B28221-02
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

What are Enterprise JavaBeans?

The EJB architecture is flexible enough to implement the objects that Table 1-1 lists.

Table 1-1 EJB Types

Type Description See ...

Session

An EJB 3.0 or EJB 2.1 component created by a client for the duration of a single client/server session used to perform operations for the client.

"What is a Session Bean?"


    Stateless

A session bean that does not maintain conversational state. Used for reusable business services that are not connected to any specific client.

"What is a Stateless Session Bean?"


    Stateful

A session bean that does maintain conversational state. Used for conversational sessions with a single client (for the duration of its lifetime) that maintain state, such as instance variable values or transactional state.

"What is a Stateful Session Bean?"


Entity

An EJB 3.0-compliant light-weight entity object that represents persistent data stored in a relational database using the Java Persistence API (JPA) persistence provider specified in its persistence unit (see "What is the persistence.xml File?").

"What is a JPA Entity?"


Entity Bean

An EJB 2.1 enterprise bean component that represents persistent data stored in a relational database.

"What is an EJB 2.1 Entity Bean?"


    CMP

An entity bean with container-managed persistence (CMP) is an entity bean that delegates persistence management to the persistence manager used by the container that hosts it.

"What is an EJB 2.1 Entity Bean With Container-Managed Persistence?"


    BMP

An entity bean with bean-managed persistence (BMP) is an entity bean that manages its own persistence.

"What is an EJB 2.1 Entity Bean With Bean-Managed Persistence?"


MDB

A message-driven bean (MDB) is an EJB 3.0 or EJB 2.1 component that functions as an asynchronous consumer of Java Message Service (JMS) messages.

"What is a Message-Driven Bean?"



For more information, see: the following

What is the Anatomy of an EJB 3.0 enterprise bean?

Using EJB 3.0, the interfaces for your EJB implementation are not restricted by EJB type. For example, in your JPA entity implementation you may implement an EJB using a plain old Java object (POJO) and any plain old Java interfaces (POJI): you do not need to implement interfaces such as javax.ejb.EntityBean and you do not need to provide separate interfaces that extend EJBHome, EJBLocalHome, EJBObject, or EJBLocalObject. A client may instantiate an EJB 3.0 POJO entity instance with new (or the EntityManager: see "How do you Query for a JPA Entity?"). A client may instantiate an EJB 3.0 session bean using dependency injection or JNDI lookup. For more information, see "EJB 3.0 Support".

Table 1-2 lists the parts you create when developing an EJB 3.0 enterprise bean.

Table 1-2 Parts of an EJB 3.0 EJB

Part Type Description

Home interface

POJI

An optional POJI annotated with @Home that specifies an object that the container itself implements: the home object. The @Home is only provided to help EJB 3.0 beans interoperate with EJB 2.1 clients, if necessary. Most EJB 3.0 bean instances will not need to provide a home interface.

Component interface

POJI

A mandatory POJI annotated with @Remote or @Local (default) that specifies the business methods that you implement in the bean and that a client can invoke. No other container service methods need be implemented, unless you need to override default container behavior. The bean class does not need to implement this interface.

Bean implementation

POJO

A mandatory POJO that may optionally implement a component interface and contains the Java code that implements the methods defined in the optional home interface and component interface (business methods). If necessary, you can optionally annotate any method to serve as a container life cycle callback function.

Deployment descriptor

ejb-jar.xml

orion-ejb-jar.xml

toplink-ejb-jar.xml

ejb3-toplink-sessions.xml

persistence.xml

orm.xml

Optional means of specifying attributes of the bean for deployment. These designate configuration specifics, such as environment, interface names, transactional support, type of EJB, and persistence information. Because this metadata can be expressed entirely through annotations (or defaults), deployment descriptor XML files are less important in EJB 3.0. Configuration in a deployment descriptor XML file overrides the corresponding annotation configuration, if present. For more information, see "Understanding EJB Deployment Descriptor Files".


As Figure 1-1 illustrates, to acquire an EJB 3.0 EJB instance, a Web client (such as a servlet) or Java client uses JNDI, while an EJB client may use either JNDI or resource injection. For more information about EJB clients, see "What Type of Client do you Have?".

For entity beans, EJB 3.0 provides an EntityManager that you use to create, find, merge, and persist a JPA entity (see "How do you Query for a JPA Entity?").

Figure 1-1 A Client Using an EJB 3.0 Stateful Session Bean by Component Interface

The events that occur in a stateless session bean
Description of "Figure 1-1 A Client Using an EJB 3.0 Stateful Session Bean by Component Interface"

The client in Figure 1-1 accesses the EJB as follows:

  1. The client retrieves the component interface of the bean.

    The servlet or Java client uses JNDI to look up an instance of Cart.

    The EJB client uses resource injection by annotating a Cart instance variable with the @EJB annotation: at run time, the EJB container will ensure that the variable is initialized accordingly.

    In both cases, the EJB container manages instantiation. A home interface is not necessary.

  2. The client invokes a method defined in the component interface (remote or local interface), which delegates the method call to the corresponding method in the bean instance (through a stub).

  3. The client can destroy the stateful session bean instance by invoking a method in its component interface that is annotated in the bean instance with @Remove.

    Stateless session beans do not require a remove method; the container removes the bean if necessary. The container can also remove stateful session beans that exceed their configured timeout or to maintain the maximum configured pool size. Entities do not require a remove method; you use the EJB 3.0 EntityManager to create and destroy entities.

What is the Anatomy of an EJB 2.1 Enterprise Bean?

Using EJB 2.1, the interfaces for your EJB implementation are based on EJB type. For example, in your EJB 2.1 entity bean implementation, you must implement the javax.ejb.EntityBean interface and you must provide separate interfaces that extend EJBHome or EJBLocalHome and EJBObject or EJBLocalObject. A client may instantiate an EJB 2.1 enterprise bean instance only with a create method that your EJB home interface provides. For more information, see "EJB 2.1 Support".

Table 1-3 lists the parts you create when developing an EJB 2.1 enterprise bean.

Table 1-3 Parts of an EJB 2.1 EJB

Part Type Description

Home interface

javax.ejb.EJBHome (remote)

javax.ejb.EJBLocalHome

Specifies the interface to an object that the container itself implements: the home object. The home interface contains the life cycle methods, such as the create methods that specify how a bean is created.

Component interface

javax.ejb.EJBObject (remote)

javax.ejb.EJBLocalObject

Specifies the business methods that you implement in the bean. The bean must also implement additional container service methods. The EJB container invokes these methods at different times in the life cycle of a bean.

Bean implementation

javax.ejb.SessionBean

javax.ejb.EntityBean

javax.ejb.MessageDrivenBean

Contains the Java code that implements the methods defined in the home interface (life cycle methods), component interface (business methods), and the required container methods (container callback functions).

Deployment descriptor

ejb-jar.xml

toplink-ejb-jar.xml

orion-ejb-jar.xml

Specifies attributes of the bean for deployment. These designate configuration specifics, such as environment, interface names, transactional support, type of EJB, and persistence information.


A client uses the home interface to acquire an EJB 2.1 enterprise bean instance and uses the component interface to invoke its business methods, as Figure 1-2 illustrates. For more information about EJB clients, see "What Type of Client do you Have?".

Figure 1-2 A Client Using an EJB 2.1 Stateless Session Bean by Home and Component Interface

The events that occur in a stateless session bean
Description of "Figure 1-2 A Client Using an EJB 2.1 Stateless Session Bean by Home and Component Interface"

The client in Figure 1-2 accesses the EJB as follows:

  1. The client retrieves the home interface of the bean–typically, through JNDI.

  2. The client invokes the create method on the home interface reference (home object). This creates the bean instance and returns a reference to the component interface (remote or local interface) of the bean.

  3. The client invokes a method defined in the component interface (remote or local interface), which delegates the method call to the corresponding method in the bean instance (through a stub).

  4. The client can destroy the bean instance by invoking the remove method that is defined in the component interface (remote or local interface).

    For some beans, such as stateless session beans, calling the remove method does nothing: in this case, the container is responsible for removing the bean instance.

What is the Life Cycle of an Enterprise Bean?

The life cycle of an enterprise bean involves important events such as creation, passivation, activation, and removal.

Each such event is associated with a callback method. You can define life cycle callback methods on the following:

You can combine these options: for example, you can define some life cycle callbacks as methods of a session bean class, and some in an interceptor class that you associate with the session bean.

The container invokes the callback prior to, or immediately after the life cycle event (depending on the event type).

The life cycle events associated with an enterprise bean and whether or not the container or the bean provider is responsible for implementing callbacks is determined by the type of enterprise beans you are developing (as specified in the appropriate EJB interface).

For an EJB 3.0 enterprise bean, when the container is responsible for the life cycle callback, you do not need to provide an implementation in your bean, unless you want to perform some additional logic.

For an EJB 2.1 enterprise bean, even when the container is responsible for the life cycle callback, and even if you do not want to perform additional logic, you must at least provide an empty implementation of the life cycle methods to satisfy the requirements of the applicable EJB interface.

For more information, see the following:

Life Cycle Callback Methods on a Bean Class

For any EJB 3.0 enterprise bean type, you can optionally annotate any EJB class method as a life cycle method.

For an EJB 2.1 enterprise bean, you must at least provide an empty implementation of the life cycle methods to satisfy the requirements of the applicable EJB interface.

Life Cycle Callback Interceptor Methods on an EJB 3.0 Interceptor Class

For an EJB 3.0 session bean or message-driven bean, you can optionally associate the bean class with an interceptor class and annotate any interceptor class method as a life cycle method.

For more information, see the following:

Life Cycle Callback Listener Methods on a JPA Entity Listener Class

For a JPA entity, you can associate the bean class with an entity listener class and annotate any entity listener class method as a life cycle method.

For more information, see "Configuring a Life Cycle Callback Listener Method on an Entity Listener Class of a JPA Entity".

What is EJB Context?

The EJBContext interface provides an instance with access to the container-provided run-time context of an EJB 2.1 enterprise bean instance. This interface is extended by the SessionContext, EntityContext, and MessageDrivenContext interfaces to provide additional methods specific to the enterprise interface Bean type.

The javax.ejb.EJBContext interface has the following definition:

public interface EJBContext {
    public EJBHome         getEJBHome(); 
    public Properties      getEnvironment();
    public Principal       getCallerPrincipal();
    public boolean         isCallerInRole(String roleName);
    public UserTransaction getUserTransaction();
    public boolean         getRollbackOnly();
    public void            setRollbackOnly();
}

A bean needs the EJB context when it wants to perform the operations listed in Table 1-4.

Table 1-4 EJB 2.1 EJBContext Operations

Method Description

getEnvironment

Get the values of properties for the bean.

getUserTransaction

Get a transaction context, which enables programmatic transaction demarcation when using bean-managed transactions (BMT). This is valid only for beans that have been designated transactional.

setRollbackOnly

Set the current transaction so that it cannot be committed. Applicable only to container-managed transactions.

getRollbackOnly

Check whether the current transaction is marked for rollback only. Applicable only to container-managed transactions.

getEJBHome

Retrieve the object reference to the corresponding EJBHome (home interface) of the bean.

lookup

Use JNDI to retrieve the bean by environment reference name. When using this method, you do not prefix the bean reference with "java:comp/env".


Do not confuse EJBContext with IntialContext (see "Configuring the Initial Context Factory").

For more information, see the following:

How do Annotations and Resource Injection Work?

Annotations allow you to control the behavior and deployment of your application. You can use metadata annotations to specify expected requirements on container behavior, to request the injection of services and resources, and to specify object-relational mappings.

Using annotations, an EJB 3.0 enterprise bean may use dependency injection mechanisms to acquire references to resources or other objects in its environment. For example, you can use the following:

  • @Resource: to inject non-EJB resources such as a database connection.

  • @EJB: to inject an enterprise bean such as a session bean.

  • @PersistenceContext: to inject an EntityManager instance to create, read, update, and delete EJB 3.0 entities.

If an EJB 3.0 enterprise bean makes use of dependency injection, OC4J injects these references after the bean instance is created, and before any business methods are invoked.

If a dependency on the EJB context is declared, the EJB context is also injected (see "What is EJB Context?").

If dependency injection fails, OC4J discards the bean instance.

OC4J supports annotation inheritance (see "Annotations and Inheritance").

In this release, you can use annotations and resource injection in the Web tier (see "Annotations in the Web Tier").

Annotations are another way of specifying an environment reference without having to use XML. When you annotate a field or property, the container injects the value into the bean on your behalf by looking it up from JNDI. When a reference is specified using annotations, you can still look it up using JNDI. Example 1-1 shows how annotations relate to JNDI. The annotations in this example correspond to the ejb-jar.xml file equivalent in Example 1-2. Your code would have the exact same behavior if this XML and JNDI was used instead.

You can override annotation configuration using deployment XML (see "Overriding Annotations With Deployment Descriptor Entries").

Example 1-1 Using Annotations and Resource Injection

@Stateless
@EJB(name="bean1", businessInterface=Bean1.class)
public class MyBean {
    @EJB Bean2 bean2;

    public void doSomething() {
        // Bean2 is already injected and available
        bean2.foo();
        // or it can be looked up from JNDI
        ((Bean2)(new InitialContext().lookup("java:comp/env/bean2"))).foo();
        // Bean1 has not been injected and is only available through JNDI
        ((Bean1)(new InitialContext().lookup("java:comp/env/bean1"))).foo();
    }
}

Example 1-2 Equivalent ejb-jar.xml File Configuration

<ejb-local-ref>
    <ejb-ref-name>bean1</ejb-ref-name>
    <ejb-ref-type>Session</ejb-ref-type>
    <local>Bean1.class</local>
</ejb-local-ref>

<ejb-local-ref>
    <ejb-ref-name>bean2</ejb-ref-name>
    <ejb-ref-type>Session</ejb-ref-type>
    <local>Bean2.class</local>
    <injection-target>
        <injection-target-name>bean2</injection-target-name>
    </injection-target>
</ejb-local-ref>

Annotations in the Web Tier

In this release, OC4J supports annotations and resource injection in the Web tier. To use annotations and resource injection in the Web tier, your client must use Java SE 1.5 and Servlet 2.5 or later.

You can use the following annotations in the Web tier:

  • @EJB

  • @Resource and @Resources

  • @PersistenceUnit and @PersistenceUnits

  • @PersistenceContext and @PersistenceContexts

  • @WebServiceRef

  • @PostConstruct

  • @PreDestroy

  • @DeclaresRoles

  • @RunAs

For more information, see the following:

Annotations and Inheritance

Annotations participate in inheritance. To ensure that annotations are local to their host class, consider the following:

  • Class-level annotations only affect the class they annotate and its members (methods and fields). Annotations never affect a member declared by a superclass, even if the member is not hidden or overridden by the subject subclass.

  • Explicit member-level annotations have priority over member-level annotations implied by a class-level annotation, except for the cases when the annotation is potentially additive (for example, interceptor annotations): if a member carries a specific member-level annotation, any annotations of the same type implied by a class-level annotation are ignored.

  • Interfaces implemented by a class never contribute annotations to the class itself or to any of its members.

  • Members inherited from a superclass (the ones that are not hidden or overridden) maintain the annotations they had in the class that declared them, including member-level annotations implied by class-level annotations.

  • Member-level annotations on a hidden or overridden member are always ignored.

To find the annotation in-effect for a class member, you need to track down the last nonhidden and nonoverridden declaration of the class member and examine it. If you cannot find the annotation, then you have to examine the enclosing class declaration. If this fails, do not consult any other source files.

Table 1-5 lists annotations and specifies how each of the annotations behave with respect to inheritance in the bean class.

Table 1-5 Annotations and Inheritance

Annotations Reaction to Inheritance Comment OC4J Support

@Stateless

@Stateful

@MessageDriven

Superclass annotations are ignored.

Example:

@Stateful 
class Base {}

@Stateless 
class A extends Base {}

class B extends Base {}

where:

- bean Base is a stateful session bean;

- bean A is a stateless session bean: @Stateful annotation of its parent bean Base does not apply (is ignored);

- bean B is a POJO class: @Stateful annotation of its parent bean Base does not apply (is ignored).

You must explicitly define a bean class through either a class annotation or deployment descriptor XML file, even if the bean is a subclass of another bean class.

Yes.

OC4J ignores the superclass-level bean-type annotations.

@Local

@Remote

@LocalHome

@Home

Superclass annotations are ignored.

You need to define the annotations properly to avoid run-time issues.

Example:

@Local 
interface Base {}

@Remote 
interface A extends Base {}

interface B extends Base {}

where:

- Base is a local business interface;

- A is a remote interface: @Local annotation of its parent bean Base does not apply (is ignored);

- B is a POJO interface: @Local annotation of its parent bean Base does not apply (is ignored).

This also implies the annotation on the bean.

Example:

@Stateful 
@Local(I1.class)
class A {}

@Stateful 
class B extends A {}

Note: unlike A, bean B does not have I1 business interface.

Yes.

OC4J ignores the superclass-level bean-type annotations.

@TransactionManagement(TransactionManagementType.CONTAINER)

@TransactionManagement(TransactionManagementType.APPLICATION)

Superclass annotations are ignored.

Example:

@ TransactionManagement 
(type=TransactionManagementType.CONTAINER)
class Base {}

@ TransactionManagement 
(type=TransactionManagementType.APPLICATION)
class A extends Base {}

class B extends Base {}

where:

- A is a bean that uses bean-managed transactions;

- B is a bean that uses default container-managed transactions.

No class-level transaction management inheritance means that a bean that uses bean-managed transactions and container-managed transactions will be mixed in the application. This might cause run-time issues.

If not explicitly annotated, a bean by default uses container-managed transactions.

Yes.

OC4J ignores the superclass-level bean-type annotation.

@TransactionAttribute(TransactionAttributeType.REQUIRED) {MANDATORY, REQUIRED, REQUIRES_NEW, SUPPORTS, NOT_SUPPORTED, NEVER}

Method-level inheritance and "virtual method annotation" inheritance are allowed.

Example:

@Transaction(REQUIRED)
class Base {
    @Transaction(NONE)
    public void foo() {...}
    public void bar() {...}
}

class A extends Base {
    public void foo() {...}
}

public class B extends Base {
    @Transaction(NEW)
    public void foo() {...}
}

@Transaction(NEW)
public class C extends Base {
    public void foo() {...}
    public void bar() {...}
}

@Transaction(NEW)
public class D extends Base {
    public void bar() {...}
}

@Transaction(NEW)
public class E extends Base {

where:

- in bean A, the foo method is not annotated: bean A overrides the foo method of its parent bean Base without annotating this method. Therefor, the foo method in bean A does not carry @Transaction(NONE) annotation;

-in bean B, the @Transaction(NEW) annotation is applicable to the foo method: bean B overrides the foo method of its parent bean Base annotating this method with @Transaction(NEW). As a result, @Transaction(NONE) annotation from the foo method of bean Base does not apply to the overridden method in the child bean B;

- in bean C, the @Transaction(NEW) annotation is applicable to the foo method: bean C overrides the foo method of its parent bean Base without annotating this method. Therefor, the foo method in bean C does not carry @Transaction(NONE) annotation. However, bean C has a class-level annotation @Transaction(NEW), which is applied to its foo method;

- in bean D, the @Transaction(NEW) annotation is applicable to the bar method: bean D overrides the bar method of its parent bean Base without annotating this method. Therefor, the bar method in bean C does not carry @Transaction(NONE) annotation. However, bean C has a class-level annotation @Transaction(NEW), which is applied to its bar method;

Supports the "virtual method annotation", which is annotated at the supercall class level and applied to all methods in the class.

For more information, see JSR 250 at http://jcp.org/en/jsr/detail?id=250

Yes.

@TransactionAttribute(TransactionAttributeType.REQUIRED){MANDATORY, REQUIRED, REQUIRES_NEW, SUPPORTS, NOT_SUPPORTED, NEVER}

(continues from preceding row)

(continues from preceding row)

- in bean E, the @Transaction(REQUIRED) annotation is applicable to the bar method: bean E has a class-level annotation @Transaction(NEW), but does not override the bar method of its parent bean Base. Therefor, the bar method in bean E carries the class-level @Transaction(REQUIRED) annotation from its parent bean Base.

(continues from preceding row)

(continues from preceding row)

@EJB

@EJBs

All superclasses will be examined to discover all uses of this annotation, including private methods and fields, and private overridden methods (both private in a parent and child).

Example:

@EJB(beanName = "Bean1"…)
public class Base {
    @EJB(beanName =" Bean2"..)
    private Bean2 b2;
    @EJB(beanName =" Bean3"..)
    protected void setB3(Bean3 b3){}
}

@EJB(beanName = "Bean4"…)
public class A extends Base {
    @EJB(beanName =" Bean5"..)
    private Bean5 b5;
}

public class B extends Base {}

When parsing bean A, all @EJB references defined in superclasses, including Bean1, Bean2, Bean3, Bean4 and Bean5 will be parsed and added. The annotated fields and methods will also be injected.

When parsing bean B, all @EJB references defined in superclasses, including Bean1, Bean2, Bean3, Bean4 will be parsed and added. The annotated fields and methods will also be injected.


Yes.

@PersistenceUnit

@PersistenceUnits

@PersistenceContext

@PersistenceContexts

Similar to @EJB and @EJBs (see preceding row).


Yes.

@Resources

@Resource

Similar to @EJB and @EJBs (see preceding row).


Yes.

@Interceptors

@ExcludeDefaultInterceptor

@ExcludeClassInterceptor

Inheritance is allowed.

Method-level business method interceptors are invoked in addition to any default interceptors and interceptors defined for the bean class (and its superclasses).

Example:

Default interceptor: D1.class

@Interceptors({C1.class})
class Base {
    @Interceptors({M1.class})
    public void foo() {...}
    public void bar() {...}
}

@Interceptors({C2.class})
class A extends Base {
    public void foo() {...}
}

@Interceptors({C2.class})
class B extends Base {
    @Interceptors({M2.class})
    public void foo() {...}
}

@Interceptors({C2.class})
class C extends Base {
    public void bar() {...}
}

@Interceptors({C3.class, C4.class})
class E extends Base {}

@Interceptors({C3.class, C4.class})
class F extends Base {
    @ExcludedDefaultInterceptor
    @ExcludedClassInterceptor
    @Interceptors({M2.class})
    public void bar() {...}
}

where:

- interceptors for the foo method in bean Base are D1, C1, M1: D1 is the default interceptor; C1 is defined as an interceptor on a bean class level; M1 defined as an interceptor for foo on a method level;

- interceptors for the foo method in bean A are D1, C2: D1 is the default interceptor; C1 is defined as an interceptor on a bean class level. Bean A overrides the foo method and does not define a method-level interceptor for it;


Yes

@Interceptors

@ExcludeDefaultInterceptor

@ExcludeClassInterceptor

(continues from preceding row)

(continues from preceding row)

- interceptors for the foo method in bean B are D1, C2, M2: D1 is the default interceptor; C2 is defined as an interceptor on a bean class level; bean B overrides the foo method and defines M2 as an interceptor on a method level;

- interceptors for the bar method in bean C are D1, C2: D1 is the default interceptor; C2 is defined as an interceptor on a bean class level;

- interceptors for the bar method in bean E are D1, C1: D1 is the default interceptor; bean E has a class-level annotation @Interceptors({C3.class, C4.class}), but does not override the bar method of its parent bean Base. Therefor, the bar method in bean E carries the class-level @Interceptors({C1.class}) annotation from its parent bean Base.

- interceptor for the bar method in bean F is M2: the default interceptor D1 is not applicable to this method, because bar is annotated with @ExcludeDefaultInterceptor; interceptors defined at the class level are not applicable, because bar is annotated with @ExcludeClassInterceptor. Bean F overrides the bar method and provides it with a @Interceptors({M2.class}) annotation, and only this annotation applies.

(continues from preceding row)

(continues from preceding row)

@AroundInvoke

If a bean class has superclasses, any methods annotated with @AroundInvoke and defined on those superclasses will be invoked, with the most general superclass first.

Example:

class Base {
    @AroundInvoke
    public Object foo(InvocationContext cts) {...}
}

class A extends Base {
    @AroundInvoke
    public Object bar(InvocationContext cts) {...}
}

class B extends Base {
    public Object foo(InvocationContext cts) {...}
}

where:

- in bean Base an interceptor method is foo();

- in bean A there are two interceptor methods–foo and bar: the bar method is defined in bean A, and the foo method is inherited by bean A from its parent bean Base. foo will be invoked first, and bar will be invoked second;

- there is no interceptor method in bean B: bean B overrides the foo method without annotating it with @AroundInvoke, therefor making it a non-interceptor method.

If an interceptor class has superclasses, the interceptor methods defined by the interceptor class' superclasses will be invoked before the interceptor method defined by the interceptor class, with the most general superclass first.

Yes.

@PostConstruct

@PreDestroy

@PostActivate

@PrePessivate

If a bean class has superclasses, any life cycle callback (interceptor) methods defined on the superclasses will be invoked, with the most general superclass first.

Note: overridden life cycle methods will not be invoked.

Example:

class Base {
    @PostConstruct
    @PostActivate
    void foo() {...}
}

class A extends Base {
    @PostConstruct
    void bar() {...}
    @PostActivate
    void ping() {...}
}

class B extends Base {
    @PreDestroy
    void foo() {...}
}

class C extends Base {
    ejbCreate() {...}
}

class D extends Base {
    @PostConstruct
    ping() {...}
    ejbCreate() {...}
}

where:

- in bean Base, there are two life cycle methods: one post-construct method foo, and one post-activate life cycle method foo;

- in bean A, there are two post-construct methods: foo and bar. The foo method will be invoked first, and bar will be invoked second. Also, bean A has two post-activate life cycle methods: foo and ping. The foo method will be invoked first, and ping will be invoked second;

- in bean B, the foo method is overridden with @PreDestroy annotation. Therefor, the post-construct method is not defined in bean B, and the post-activate life cycle method is not defined. Only the pre-destroy life cycle method foo is defined in bean B;

- in bean C, there are two post-construct methods: foo, which is inherited from the parent beans Base and which is invoked first, and ejbCreate, which is defined by bean C and is invoked second;

- there is an error in bean D: the EJB 2.1-style life cycle callback (for example, ejbCreate() method) cannot coexist with the corresponding EJB 3.0-style (for example, @PostConstruct annotation) callback in one bean class.

If an interceptor class has superclasses, the life cycle callback interceptor methods defined by the interceptor class' superclasses will be invoked before the life cycle callback interceptor method defined by the interceptor class, with the most general superclass first.

Yes.

@Timeout

At most one timeout method is allowed in the inheritance hierarchy.

Example:

class Base {
    @Timeout
    public void foo(Timer) {...}
}

class A extends Base {
    @Timeout
    public void bar(Timer) {...}
}

class B extends Base {
    public void foo(Timer) {...}
}

class C extends Base implements TimedObject {
    public void ejbTimeout(Timer) {...}
}

where:

- foo is the timeout method in bean Base;

- there is an error in bean A: bar is the timeout method defined in bean A. Bean A also inherits foo timeout method from its parent bean Base. That makes it two timeout methods in bean A, which is not allowed;

- there is no timeout method in bean B: bean B overrides the foo method without annotating it, thus making a non-timeout method;

- there is an error in bean C: ejb Timeout is the timeout method defined in bean C. In addition, bean C inherits foo timeout method from its parent bean Base. That makes it two timeout methods in bean C, which is not allowed two timeout methods in bean C.

If a method annotated in both the base and the superclass (different method name), the container will throw an exception as the EJB 3.0 specification only allows one timeout method for each bean.

Yes.

@Remove

Multiple removes are allowed.

Example:

class Base {
    @Remove
    void foo() {...}
}

class A extends Base {
    @Remove
    void bar() {...}
}

class B extends Base {
    void foo() {...}
}

class C extends Base {
    @Remove
    void foo(int) {...}
}

were:

- foo is the removal method in bean Base;

- foo and bar are the removal methods in bean A: the bar method is explicitly defined as a removal method in bean A; since bean A does not override the foo method, it inherits foo as a removal method from its parent bean Base;

- there is no removal method in bean B: bean B overrides the foo method and does not supply it with an annotation (the @Remove annotation of the foo method in bean Base would have been inherited, if the method was not overridden);

- foo() and foo(int) are the removal methods in bean C: the foo(int) method is explicitly defined as a removal method in bean C; since bean C does not override the foo() method, it inherits foo() as a removal method from its parent bean Base.

The @Remove annotation is additive in nature: more than one removal method is allowed in a bean.

Yes.

@RolesAllowed

@DenyAll

@PermitAll

Only method-level inheritance is allowed.

Example:

@PermitAll
class Base {
    @DenyAll
    public void foo() {...}
    void bar() {...}
}

class A extends Base {
    public void foo() {...}
}

public class B extends Base {
    @RolesAllowed({admin})
    public void foo( ) {...}
}

@RolesAllowed({guest}, {admin})
public class C extends Base {
    public void foo() {...}
    void bar(){...}
}

@DenyAll
public class D extends Base {
    public void bar() {...}
}

@RolesAllowed({guest}, {admin})
public class E extends Base {}

@RolesAllowed({guest}, {admin})
class F extends Base {
    @RolesAllowed ({admin})
    public void bar() {...}
}

where:

- in bean A, no security permissions are given (no roles are allowed) in the foo method: bean A cannot inherit any class-level annotations from its parent class Base. Moreover, since bean A overrides its parent's foo method and does not supply this overridden method with annotations, the foo method in bean A acts as unannotated method;

- in bean B, only admin role is allowed in the foo method: bean B does not have its own class-level annotations and cannot inherit any class-level annotations from its parent class Base. However, since bean B overrides its parent's foo method and supplies this overridden method with a @RolesAllowed({admin}) annotation, the foo method in bean B sets the admin role;

This is similar to the transaction attribute scenarios.

Note: EJB 3.0 specification states that method-level security annotation will override the class-level annotation. But for ejb-jar.xml method-permission, it is addictive (or union of both class and method level roles). The example of it is a bean F case.

From King: The EJB 3.0 specification may want to spill out this inconsistence and come up with a way to handle it. XML over annotation doc should also list this issue.

Yes.

@RolesAllowed

@DenyAll

@PermitAll

(continues from preceding row)

(continues from preceding row)

- in bean C, guest and admin roles are allowed in the foo method: bean C has its own class-level annotation of @RolesAllowed({guest},{admin}), but cannot inherit any class-level annotations from its parent class Base. Since bean C overrides its parent's foo method and does not supply this overridden method with any annotations, the foo method in bean C sets the guest and admin roles;

- in bean D, no roles are allowed (all denied) in the bar method: bean D has its own class-level annotation of @DenyAll, and cannot inherit any class-level annotations from its parent class Base. Since bean D overrides its parent's bar method and does not supply this overridden method with any annotations, the bar method in bean D denies all security permissions;

- in bean E, all the roles are allowed (permit all) in the bar method: bean E has its own class-level annotation of @RolesAllowed({guest},{admin}), but cannot inherit any class-level annotations from its parent class Base. However, since bean E does not override its parent's bar method, bean E inherits this methods from bean Base along with the @PermitAll annotation applied to it;

- for explanations on bean F, see Comments column.

(continues from preceding row)

(continues from preceding row)

@RunAs

Class-level inheritance is not allowed.

Example:

@RunAs ("bob")
class Base {}

@RunAs ("joe")
class A extends Base {}

class B extends Base {}

where:

- run is defined as "joe" for bean A: as bean A cannot inherit any annotations from its parent class, bean A does not inherit run "bob" from its parent class Base;

- run is not defined for bean B: as bean B cannot inherit any annotations from its parent class, bean B does not inherit role "bob" from its parent class Base;


Yes.

Ignores the superclass-level bean type annotation.

@DeclareRoles

Class-level inheritance is not allowed.

Example:

@DeclareRoles ({"bob"})
class Base {}

@DeclareRoles ({"joe"})
class A extends Base {}

class B extends Base {}

where:

- bean A declares role "joe": as bean A cannot inherit any annotations from its parent class, bean A does not inherit role "bob" from its parent class Base;

- bean B does not declare any roles: as bean B cannot inherit any annotations from its parent class, it does not inherit role "bob" from its parent class Base.


Yes.

@WebService

Class-level inheritance is not allowed.

Example:

@WebServices
class Base {}

@Stateless
class A extends Base {}

where:

- bean A is not a Web Service end point, because it does not inherit @WebService annotation from its parent class Base.


Yes.

Ignores the superclass-level bean type annotation.

@StatefulDeployemt

@StatelessDeployemt

@MessageDrivenDeployemt

Class-level inheritance is not allowed.

Example:

@StatefulDeployment (timeout=60)
class Base {}

@StatefulDeployment (timeout=30)
class A extends Base {}

class B extends Base {}

where:

- bean A has a stateful deployment timeout of 30: bean A cannot inherit any annotations from its parent class, therefor bean A does not inherit a stateful deployment timeout of 60 from its parent class Base;

- bean B does not have a timeout: bean B cannot inherit any annotations from its parent class, therefor bean B does not inherit a stateful deployment timeout of 60 from its parent class Base;

These are OC4J-specific annotations: they are not defined in the EJB 3.0 specification.

Yes.

Ignores the superclass-level bean type annotation.


Overriding Annotations With Deployment Descriptor Entries

You can combine the use of annotations and deployment descriptors in the design of your application. In this case, a deployment descriptor plays a role of an overriding mechanism for the annotations. For a list of rules that apply when XML descriptor is used to override annotations, see EJB 3.0 specification.

OC4J supports the annotations overriding rules defined in the EJB 3.0 specification. In the current release of OC4J, if a deployment descriptor overriding violates these rules, OC4J logs a warning, ignores the override, and uses the annotation configuration. For example, if you annotate a class with a @Stateful annotation, and then in the ejb-jar.xml file you override this with an <entity> entry, it would be a violation of the overriding rule: you cannot override the bean type. OC4J will behave as follows: it will log a warning, ignore the override, and continue to treat the class as a stateful session bean.

Note:

In future releases of OC4J, the warnings will be replaced with exceptions that will fail the deployment.

Table 1-6 lists overriding rules for annotations with XML that are defined in EJB 3.0 specification, as well as the behavior of OC4J (10.1.3.1 release, EJB layer) with regards to these rules.

Table 1-6 Overriding Annotations With XML

Scope Annotations XML EJB 3.0 Specification Overriding Rules OC4J-specific Behavior (10.1.3.1 Release)

Session bean type

@Stateless

@Stateful

<session-type>

Section 19.2 of the EJB 3.0 specification states that if the bean's type has been specified by means of the @Stateless, @Stateful, or @MessageDriven annotation, its type cannot be overridden by means of the deployment descriptor. The bean's type (and its session type), if specified, must be the same as that specified in annotations.

If this rule is broken, OC4J logs a warning.

Note: in 11g release of OC4J, the container will throw a validation exception.

Transaction type: BMT or CMT

@TransactionManagement(TransactionManagementType.CONTAINER, TransactionManagementType.APPLICATION)

<transaction-type>

Section 13.3.6 of the EJB 3.0 specification states that transaction type override is not allowed.

If this rule is broken, OC4J logs a warning.

Note: in 11g release of OC4J, the container will throw a validation exception.

Transaction attribute

@TransactionAttribute(TransactionAttributeType.REQUIRED){MANDATORY, REQUIRED, REQUIRES_NEW, SUPPORTS, NOT_SUPPORTED, NEVER}

<container-transaction>

<trans-attribute>

Section 13.3.7 of the EJB 3.0 specification states that XML is served as an alternative to metadata annotations to specify the transaction attributes (or as a means to supplement or override metadata annotations for transaction attributes). Transaction attributes specified in the deployment descriptor are assumed to override or supplement transaction attributes specified in annotations.

OC4J complies with the overriding rule.

Interceptor

@Interceptors

@ExcludeDefaultInterceptor

@ExcludeClassInterceptor

<interceptor-binding>

<exclude-default-interceptors>

<exclude-class-interceptors>

<interceptor-order>

Section 12.8.2 of the EJB 3.0 specification states that the binding of interceptors to classes is additive. XML is used to augment the interceptors and interceptor methods defined by means of annotations. The specification also states that XML may be used as an alternative to specify the invocation order of interceptors or to override the order specified in metadata annotations.

OC4J does not allow multiple interceptor-order definitions. It cannot turn off exclude-class-interceptors and exclude-default-interceptors flags if interceptor-order is used. It cannot define interceptor-class outside of interceptor-order. Those are not defined in the EJB 3.0 specification.

Interceptor callback

@PostConstruct

@PreDestroy

@PostActivate

@PrePessivate

@AroundInvoke

<post-construct-method>

<pre-destroy-method>

<post-activate-method>

<pre-passivate-method>

<around-invoke-method>

Section 12.8.1 of the EJB 3.0 specification states that at most one method of a given interceptor class can be designated as an around-invoke method, post-construct method, pre-destroy method, pre-passivate method, or post-activate method, regardless of whether the deployment descriptor is used to define interceptors or some combination of annotations and deployment descriptor elements is used.

OC4J adds the life cycle callback method to the descriptor list without validating the singleton restraint.

Security identity

@DeclareRoles

@RunAs

<security-role>

<role-name>

Section 17.3.4 of the EJB 3.0 specification states that XML <security-identity> element can be used to override a security identity specified in metadata. The value of the <security-identity> element is either use-caller-identity or run-as.

OC4J complies with the overriding rule.

Method permission

@RolesAllowed

@DenyAll

@PermitAll

<method-permission>

Section 17.3.2.2 of the EJB 3.0 specification states that the specification of the <method-permission> element in XML is served as an alternative to metadata annotations to specify the method permissions (or as a means to supplement or override metadata annotations for method permission values). Any values explicitly specified in the deployment descriptor override any values specified in annotations. The granularity of overriding is at the method level. The method permissions relation is defined as the union of all the method permissions defined in the individual <method-permission> elements.

OC4J complies with the overriding rule.

EJB reference

@EJB

@EJBs

<ejb-ref>

<ejb-local-ref>

Section 16.5.2.1 of the EJB 3.0 specification states that the following rules apply to how an XML entry may override an @EJB / @EJBs annotation:

  • The relevant deployment descriptor entry is located based on the JNDI name used with the annotation (either defaulted or provided explicitly).

  • The type specified in the deployment descriptor using the <remote>, <local>, <remote-home>, or <local-home> element and any bean referenced by the <ejb-link> element must be assignable to the type of the field or property, or the type specified by the beanInterface element of the @EJB annotation.

  • The description, if specified, overrides the description element of the annotation.

  • The injection target, if specified, must name exactly the annotated field or property method.

OC4J complies with the overriding rule.

Resource reference

@Resource

@Resources

<env-entry>

<resource-ref>

<resource-env-ref>

Section 16.2.3 of the EJB 3.0 specification states that the following rules apply to how a XML entry may override a @Resource / @Resources annotations:

  • The relevant deployment descriptor entry is located based on the JNDI name used with the annotation (either defaulted or provided explicitly).

  • The type specified in the deployment descriptor must be assignable to the type of the field or property, or the type specified in the @Resource annotation.

  • The description, if specified, overrides the description element of the annotation.

  • The injection target, if specified, must name exactly the annotated field or property method.

  • The <res-sharing-scope> element, if specified, overrides the shareable element of the annotation.

  • The <res-auth> element, if specified, overrides the authenticationType element of the annotation.

OC4J complies with the overriding rule.

Persistence unit

@PersistenceUnits

@PersistenceUnit

<persistence-units>

<persistence-unit>

Section 16.10.2.1 of the EJB 3.0 specification states that the following rules apply to how a XML entry may override a @PersistenceUnit / @PersistenceUnits annotation:

  • The relevant deployment descriptor entry is located based on the JNDI name used with the annotation (either defaulted or provided explicitly).

  • The <persistence-unit-name> element of the deployment descriptor overrides the unitName element of the annotation.

  • The injection target, if specified, must name exactly the annotated field or property method.

OC4J complies with the overriding rule.

Persistence context

@PersistenceContext

@PersistenceContexts

<persistence-context>

<persistence-contexts>

Section 16.11.2 of the EJB 3.0 specification states that the following rules apply to how a XML entry may override a @PersistenceContext / @PersistenceContexts annotation:

  • The relevant deployment descriptor entry is located based on the JNDI name used with the annotation (either defaulted or provided explicitly).

  • The <persistence-context-type> element of the deployment descriptor overrides the type element of the annotation.

  • Any <persistence-property> elements are added to those specified by the @PersistenceContext / @PersistenceContexts annotation. If the name of a specified property is the same as one specified by the @PersistenceContext annotation, the value specified in the annotation is overridden.

  • The injection target, if specified, must name exactly the annotated field or property method.

OC4J complies with the overriding rule.

Timeout

@Timeout

<timeout-method>

Section 18.2.2.of the EJB 3.0 specification states that if the @Timeout annotation is used, or the bean implements the TimedObject interface, the <timeout-method> XML, if specified, can only be used to refer to the same method.

OC4J complies with the overriding rule.

Remove

@Remove (retainIfException=true|false)

<remove-method>

<retain-if-exception>

Section 4.3.11 of the EJB 3.0 specification states that the XML <retain-if-exception> sub-element of the <remove-method> element may be explicitly specified to override the retainIfException value specified or defaulted by the @Remove annotation.

OC4J handles the remove methods properly on stateful session beans.

Activation configuration

@MessageDriven

activationConfig

<activation-config>

Section 5.4.13 of the EJB 3.0 specification states that the activation configuration properties specified in the deployment descriptor are added to those specified by means of the @MessageDriven annotation. If a property of the same name is specified in both, the deployment descriptor value overrides the value specified in the annotation.

OC4J complies with the overriding rule.

Note: there is a bug in the current release of OC4J: the container does not perform the override at all times. Instead, it creates a new activation configuration object to the list.

Bug 5465559

Deployment

@StatefulDeployemt

@StatelessDeployemt

@MessageDrivenDeployemt

<session-deployment>

<message-driven-deployment>

These annotations are not defined in the EJB 3.0 specification: they are OC4J-specific.

OC4J handles these annotations in the following way: if applied, the deployment settings in XML will override the annotation.


OC4J Support for Annotation Attribute mappedName

OC4J supports @EJB and @Resource attribute mappedName. For these annotations, mappedName is the equivalent of the location attribute of orion-ejb-jar.xml in elements session-deployment, entity-deployment, and message-driven-deployment.

OC4J does not support the mappedName attribute in @Stateless, @Stateful, or @MessageDriven annotations.