The WebLogic Enterprise JavaBeans (EJB) Programming Environment


	Corporate Info \| News \| Solutions \| Products \| Partners \| Services \| Events \| Download \| How To Buy
	http://www.oracle.com/technology/documentation/index.html \| Site Map \| Search \| PDF Files \| Contact \| Glossary

WebLogic Enterprise Doc Home \| Getting Started & Related Topics \| Previous Topic \| Next Topic \| Contents \| Index

This topic includes the following sections:

Overview of the WebLogic Enterprise EJB Programming Environment

The Enterprise JavaBeans Specification 1.1, published by Sun Microsystems, Inc., defines a component architecture for building distributed, object-oriented business applications in Java. The EJB architecture addresses the development, deployment, and run-time aspects of an enterprise application's lifecycle.

An EJB encapsulates business logic inside a component framework that manages the details of security, transaction, and state management. Low-level details, such as the following, are handled by the EJB container:

Multithreading
Resource pooling
Scaling
Distributed naming
Automatic persistence
Remote invocation
Transaction boundary management
Distributed transaction management

This built-in, low-level support allows the EJB to focus on the business problem to be solved.

With the WebLogic Enterprise EJB model, you can write or buy business components (such as invoices, bank accounts, and shipping routes) and, during deployment into a certain project, specify how the component should be used -- which users have access to which methods, whether the container should automatically start a transaction or whether it should inherit the caller's transaction, and so on. In this scenario, an EJB contains the business logic (methods) and the customization needed for a particular application (deployment descriptor), and the EJB will run within any standard implementation of the EJB container. An EJB is, in essence, a distributed object for which transactions and security can be specified declaratively in deployment descriptors.

The spirit of "write once, run anywhere" carries through into EJB: any vendors's EJB container (that conforms to the EJB Specification) can run any third-party EJBs (that also conform to the EJB Specification) to create an application. Nuances of the security mechanisms and specific distributed transaction monitors are entirely abstracted out of the application code (unless the Bean Provider chooses to make such calls explicitly).

Types of Beans Supported in WebLogic Enterprise

With the WebLogic Enterprise system, you can build and deploy standard, portable EJBs. The EJB Specification defines three types of beans as listed and described in Table 3-1.

Table 3-1 Bean Types Specified by the EJB Specification

Bean Type
Description

Stateless session bean

An instance of a stateless session bean has no conversational state for the client that created the instance. This instance is not assigned permanently to the client. The EJB container can maintain a pool of instances and allocate method invocations coming from any client to any available instance (that is, not processing a request for a particular client). Therefore, any instance can receive method invocations from any client, and these requests can be processed on behalf of different transactions and security contexts.

The EJB container decides the life of an instance; that is, the container can destroy an instance when resources are required or according to other policies. However, the client decides the life of the reference to the bean. The reference obtained from the bean's home interface is valid until the client destroys it.

Note that stateless session beans cannot use the SessionSynchronization interface to synchronize with the starting and stopping of a transaction.

Stateful session bean

An instance of a stateful session bean maintains a conversational state for the client that created the instance. Therefore, instances of a stateful session bean are assigned to a particular client and are destroyed only when the client decides to remove the EJB object. Instances of stateful session beans do not survive a crash of the EJB container (which in WebLogic Enterprise spans all the processes in the same group where the bean is deployed) or a redeployment of the bean.

The EJB container can passivate inactive instances to maximize the use of the system resources -- that is, to deactivate the bean with its state saved to be restored at a later time during the bean's reactivation. Stateful session beans can use the SessionSynchronization interface to synchronize with the starting and stopping of a transaction.

Entity bean

An instance of an entity bean has a unique identity called the primary key. Object references to an entity bean should be usable for a long time and clients should be able to reuse them across server crash or restart. The reference becomes invalid when a client application removes the EJB or when the EJB is reconfigured.

Note: If a server group crashes, and the System Administrator restarts that group using the same group ID and persistence store, the EJB container can process requests for beans in that group again. The EJB container for stateless session beans spans the entire domain in which the beans are deployed.

Multiple client applications can access an entity bean instance; the EJB container is responsible for synchronizing the access to the instance.

Typically, an entity bean has a persistent state, and application designers can choose between managing the persistence directly from the bean (bean-managed) or letting the EJB container manage the persistence (container-managed). In either case, the EJB container determines when an entity bean instance can be passivated (which also triggers the persistent storage of the state of the instance). An entity bean cannot use the SessionSynchronization interface to synchronize with the starting and stopping of a transaction.

Bean Type	Description
Stateless session bean	An instance of a stateless session bean has no conversational state for the client that created the instance. This instance is not assigned permanently to the client. The EJB container can maintain a pool of instances and allocate method invocations coming from any client to any available instance (that is, not processing a request for a particular client). Therefore, any instance can receive method invocations from any client, and these requests can be processed on behalf of different transactions and security contexts. The EJB container decides the life of an instance; that is, the container can destroy an instance when resources are required or according to other policies. However, the client decides the life of the reference to the bean. The reference obtained from the bean's home interface is valid until the client destroys it. Note that stateless session beans cannot use the SessionSynchronization interface to synchronize with the starting and stopping of a transaction.
Stateful session bean	An instance of a stateful session bean maintains a conversational state for the client that created the instance. Therefore, instances of a stateful session bean are assigned to a particular client and are destroyed only when the client decides to remove the EJB object. Instances of stateful session beans do not survive a crash of the EJB container (which in WebLogic Enterprise spans all the processes in the same group where the bean is deployed) or a redeployment of the bean. The EJB container can passivate inactive instances to maximize the use of the system resources -- that is, to deactivate the bean with its state saved to be restored at a later time during the bean's reactivation. Stateful session beans can use the SessionSynchronization interface to synchronize with the starting and stopping of a transaction.
Entity bean	An instance of an entity bean has a unique identity called the primary key. Object references to an entity bean should be usable for a long time and clients should be able to reuse them across server crash or restart. The reference becomes invalid when a client application removes the EJB or when the EJB is reconfigured. Note: If a server group crashes, and the System Administrator restarts that group using the same group ID and persistence store, the EJB container can process requests for beans in that group again. The EJB container for stateless session beans spans the entire domain in which the beans are deployed. Multiple client applications can access an entity bean instance; the EJB container is responsible for synchronizing the access to the instance. Typically, an entity bean has a persistent state, and application designers can choose between managing the persistence directly from the bean (bean-managed) or letting the EJB container manage the persistence (container-managed). In either case, the EJB container determines when an entity bean instance can be passivated (which also triggers the persistent storage of the state of the instance). An entity bean cannot use the SessionSynchronization interface to synchronize with the starting and stopping of a transaction.

EJBs and Persistence

An entity EJB can save its state in any transactional or nontransactional persistent storage, or it can ask the EJB container to save its nontransient instance variables automatically. The WebLogic Enterprise system allows both choices. An EJB that manages its own persistence is referred to as having bean-managed persistence; an EJB that delegates to the EJB container the saving and restoring of its state is referred to as having container-managed persistence.

You control the persistence characteristics of a bean, such as where its data is maintained in durable storage, in its deployment descriptor; in the case of bean-managed persistence, you implement the specific method invocations in the bean that load and store state.

For more information about development and deployment considerations with regards to persistence, see the following topics:

Roles of People Who Develop, Build, Deploy, and Administer EJBs

The Enterprise JavaBeans Specification describes the six roles regarding who develops, builds, deploys, and administers an EJB application. These roles are summarized in Table 3-2 to help clarify what needs to be done, by whom, and when during the entire life cycle of an EJB in a way that is consistent with the EJB Specification.

Table 3-2 EJB Roles

Role
Description

Enterprise Bean Provider

The Enterprise Bean Providers (or Bean Providers) produce enterprise beans. Their output is an EJB Java ARchive (EJB JAR) file that contains one or more enterprise beans. The Bean Provider is responsible for:

The Java classes that implement the enterprise bean's business methods
The definition of the bean's remote and home interfaces
The bean's deployment descriptor
The deployment descriptor includes the structural information (for example, the name of the enterprise bean class) of the enterprise bean and declares all the enterprise bean's external dependencies (for example, the names and types of resources that the enterprise bean uses).

Application Assembler

The Application Assembler combines enterprise beans into larger deployable application units. The input to the Application Assembler is one or more EJB JAR files produced by the Bean Providers. The Application Assembler outputs one or more EJB JAR files that contain the enterprise beans along with their application assembly instructions. The Application Assembler has inserted the application assembly instruction into the deployment descriptors.

Bean providers cooperate with the Application Assembler to combine EJBs into larger deployable units. In the WebLogic Enterprise environment, creating these larger deployable units is more efficient if the Application Assembler takes into account the scalability and resource management capabilities provided by the WebLogic Enterprise environment. For example, EJBs that access the same resources should be packaged together. The Application Assembler also specifies the security required by the application by associating client role names with the methods of the different beans.

Deployer

The Deployer uses the EJB container tools to customize one or more EJB JAR files produced by a Bean Provider or Application Assembler so that the beans can run in the corresponding EJB environment. These tools generate the additional classes required to manage the beans. The Deployer is primarily focused on the individual EJBs.

In the WebLogic Enterprise environment, the Deployer uses the ejbc command or the WebLogic EJB Deployer for this purpose. These tools can also be used by the Application Assembler to construct an EJB package, which is the EJB JAR file containing all the bean implementations and the assembly instructions. The Deployer also ensures that the security role names defined by the Application Assembler map to existing user groups and accounts that exist in the EJB environment.

The Deployer must resolve all the external dependencies declared by the Bean Provider (for example, Deployers must ensure that all resources used by the enterprise beans are present in the operational environment, and they must bind them to the resource manager connection factory references declared in the deployment descriptor), and must follow the application assembly instructions defined by the Application Assembler.

EJB Server Provider

The EJB Server Provider (in the WebLogic Enterprise system, this is BEA) is a specialist in the area of distributed transaction management, distributed objects, and other lower-level, system-level services.

EJB Container Provider

The EJB Container Provider (in the WebLogic Enterprise system, this is BEA) provides:

The deployment tools necessary for the deployment of enterprise beans
The run-time support for the deployed enterprise beans' instances
From the perspective of the enterprise beans, the container is a part of the target operational environment. The container run time provides the deployed enterprise beans with transaction and security management, network distribution of clients, scalable management of resources, and other services that are generally required as part of a manageable server platform.

System Administrator

The System Administrator is responsible for the configuration and administration of the enterprise's computing and networking infrastructure, which includes the EJB server and container. The System Administrator is also responsible for overseeing the well-being of the deployed enterprise bean applications at run time.

The System Administrator cooperates with the Deployer to define the environment needed by the application. The System Administrator configures the WebLogic Enterprise domain by defining the different machines, server groups, and other resources needed by the application (for example, JDBC connection pools and XA resource managers).

The System Administrator also needs to add any security information needed by the application (for example, new user groups). The administrator is also responsible for monitoring the application and performing any run-time changes needed to adapt the operational environment to failures or other conditions.

Role	Description
Enterprise Bean Provider	The Enterprise Bean Providers (or Bean Providers) produce enterprise beans. Their output is an EJB Java ARchive (EJB JAR) file that contains one or more enterprise beans. The Bean Provider is responsible for: The Java classes that implement the enterprise bean's business methods The definition of the bean's remote and home interfaces The bean's deployment descriptor The deployment descriptor includes the structural information (for example, the name of the enterprise bean class) of the enterprise bean and declares all the enterprise bean's external dependencies (for example, the names and types of resources that the enterprise bean uses).
Application Assembler	The Application Assembler combines enterprise beans into larger deployable application units. The input to the Application Assembler is one or more EJB JAR files produced by the Bean Providers. The Application Assembler outputs one or more EJB JAR files that contain the enterprise beans along with their application assembly instructions. The Application Assembler has inserted the application assembly instruction into the deployment descriptors. Bean providers cooperate with the Application Assembler to combine EJBs into larger deployable units. In the WebLogic Enterprise environment, creating these larger deployable units is more efficient if the Application Assembler takes into account the scalability and resource management capabilities provided by the WebLogic Enterprise environment. For example, EJBs that access the same resources should be packaged together. The Application Assembler also specifies the security required by the application by associating client role names with the methods of the different beans.
Deployer	The Deployer uses the EJB container tools to customize one or more EJB JAR files produced by a Bean Provider or Application Assembler so that the beans can run in the corresponding EJB environment. These tools generate the additional classes required to manage the beans. The Deployer is primarily focused on the individual EJBs. In the WebLogic Enterprise environment, the Deployer uses the ejbc command or the WebLogic EJB Deployer for this purpose. These tools can also be used by the Application Assembler to construct an EJB package, which is the EJB JAR file containing all the bean implementations and the assembly instructions. The Deployer also ensures that the security role names defined by the Application Assembler map to existing user groups and accounts that exist in the EJB environment. The Deployer must resolve all the external dependencies declared by the Bean Provider (for example, Deployers must ensure that all resources used by the enterprise beans are present in the operational environment, and they must bind them to the resource manager connection factory references declared in the deployment descriptor), and must follow the application assembly instructions defined by the Application Assembler.
EJB Server Provider	The EJB Server Provider (in the WebLogic Enterprise system, this is BEA) is a specialist in the area of distributed transaction management, distributed objects, and other lower-level, system-level services.
EJB Container Provider	The EJB Container Provider (in the WebLogic Enterprise system, this is BEA) provides: The deployment tools necessary for the deployment of enterprise beans The run-time support for the deployed enterprise beans' instances From the perspective of the enterprise beans, the container is a part of the target operational environment. The container run time provides the deployed enterprise beans with transaction and security management, network distribution of clients, scalable management of resources, and other services that are generally required as part of a manageable server platform.
System Administrator	The System Administrator is responsible for the configuration and administration of the enterprise's computing and networking infrastructure, which includes the EJB server and container. The System Administrator is also responsible for overseeing the well-being of the deployed enterprise bean applications at run time. The System Administrator cooperates with the Deployer to define the environment needed by the application. The System Administrator configures the WebLogic Enterprise domain by defining the different machines, server groups, and other resources needed by the application (for example, JDBC connection pools and XA resource managers). The System Administrator also needs to add any security information needed by the application (for example, new user groups). The administrator is also responsible for monitoring the application and performing any run-time changes needed to adapt the operational environment to failures or other conditions.

Items You Create for an EJB Application

Table 3-3 summarizes all the items you need to create for an EJB application that runs in the WebLogic Enterprise environment, regardless of which role you are assuming, and explains where you can find more information about creating the item.

Table 3-3 Items You Create for an EJB Application

Item
Description
Where to Find More Information

One or more EJBs

The basic beans containing your application's business logic.

Step 1: Create the EJB

Deployment descriptor

An XML file, created by one of the following methods, that specifies basic configuration and run-time information relevant to the deployment of the EJBs:

DDGenerator command
WebLogic EJB Deployer
Manually, using a common text editor

Step 3: Create the Deployment Descriptor and Step 6: Modify the Deployment Descriptor

EJB JAR file

A Java ARchive (JAR) file that contains all the Java class files for the EJBs in the application. This file is created initially by the Bean Provider, and is then modified by the Bean Deployer and Application Assembler.

Step 4: Create a Standard EJB JAR File and Step 7: Package the Components Into a Deployable EJB JAR File

WebLogic EJB extensions to the deployment descriptor DTD

An XML file, specifying configuration information pertinent to the WebLogic Enterprise environment.

Step 5: Create the WebLogic EJB Extensions to the Deployment Descriptor DTD

Module initializer object

A Java object specifying the module initializer class. This entity is optional.

Step 2: Create the Module Initializer Object

Item	Description	Where to Find More Information
One or more EJBs	The basic beans containing your application's business logic.	Step 1: Create the EJB
Deployment descriptor	An XML file, created by one of the following methods, that specifies basic configuration and run-time information relevant to the deployment of the EJBs: DDGenerator command WebLogic EJB Deployer Manually, using a common text editor	Step 3: Create the Deployment Descriptor and Step 6: Modify the Deployment Descriptor
EJB JAR file	A Java ARchive (JAR) file that contains all the Java class files for the EJBs in the application. This file is created initially by the Bean Provider, and is then modified by the Bean Deployer and Application Assembler.	Step 4: Create a Standard EJB JAR File and Step 7: Package the Components Into a Deployable EJB JAR File
WebLogic EJB extensions to the deployment descriptor DTD	An XML file, specifying configuration information pertinent to the WebLogic Enterprise environment.	Step 5: Create the WebLogic EJB Extensions to the Deployment Descriptor DTD
Module initializer object	A Java object specifying the module initializer class. This entity is optional.	Step 2: Create the Module Initializer Object

Tools and Facilities Provided for Building and Deploying EJBs

To help application programmers and deployers build EJBs that fully leverage the WebLogic Enterprise system, the WebLogic Enterprise software provides the tools and facilities listed in Table 3-4.

Table 3-4 Resources for Building and Deploying EJBs

Tool or Facility
Description

ejbc command

Used by application programmers, Application Assemblers, and deployers as a command-line alternative to the WebLogic EJB Deployer to construct a deployable EJB JAR file.

DDGenerator command

Used by the Bean Provider to create the initial deployment descriptor file.

WebLogic EJB Deployer

Used by the Bean Provider, Bean Deployer, and Application Assembler to configure and deploy EJBs for use with your WebLogic Enterprise server. You can use the WebLogic EJB Deployer to:

Examine an existing EJB and the configurable properties in its deployment descriptor.
Modify the properties and save the changes to a file (.xml or .jar format).
Generate EJB interface classes for a particular WebLogic environment.
Generate deployment classes for the beans.
The WebLogic EJB Deployer is documented in the online help available from that tool's Help menu.

UBBCONFIG file

Used for configuring the EJB container and the Java server in which the EJB container is run and which loads the JVM and other modules needed by the EJB application. (You can also use the TMIB in place of the UBBCONFIG file.)

Tool or Facility	Description
ejbc command	Used by application programmers, Application Assemblers, and deployers as a command-line alternative to the WebLogic EJB Deployer to construct a deployable EJB JAR file.
DDGenerator command	Used by the Bean Provider to create the initial deployment descriptor file.
WebLogic EJB Deployer	Used by the Bean Provider, Bean Deployer, and Application Assembler to configure and deploy EJBs for use with your WebLogic Enterprise server. You can use the WebLogic EJB Deployer to: Examine an existing EJB and the configurable properties in its deployment descriptor. Modify the properties and save the changes to a file (.xml or .jar format). Generate EJB interface classes for a particular WebLogic environment. Generate deployment classes for the beans. The WebLogic EJB Deployer is documented in the online help available from that tool's Help menu.
UBBCONFIG file	Used for configuring the EJB container and the Java server in which the EJB container is run and which loads the JVM and other modules needed by the EJB application. (You can also use the TMIB in place of the UBBCONFIG file.)

For more information about deploying and administering EJB applications in the WebLogic Enterprise environment, see Developing WebLogic Enterprise EJB Applications.

EJBs and Failover in the WebLogic Enterprise Environment

The WebLogic Enterprise system provides the following failover characteristics of EJB applications deployed in a WebLogic Enterprise domain. Note that client applications cannot control where EJBs are instantiated. Figure 3-1 shows how, in the instance of a machine crash, failover is managed wholly by the WebLogic Enterprise system.

Figure 3-1 EJB Failover Capabilities in WebLogic Enterprise

Stateless session beans. If the server process hosting a stateless session bean fails, the bean is automatically instantiated in a different server process (on the same server or on another group within the domain), provided that the server process that is capable of supporting the session bean is available.

Entity beans. If one group that hosts one or more entity beans fails and in cases when the client application receives a RemoteException, the client application can invoke the findByPrimaryKey method to find the home interface for the entity bean, with the specified unique key, on another group in the domain. This works as long as the other group is configured to support that entity bean. Application developers can write client application code within a loop that begins by invoking the findByPrimaryKey method; this way, if a group fails, the client application retries the invocation on a different group.

Note that, for bean-managed persistence, the Bean Provider must implement this method explicitly; for container-managed persistence, this method is generated automatically.

Stateful session beans. If one group fails, the administrator must dynamically configure the group on a different machine. For more information, see the Administration Guide in the WebLogic Enterprise online documentation.

For file-based persistence, recovery depends on whether persistence storage resides on a file system that is still network accessible (for example, an NFS-mounted volume). Because the persistence-store-directory-root element in the WebLogic Enterprise EJB extensions to the deployment descriptor DTD specifies the path for persistent storage, the bean's state can be recovered. (Note that this file persistence mechanism is internal to the WebLogic Enterprise system.)

For JDBC-based persistence, the application simply reconnects to the database, as long as the DBMS node is running and the network is accessible to the new node.

Note: In general, you should use JDBC-based persistence for production applications because it is more robust than file-based persistence. File-based persistence is typically appropriate only for development and prototyping purposes.

Table 3-1 Bean Types Specified by the EJB Specification

Table 3-2 EJB Roles

Table 3-3 Items You Create for an EJB Application

Table 3-4 Resources for Building and Deploying EJBs