The J2EE Model for EJB Access

All EJBs are managed by the Geronimo container, and execute under the auspices of OpenEJB 2 - the business-tier container within Geronimo. Access to EJB can be from a source either internal or external to the Geronimo server.

Internal access includes the following:

• Access from Web-tier components

• Access from other EJB components

• Access from the client application container

External access includes the following:

• Access from non-J2EE client

• Access via CORBA to EJB interoperations

• Access via Web service to EJB support

The configurations required to support these access methods are different. The focus in this chapter is on the deployment of modules for internal access. Chapter 15 explains how to configure and deploy modules for Web services and CORBA access. Access from non-J2EE client via means other than CORBA and Web services requires specialized coding and is highly application-specific; it is out of the scope of this book.

Since EJBs are typically passive code modules, they do not perform any tasks until one of their methods is invoked. To access an EJB, you must first obtain a reference to it. Components that utilize EJBs typically perform the lookup (for EJBs) using JNDI APIs. The JNDI API is an essential J2EE 1.4 API that allows the dynamic lookup of EJB at run time. In addition, the use of JNDI enables the same EJB consumer components to be deployed on any application server that supports JNDI lookup of EJBs.

J2EE applications are componentized, and each component can typically be deployed separately. This enables code reuse and maximum configuration flexibility. Depending on requirements, different EJB components can be wired up for a consumer.

Geronimo manages all the EJBs that run within it. It provides the JNDI interface to EJB consumer components. As an administrator and deployer, you will have control over the exact wiring of EJB components for an application. By associating references to specific EJB components with specific JNDI names, you can customize your deployment and application assembly according to particular business needs. Because of this, it is important to understand how to reference EJBs in Geronimo and to become familiar with where EJB references may be used within the deployment plans.

Web-Tier EJB and Resource References

In formal multi-tiered server design, the Web-tier presentation logic makes frequent use of the EJBs located in the business tier to perform business logic operations. This requires the lookup of business-tier EJBs, from Web-tier modules. Since Web-tier modules must be deployable as independent entities (as specified in the J2EE specifications), the Web-tier component code does not refer to the EJBs that it needs directly. Instead, it dynamically makes JNDI calls at run time to look up the EJBs that it needs. This lookup is via a JNDI reference name. Every Web-tier module must declare these reference names in a deployment descriptor. In this way, external references are explicitly specified by J2EE Web-tier components.

It is the job of the application deployer to wire up these reference names to actual EJB references during configuration and deployment. The syntax for actual EJB references can be different between application servers. Because of this, the mapping between JNDI reference name and EJB references is often performed in a container-specific deployment plan. In the case of Web-tier components in Geronimo, this container-specific deployment plan is the geronimo-web.xml. In the geronimo-web.xml plan of a deployed application, you will find detailed mapping between JNDI reference name and references to Geronimo-managed EJBs. EJBs are considered external references with respect to the deployed WAR component.

Figure 12-1 shows the J2EE packaging for Web-tier application, with a particular focus on external references to EJBs and other resources. Chapters 10 and 11 discuss the actual deployment of these applications. External references of a Web-tier module are not limited to EJBs alone. In Figure 12-1, notice that the WAR file is completely self-contained unit. In addition to external EJB references, the servlets and JSPs may have references to one or more of the following:

• External adapters (such as JDBC connectors or JMS connection factories)

• External resources

• External environment variables

Figure 12-1: Web-tier module references to business-tier EJBs and other resources

At the time the developer actually writes and creates the code of the servlets and JSPs in the WAR file, it is usually not possible to know what these external references will refer to. This situation is analogous to the EJB lookup one. To make deployment as flexible as possible, all of these external references are coded as a JNDI lookup against intermediate JNDI reference names. As with EJB lookup reference names, these resource reference names are tallied and specified within the deployment descriptor. For a WAR file, this deployment descriptor is the web.xml file under the WEB-INF directory of the archive.

External References in EJB JAR Files

References to external EJBs and resources are not exclusive to Web-tier modules. In fact, EJBs themselves can have dependencies on other EJBs or resources. Figure 12-2 illustrates the familiar situation.

Figure 12-2: Business-tier references to separately deployed EJBs and other resources

Figure 12-2 reveals that EJBs in one EJB JAR file can refer to other separately deployed EJBs. In the same manner as Web-tier external references, EJBs look up one another via JNDI names. These JNDI names are declared in their J2EE deployment descriptor - ejb.xml. This deployment descriptor can be found under the META-INF subdirectory of a typical EJB JAR archive file. To wire up these references to actual EJBs managed by Geronimo, the JNDI names must be mapped to EJB references. The EJB reference syntax is unique to Geronimo, and these mappings are defined in the open-ejb.xml deployment plan. This plan can be either embedded within the EJB JAR file (under the META-INF subdirectory) or specified externally when the EJBs are deployed.

Resolving Local References within an EAR Module

An EAR module combines multiple WAR and EJB JAR modules into an enterprise application. When an EAR is created, references to EJBs in the EJB JAR modules can often be resolved without additional deployment plans. This may include references from Web-tier components in the WAR files to business-tier EJBs, or it may be references between EJBs. All of these references exist as JNDI names in deployment descriptors. When a referenced EJB is local within the same EAR module, however, the wiring can be optimized. Geronimo allows you to map JNDI names to local references in this case. Local references can often provide high-performance access to components, since direct access to the referenced objects is possible. Both the consumer and the component referenced are usually within the same JVM.

Figure 12-3 illustrates this situation.

Figure 12-3: Resolved EJB references within an EAR module

In Figure 12-3, some references to EJBs can be resolved internally, while others are external and must be explicitly mapped in the Geronimo-specific deployment plan. For those that can be internally mapped, Geronimo tries to be very intelligent in locating the referenced EJB. Namely, Geronimo will do the following:

• Look for EJBs within its management that support the referenced LocalHome interface

• Look for EJBs within its management that support the referenced EJBHome interface

This strategy simplifies the configuration of internally referenced EJBs in most situations.

If there are multiple or no EJBs supporting the required interfaces, Geronimo will not be able to resolve the internal reference automatically, and the reference must be explicitly mapped in the deployment plan. When using externally referenced EJBs, the deployer/administrator must map them explicitly.

Mapping External References

The task of deploying J2EE modules to Geronimo frequently requires careful mapping of external references. External reference mappings are required when Web-tier components or business-tier EJBs refer to EJB references that cannot be resolved internally within an EAR. In these cases, additional Geronimo-specific deployment plans must be crafted to map the references specified in the J2EE deployment descriptor to actual external EJBs. Figure 12-4 illustrates this mapping exercise.

Figure 12-4: Mapping external EJB references via a Geronimo-specific deployment plan

In Figure 12-4, it is evident that one major purpose for a Geronimo-specific deployment plan is to map declared references in a J2EE deployment descriptor to actual components within a Geronimo deployment. This mapping is not limited to externally deployed EJBs, but also applies to other container-managed objects (such as JMS admin objects, security roles, and JCA resource adapters).

Table 12-1 shows the J2EE descriptors (where the external references are declared) and their associated Geronimo-specific deployment plan (where the references are mapped to container-managed objects).

Table 12-1: J2EE Descriptors and Associated Geronimo Deployment Plan
Open table as spreadsheet

J2EE Deployment Descriptor	Geronimo-Specific Deployment Plan
web.xml	geronimmo-web.xml
ejb-jar.xml	openejb-jar.xml
application.xml	geronimo-application.xml
ra.xml	geronimo-ra.xml

Uses for most of these deployment descriptors and deployment plans will be shown in the following example.