EJB.4.2 Enterprise JavaBeans Architecture Contracts

This section provides an overview of the Enterprise JavaBeans architecture contracts. The contracts are described in detail in the following chapters of this document.

EJB.4.2.1 Client-View Contract

This is a contract between a client and a container. The client-view contract provides a uniform development model for applications using enterprise beans as components. This uniform model enables the use of higher level development tools and allows greater reuse of components .

The enterprise bean client view is remotable ”both local and remote programs can access an enterprise bean using the same view of the enterprise bean.

A client of an enterprise bean can be another enterprise bean deployed in the same or different container. Or it can be an arbitrary Java technology-enabled program, such as an application, applet, or servlet. The client view of an enterprise bean can also be mapped to non-Java client environments, such as CORBA clients that are not written in the Java programming language.

The enterprise bean provider and the container provider cooperate to create the enterprise bean's client view. The client view includes:

• Home interface

• Remote interface

• Object identity

• Metadata interface

• Handle

The enterprise bean's home interface defines the methods for the client to create, remove, and find EJB objects of the same type (i.e., they are implemented by the same enterprise bean). The home interface is specified by the bean provider; the container creates a class that implements the home interface. The home interface extends the javax.ejb.EJBHome interface.

A client can locate an enterprise bean home interface through the standard Java Naming and Directory Interface (JNDI) API.

An EJB object is accessible via the enterprise bean's remote interface . The remote interface defines the business methods callable by the client. The remote interface is specified by the bean provider; the container creates a class that implements the remote interface. The remote interface extends the javax.ejb.

EJBObject interface. The javax.ejb.EJBObject interface defines the operations that allow the client to access the EJB object's identity and create a persistent handle for the EJB object.

Each EJB object lives in a home, and has a unique identity within its home. For session beans, the container is responsible for generating a new unique identifier for each session object. The identifier is not exposed to the client. However, a client may test if two object references refer to the same session object. For entity beans, the bean provider is responsible for supplying a primary key at entity object creation time; ^[1] the container uses the primary key to identify the entity object within its home. A client may obtain an entity object's primary key via the javax.ejb.EJBObject interface. The client may also test if two object references refer to the same entity object.

^[1] In special situations, the primary key type can be specified at deployment time (see subsection EJB.9.4.7.3).

A client may also obtain the enterprise bean's metadata interface. The metadata interface is typically used by clients who need to perform dynamic invocation of the enterprise bean. (Dynamic invocation is needed if the classes that provide the enterprise client view were not available at the time the client program was compiled.)

EJB.4.2.2 Component Contract

This subsection describes the contract between an enterprise bean and its container. The main requirements of the contract follow. (This is only a partial list of requirements defined by the specification.)

• The requirement for the bean provider to implement the business methods in the enterprise bean class. The requirement for the container provider to delegate the client method invocation to these methods.

• The requirement for the bean provider to implement the ejbCreate , ejbPostCreate, and ejbRemove methods, and to implement the ejbFind<METHOD> methods if the bean is an entity with bean-managed persistence. The requirement for the container provider to invoke these methods during an EJB object creation, removal, and lookup.

• The requirement for the bean provider to define the enterprise bean's home and remote interfaces. The requirement for the container provider to provide classes that implement these interfaces.

• For sessions, the requirement for the bean provider to implement the container callbacks defined in the javax.ejb.SessionBean interface, and optionally the javax.ejb.SessionSynchronization interfaces. The requirement for the container to invoke these callbacks at the appropriate times.

• For entities, the requirement for the bean provider to implement the container callbacks defined in the javax.ejb.EntityBean interface. The requirement for the container to invoke these callbacks at the appropriate times.

• The requirement for the container provider to implement persistence for entity beans with container-managed persistence.

• The requirement for the container provider to provide the javax.ejb.SessionContext interface to session bean instances, and the javax.ejb.EntityContext interface to entity bean instances. The context interface allows the instance to obtain information from the container.

• The requirement for the container to provide to the bean instances the JNDI API context that contains the enterprise bean's environment.

• The requirement for the container to manage transactions, security, and exceptions on behalf of the enterprise bean instances.

• The requirement for the bean provider to avoid programming practices that would interfere with the container's runtime management of the enterprise bean instances.

EJB.4.2.3 EJB JAR File

An EJB JAR file is a standard format used by EJB tools for packaging enterprise beans with their declarative information. The EJB JAR file is intended to be processed by application assembly and deployment tools.

The EJB JAR file is a contract used both between the bean provider and the application assembler, and between the application assembler and the deployer.

The EJB JAR file includes:

• Java class files for the enterprise beans and their remote and home interfaces.

• An XML deployment descriptor . The deployment descriptor provides both the structural and application assembly information about the enterprise beans in the EJB JAR file. The application assembly information is optional. (Typically, only EJB JAR files with assembled applications include this information.)

EJB.4.2.4 Contracts Summary

Figure EJB.4-1 illustrates the Enterprise JavaBeans contracts.

Figure EJB.4-1. Enterprise JavaBeans Architecture Contracts

Note that while the figure illustrates only a remote client running outside the container, the client-view API is also applicable to clients that are enterprise beans deployed in the same container.