What are Enterprise JavaBeans?

What is the Anatomy of an EJB 3.0 EJB?

Using EJB 3.0, the interfaces for your EJB implementation are not restricted by EJB type. For example, in your EJB 3.0 entity bean 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 like 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 an EJB 3.0 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 EJB.

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 an EJB 3.0 entity (see "How Do You Query for an EJB 3.0 Entity?").

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

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. Entity beans do not require a remove method; you use the EJB 3.0 EntityManager to create and destroy entity beans.

What is the Anatomy of an EJB 2.1 EJB?

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 EJB 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 EJB.

A client uses the home interface to acquire an EJB 2.1 EJB 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

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—normally 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 Lifecycle of an EJB?

The lifecycle of an EJB involves important events such as creation, passivation, activation, and removal. Each such event is associated with a callback defined on the EJB class (see "Callback Methods"). The container invokes the callback prior to or immediately after the lifecycle event (depending on the event type).

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

For an EJB 3.0 bean, when the container is responsible for the lifecycle 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 bean, even when the container is responsible for the lifecycle callback, and even if you do not want to perform additional logic, you must at least provide an empty implementation of the lifecycle methods to satisfy the requirements of the applicable EJB interface.

For more information, see:

• "What is the Stateless Session Bean Lifecycle?"

• "What is the Stateful Session Bean Lifecycle?"

• "What is the CMP Entity Bean Lifecycle?"

• "What is the BMP Entity Bean Lifecycle?"

• "What is the Message-Driven Bean Lifecycle?"

What is EJB Context?

The EJBContext interface provides an instance with access to the container-provided runtime context of an EJB 2.1 EJB 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.

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

For more information, see:

• "What is Session Context?"

• "What is Entity Context?"

• "What is Message Driven Context?"

• "Accessing an EJB 2.1 EJBContext"

How Do Annotations and Resource Injection Work?

Using the @Resource or @EJB annotation, an EJB 3.0 bean may use dependency injection mechanisms to acquire references to resources or other objects in its environment. You use @Resource to inject non-EJB resources and @EJB to inject EJBs.

If an EJB 3.0 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.

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 normally 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.

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

<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>