Developing WebLogic Enterprise EJB Applications

 

This chapter provides a step-by-step tutorial that explains how to create an EJB application that you can build and run in the WebLogic Enterprise environment. The steps described in this chapter use the statefulSession EJB sample application provided with the WebLogic Enterprise software. The statefulSession example exists in the following location on your system:

Windows NT

$TUXDIR\samples\j2ee\ejb\basic\statefulSession

UNIX

$TUXDIR/samples/j2ee/ejb/basic/statefulSession

This topic includes the following sections:

• Overview of the Development Process for WebLogic Enterprise EJB Applications

• The statefulSession EJB Sample Application

• Developing EJB Applications

• Building and Deploying EJB Applications

• WebLogic Enterprise EJB Sample Applications

Note the following about using this chapter:

• The steps in this chapter lead you through the process of creating an EJB that can be deployed in the WebLogic Enterprise environment, also known as a deployable EJB. To create a standard EJB -- that is, a portable bean that lacks the extensions specific to the WebLogic Enterprise environment -- see Designing Enterprise JavaBeans for the WebLogic Enterprise System.

• For a more thorough understanding of Enterprise JavaBeans, especially with regards to background information and programming considerations, refer to the following resources:

  • Valesky, T. 1999. Enterprise JavaBeans: Developing Component-Based Distributed Applications. Addison-Wesley.

  • Sun Microsystems, Inc. Enterprise JavaBeans Specification 1.1.

 

---

Overview of the Development Process for WebLogic Enterprise EJB Applications

Table 7-1 outlines the development process for WebLogic Enterprise EJB applications.

Table 7-1 EJB Application Development Process in WebLogic Enterprise

Step	Description
1	Create the EJB.
2	Create the module initializer class.
3	Create the deployment descriptor.
4	Create a standard EJB JAR file.
5	Create the WebLogic extensions to the deployment descriptor DTD.
6	Modify the Deployment Descriptor.
7	Package the components into a deployable EJB JAR file.
8	Configure the EJB application.
9	Create the client application.
10	Start and run the WebLogic Enterprise EJB application.
11	Dynamically manage the EJB deployment.

Figure 7-1 illustrates the process for developing WebLogic Enterprise EJB applications. In this figure, the shaded objects represent entities you need to create.

Figure 7-1 Process for Developing WebLogic Enterprise EJB Applications

 

---

The statefulSession EJB Sample Application

The statefulSession sample application shows how repeated calls to the same session bean have a persistent state -- the change in the cash account -- that is maintained across all the calls. Notice that neither the client nor the EJB do anything to maintain that state: the container handles it transparently. All the logic for the cash account is encapsulated in the bean, unlike the stateless session sample where all persistence is provided by the client.

The EJB in this sample provides basic trading methods such as buying and selling stocks. Since there are no persistent stores involved in this sample, all the stock data are set in the deployment descriptor of the EJB as environment properties. The container supplies the data to the EJB through the JNDI lookup operation.

This sample provides two types of clients: one is a simple, single-threaded RMI client application, and the other is a multithreaded RMI client application. The statefulSession bean sample application implements the classes listed and described in Table 7-2.

Table 7-2 Classes Implemented in the Stateful Session Bean Example

Class	Description
Client	This class: Creates an InitialContext class. Creates a trader, and performs repeated buying and selling of shares. Shows persistence of state between calls to the TraderBean; the client does not do anything to maintain state between calls. Searches the JNDI tree for an appropriate container.
MultiClient	This class: Creates an InitialContext class. Creates a trader, and performs repeated buying and selling of shares. Shows calling a stateful session bean using multiple colocated clients: each thread is a trader, and performs repeated buying and selling of shares. Shows persistence of state between calls to the TraderBean bean. Like the single-threaded Client bean, the MultiClient bean does not do anything to maintain state between calls.
TraderBean	This bean does not manage any persistence of state between invocations on it. Creating the business methods on this bean is described in the section Create the Bean's Implementation Class.
TradeResult	This bean contains the results of a buy/sell transaction.

Figure 7-2 shows how the stateful session bean example works.

Figure 7-2 Stateful Session Bean Sample Application

 

---

Developing EJB Applications

This section describes the following steps for developing an EJB application in the WebLogic Enterprise system:

• Step 1: Create the EJB

• Step 2: Create the Module Initializer Object

• Step 3: Create the Deployment Descriptor

• Step 4: Create a Standard EJB JAR File

Step 1: Create the EJB

The EJB Specification 1.1, published by Sun Microsystems, Inc., describes the different requirements of the EJB writer and the EJB framework; EJBs created for the WebLogic Enterprise environment must conform to those requirements. When you write EJBs, pay close attention to these requirements.

When writing an EJB, you must implement the following:

• The bean's home interface

• The bean's remote interface

• The bean's implementation class, which includes:

  • The business methods for the bean

  • The ejbCreate, ejbPostCreate, and ejbRemove callback methods

  • For session beans, the callbacks defined by the SessionBean interface and, optionally, the callbacks on the SessionSynchronization interface

  • For entity beans, the callbacks defined on the EntityBean interface, and the primary key classes

  • For bean-managed persistence, the ejbLoad and ejbStore callbacks

    Notes: The direct use of threads by Bean Providers is discouraged by the EJB Specification 1.1. This constraint also applies to WebLogic Enterprise server applications -- bean and RMI implementers should not attempt to manage, change properties, start, stop, suspend, or resume a thread or a thread group.

    The ejbc command, which is provided with the WebLogic Enterprise development software, includes a compliance checker utility that examines the packaged EJBs and determines if the EJBs conform to these requirements.

The subsections that follow provide details on implementing an EJB, using the stateful session EJB sample application as an example.

Create the Bean's Home Interface

Each EJB has a home interface that creates instances of the bean. EJB client applications use the home interface as a means of obtaining a reference, or a handle, to the EJB. The home interface is analogous to a factory object in CORBA. The home interface defines the methods used by client applications to create, remove, and find objects of the corresponding EJB type.

The home interface for the statefulSession EJB contains the create method, which corresponds to the ejbCreate method on the EJB itself. The following code example shows the home interface for the TraderBean EJB:

package samples.j2ee.ejb.basic.statefulSession;

import java.rmi.RemoteException;
import javax.ejb.*;


/**
* This interface is the home interface for the TraderBean.java
*/
public interface TraderHome extends EJBHome {
Trader create(String traderName) throws CreateException, RemoteException;
}

Create the Bean's Remote Interface

Each EJB has a well-defined remote interface that defines the EJB callbacks and the business methods that can be invoked by a client. As stated in the EJB Specification 1.1, a client application never directly accesses instances of a bean's class. A client always uses the bean's remote interface to access that bean's instance. The class that implements the bean's remote interface is provided by the EJB container.

The EJB's remote interface does the following:

• Defines the business logic methods of the EJB.

• Supports the methods of the javax.ejb.EJBObject interface. These methods allow the client to:

  • Get the EJB's home interface

  • Get the EJB's handle

  • Test if the EJB is identical with another EJB

  • Remove the EJB

The following business methods are also defined on the remote interface of the TraderBean EJB:

• buy()

• sell()

• getBalance()

• getTraderName()

Listing 7-1 shows the remote interface for the TraderBean EJB.

Listing 7-1 TraderBean Remote Interface

---

package samples.j2ee.ejb.basic.statefulSession;

import java.rmi.RemoteException;
import javax.ejb.*;

/**
 * The methods in this interface are the public face of TraderBean.
 * The signatures of the methods are identical to those of the EJBean, except
 * that these methods throw a java.rmi.RemoteException.
*/

public interface Trader extends EJBObject {

public  TradeResult buy(String customerName, String stockSymbol, int shares)
    throws ProcessingErrorException, RemoteException;

public TradeResult sell(String customerName, String stockSymbol, int shares)
    throws ProcessingErrorException, RemoteException;

public double getBalance() 
    throws RemoteException;

public String getTraderName() 
    throws RemoteException;
}

Create the Bean's Implementation Class

The bean's implementation class includes the following:

• A declaration of the type of bean being implemented (session or entity).

• The business methods on the bean.

• A specific set of callback methods. The set you implement depends on the type of bean you are creating.

Declaring the Bean Type

After you declare your bean's package name and import classes, you declare what interface your bean implements: session or entity. The following line declares that the TraderBean class implements the SessionBean interface:

public class TraderBean implements SessionBean

Implementing the Business Methods on the Bean

The TraderBean EJB implements the following business methods:

• buy()

  Buys shares of a stock for a named customer.

• sell()

  Sells shares of a stock for a named customer.

• getBalance()

  Returns the current balance of a trading session.

• getTraderName()

  Returns the name of the current Trader class.

Implementing the Callback Methods on the Bean

You need to implement the following methods on the bean, which are standard for all beans. These are commonly referred to as callback methods.

• ejbCreate()

  Corresponds to the create method in the home interface TraderHome.java. The parameter sets of the ejbCreate and create methods are identical. When the client calls the create method on the bean's home interface, the EJB container allocates an instance of the TraderBean EJB and then calls the ejbCreate method on the EJB.

• ejbRemove()

  This method is automatically invoked by the EJB container before it ends the life of the session bean. Invoking this method occurs as a result of a client application invoking the remove method on the bean's remote object, or when the EJB container decides to terminate the session object after a timeout. This method is required by the EJB Specification.

• ejbPassivate()

  This method is invoked by the EJB container before a bean is moved into a passive state, causing any resources used by the bean to be released. This method is required by the EJB Specification, but is not used by the statefulSession bean example.

• ejbActivate()

  This method is invoked by the EJB container when a bean is activated from a passive state, causing any resources required by the bean to be restored. This method is required by the EJB Specification, but is not used by the statefulSession bean example.

• setSessionContext()

  This method sets the associated session context. The WebLogic Enterprise container invokes this method after the EJB has been instantiated. The EJB instance should store the reference to the context object in an instance variable.

ejbCreate Callback Example

The following code example shows the ejbCreate method on the TraderBean EJB:

public void ejbCreate(String traderName) throws CreateException {
  printTrace("ejbCreate (" + traderName + ")");
  this.traderName     = traderName;
  this.tradingBalance = 0.0;

setSessionContext Callback Example

The following code example shows the setSessionContext method on the TraderBean EJB, storing the context in the variable ctx:

public void setSessionContext(SessionContext ctx) {
  printTrace("setSessionContext called");
  this.ctx = ctx;
  }

Step 2: Create the Module Initializer Object

The module initializer object is optional for EJB applications that run in the WebLogic Enterprise environment. You use it for specifying special requirements for your EJB application, such as custom operations; for example:

• Performing basic module initialization (or EJB JAR file deployment) operations, which may include allocating resources needed by the EJB JAR file.

• Performing basic server application initialization operations, which may include registering homes or factories managed by the server application and allocating resources needed by the server application.

• Performing server process shutdown and cleanup procedures when the server application has finished servicing requests.

  Notes: For EJBs, the scope of the module initializer object is at the EJB JAR file level and not of the entire server application, as with the Server object and WebLogic Enterprise CORBA applications.

  The statefulSession EJB sample application does not include a module initializer object.

If you have enabled hot redeployment for the modules in your EJB application, the module initializer object is automatically invoked at appropriate times when the module is deployed or undeployed.

You implement this module initializer object by creating a module initializer class that derives from com.beasys.Tobj.Server and by implementing the following two methods on that class:

• initialize

  The initialize method is invoked when the EJB JAR file is loaded (generally when the WebLogic Enterprise server process is booted).

• release

  The release method is invoked when the WebLogic Enterprise server process is shut down or when the EJB JAR file is redeployed to another server process.

In the module initializer object application code, you can also write a public default constructor. You create the module initializer object class from scratch using a text editor.

If you have created a module initializer object, the EJB container parses the WebLogic EJB extensions to the deployment descriptor DTD in each deployed EJB JAR file (specified in the UBBCONFIG file) during startup.

The module-initializer-class-name element in the WebLogic EJB extensions to the deployment descriptor DTD identifies the module initializer object to be used at server initialization and shutdown or, if you are using hot redeployment, when a module is deployed or undeployed. When the server process is booted or a module is deployed, the EJB container instantiates this module initializer object and invokes its initialize method, passing in any startup arguments specified in the UBBCONFIG file. When the server process is shut down or a module is undeployed, the EJB container invokes the module initializer object's release method.

For information about the com.beasys.Tobj.Server base class, see the API Javadoc in the WebLogic Enterprise online documentation. For more information about hot redeployment, see Step 11: Dynamically Manage the EJB Deployment (Hot Redeployment).

Step 3: Create the Deployment Descriptor

The deployment descriptor is an XML file that specifies structural information (for example, the name of the enterprise bean class) about the EJB and declares all the EJB's external dependencies (for example, the names and types of resources that the enterprise bean uses). For complete details on all the elements you can specify in the deployment descriptor, see the EJB XML Reference in the WebLogic Enterprise online documentation.

The deployment descriptor also ties together the different classes and interfaces, and is used by the ejbc command to build the code-generated class files. You can also use the deployment descriptor to specify critical aspects of the EJB's deployment at run time.

You create the deployment descriptor using one of the following methods:

• Using the WebLogic EJB Deployer

• Using the DDGenerator command

• Manually, using a text editor

Note that the DDGenerator command is an unsupported tool. For information about using the DDGenerator command, see the Release Notes.

The deployment descriptor you create must:

• Be valid with respect to the Document Type Definition (DTD) documented in the EJB Specification 1.1

• Conform to the semantics rules specified in the DTD comments and elsewhere in the EJB Specification 1.1

• If you are creating the deployment descriptor from scratch, include the following reference to the deployment descriptor DTD at the beginning of the file:

  <!DOCTYPE ejb-jar PUBLIC "-//Sun Microsystems, Inc.//DTD Enterprise
  JavaBeans 1.1//EN" "http://java.sun.com/j2ee/dtds/ejb-jar_1_2.dtd">

The sections that follow describe the elements you must specify in a deployment descriptor for a given type of EJB, using the statefulSession as an example, and show the EJB Deployer.

Required Elements for Session Beans

The elements that you need to specify in the deployment descriptor for the stateless session EJB is listed and described in Table 7-3.

Table 7-3 Required Elements for Session Beans

Element	Description	Purpose
ejb-name	EJB's name	Specifies the logical name you assign to each EJB in the EJB JAR file. There is no architected relationship between this name and the JNDI name that the Deployer assigns to the EJB.
ejb-class	EJB's class	Specifies the fully qualified name of the Java class that implements the EJB's business methods.
home	EJB's home interface	Specifies the fully qualified name of the EJB's home interface.
remote	EJB's remote interfaces	Specifies the fully qualified name of the EJB's remote interface.
session | entity	EJB's type	The EJB types are session and entity. Use the appropriate session or entity element to declare the EJB's structural information.
session-type	Session bean's state management type	Declares whether the session bean is stateful or stateless.
transaction-type	Session bean's transaction demarcation type	If the EJB is a session bean, declares whether transaction demarcation is performed by the enterprise bean or by the container.

Listing 7-2 shows the deployment descriptor for the statefulSession EJB. Line numbers are added to help with the discussion of this deployment descriptor, which follows.

Listing 7-2 Stateful Session Bean Deployment Descriptor

---

1  <!DOCTYPE ejb-jar PUBLIC "-//Sun Microsystems, Inc.//DTD Enterprise
2  JavaBeans 1.1//EN" "http://java.sun.com/j2ee/dtds/ejb-jar_1_2.dtd">
3  
4  <ejb-jar>
5    <enterprise-beans>
6      <session>
7        <ejb-name>
8          statefulSession
9        </ejb-name>
10       <home>
11         samples.j2ee.ejb.basic.statefulSession.TraderHome
12       </home>
13       <remote>
14         samples.j2ee.ejb.basic.statefulSession.Trader
15       </remote>
16       <ejb-class>
17         samples.j2ee.ejb.basic.statefulSession.TraderBean
18       </ejb-class>
19      <!-- Session bean state management type declaration -->
20      <session-type>
21        Stateful
22      </session-type>
23   <!-- Transaction demarcation type declararion -->
24       <transaction-type>
25         Container
26       </transaction-type>
27       
28       <!-- Environment entries: Stock symbols, and prices -->
29       <env-entry>
30         <env-entry-name>
31           BEAS
32         </env-entry-name>
33         <env-entry-type>
34           java.lang.Double
35         </env-entry-type>
36         <env-entry-value>
37           10.0
38         </env-entry-value>
39       </env-entry>
40             .
41             .
42             .         
43     </session>
44   </enterprise-beans>
45   
46   <!-- Assembly description -->
47   <assembly-descriptor>
48   
49     <!-- Container transaction attributes -->
50     <container-transaction>
51       <method>
52         <ejb-name>
53           statefulSession
54         </ejb-name>
55         
56         <!-- Apply to all the methods (*) of the ejb -->
57         <method-name>
58           *
59         </method-name>
60       </method>
61       
62       <!-- Transaction attributes for the methods -->
63       <trans-attribute>
64         NotSupported
65       </trans-attribute>
66     </container-transaction>
67   </assembly-descriptor>
68 </ejb-jar>

In the preceding deployment descriptor, note the following:

• Lines 7-9 identify statefulSession as the EJB name.

• Lines 10-15 identify the home and remote interfaces.

• Lines 20-22 identify that the statefulSession EJB is stateful.

• Lines 28-42 identify a number of environment entries specific to the statefulSession EJB.

• Lines 46-67 identify assembly descriptor information for transaction attributes. For information about EJBs and transactions, see Using Transactions in the WebLogic Enterprise online documentation.

Using the WebLogic EJB Deployer to Create the Deployment Descriptor

You can use the WebLogic EJB Deployer to create the deployment descriptor for the EJB. Figure 7-3 shows the EJB Deployer main window.

Figure 7-3 WebLogic EJB Deployer Main Window

For information about how to start and use the EJB Deployer, see Using the WebLogic Enterprise EJB Deployer in the WebLogic Enterprise online documentation.

Step 4: Create a Standard EJB JAR File

In this step, you create a standard EJB JAR file. A standard EJB JAR file contains an EJB that has been built, but lacks the specific deployment information on any specific system. You typically build a standard EJB with the goal of being able to distribute that EJB to a variety of deployment environments. Typically, the Bean Provider performs steps 1 through 4, as described in the chapter, and a standard EJB JAR file provides a convenient package that can be handed off to the Application Assembler or Deployer, who may perform steps 5 through 9.

The input to the standard EJB JAR file is typically:

• Compiled class files for the EJB's implementation class, the home interface, and remote interface

• The deployment descriptor

You can create a standard EJB JAR file using the jar command.

 

---

Building and Deploying EJB Applications

This section describes the steps to develop an EJB application for the WebLogic Enterprise system:

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

• Step 6: Modify the Deployment Descriptor

• Step 7: Package the Components Into a Deployable EJB JAR File

• Step 8: Configure the EJB Application

• Step 9: Create the Client Application

• Step 10: Start and Run the WebLogic Enterprise EJB Application

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

For an EJB application to be deployable in the WebLogic Enterprise environment, you need to create a file containing the WebLogic EJB extensions to the deployment descriptor DTD. This file specifies the following run time and configuration information for the EJB application:

• Custom application startup and shutdown properties

• Registration of the application's home interfaces

• Persistence information

For complete details on all the elements you can specify in the WebLogic EJB extensions to the deployment descriptor DTD, see the EJB XML Reference in the WebLogic Enterprise online documentation.

Creating the WebLogic EJB Extensions to the Deployment Descriptor DTD

You can create the file containing the WebLogic EJB extensions to the deployment descriptor DTD using one of the following methods:

• Using the WebLogic EJB Deployer

• By hand, in a common text editor

Specifying the WebLogic EJB Extensions DTD

The file that includes the WebLogic EJB extensions to the deployment descriptor DTD must specify the following DTD reference at the beginning of the file:

<!DOCTYPE weblogic-ejb-extensions SYSTEM "weblogic-ejb-extensions.dtd" >

Registering Names for the EJB Home Classes

A name for the EJB home class must be registered in the global WebLogic Enterprise JNDI namespace. This allows Java clients to perform a lookup on the JNDI name for the EJB home, even across WebLogic Enterprise domains, and gain access to the object. The name for the EJB home class can be different than the <ejb-name> element specified in the standard EJB XML. The <ejb-name> in the standard deployment descriptor must be unique only among the names of the EJBs in the same EJB JAR file. However, the JNDI name must be unique among all global home or factory names in a WebLogic Enterprise domain; this includes EJB homes, CORBA factories, and RMI-named objects.

Example

Listing 7-3 is from the file weblogic-ejb-extensions.xml, which specifies the WebLogic extensions to the deployment descriptor DTD for the stateful session bean example. Line numbers are used to aid in the brief discussion that follows.

Listing 7-3 Specifying the Name of the EJB Home Class

---

1  <weblogic-ejb-extensions>
2    <weblogic-version>
3      WebLogic Enterprise Server 5.0
4    </weblogic-version>
5    <weblogic-enterprise-bean>
6      <ejb-name>
7        statefulSession
8      </ejb-name>
9       <weblogic-deployment-params>
10       <jndi-name>
11         statefulSession.TraderHome
12       </jndi-name>
13               .
14               .
15               .
16      </weblogic-deployment-params>
17 </weblogic-ejb-extensions>

In the preceding WebLogic EJB extensions to the deployment descriptor DTD, note the following lines:

• Lines 9 through 16 contain specific deployment parameters for metrics like the size of the bean pool and the size of the cache.

• Lines 10 through 12 specify the name of the EJB that is registered with JNDI; this is the name on which the client application performs a lookup invocation.

Specifying Persistence Information

The WebLogic Enterprise EJB container provides container-managed persistence. The code for implementing the persistence is generated by the ejbc command based on the deployment descriptors. The persistence store can be a flat file or it can be a database managed with a JDBC connection pool. For the EJB state to fully cooperate in a WebLogic Enterprise global transaction, configure the EJB to use the JDBC-managed database store provided in WebLogic Enterprise. Use file-based persistence only during development and prototyping.

The standard deployment descriptor created by the Bean Provider normally specifies:

• The fields in the EJB that are to be persistent, via the cmp-field element

• For entity beans, information about the primary key

However, you, as the deployer, need to specify additional information for mapping an EJB to its persistent store via the WebLogic EJB extensions to the deployment descriptor DTD.

File-based Persistence

Listing 7-4 shows the WebLogic EJB extensions to the deployment descriptor DTD for specifying file-based persistence.

Listing 7-4 File-based Persistence Elements

---

<!--
Persistence store descriptor. Specifies what type of persistence store
EJB container should use to store state of bean.
-->
<!ELEMENT persistence-store-descriptor (description?,
(persistence-store-file |
persistence-store-jdbc)?)>
<!--
Persistence store using file. Bean is serialized to a file.
Mainly used to store state of Stateful Session Beans.
-->
<!ELEMENT persistence-store-file (description?,
persistence-store-directory-root
?)>
<!--
Root directory on File system for storing files per bean.
-->
<!ELEMENT persistence-store-directory-root (#PCDATA)>

The information supplied for the persistence-store-directory-root element is used by the EJB container to store all instances of the EJB, with the ejb-name element converted to a directory name.

Database-stored Persistence

Listing 7-5 shows the WebLogic EJB extensions to the deployment descriptor DTD for specifying a JDBC connection for database-stored persistence.

Listing 7-5 Database-stored Persistence Elements

---

<!--
Persistence store is any RDBMS. JDBC driver is used to talk to database.
Required for CMP.
-->
<!ELEMENT persistence-store-jdbc (description?, pool-name, user?, password?,
driver-url?, driver-class-name?, table-name, attribute-map,
finder-descriptor*)>

<!-- Required for CMP -->
<!ELEMENT pool-name (#PCDATA)>

<!-- Ignored in WebLogic Enterprise Server as this is part of connection
pool
setup at startup -->
<!ELEMENT user (#PCDATA)>

<!-- Ignored in WebLogic Enterprise Server as this is part of connection
pool
setup at startup -->
<!ELEMENT password (#PCDATA)>

<!-- Ignored in WebLogic Enterprise Server as this is part of connection
pool
setup at startup -->
<!ELEMENT driver-url (#PCDATA)>

<!-- Ignored in WebLogic Enterprise Server as this is part of connection
pool
setup at startup -->
<!ELEMENT driver-class-name (#PCDATA)>

<!-- Required for CMP -->
<!ELEMENT table-name (#PCDATA)>

<!-- Required for CMP -->
<!ELEMENT attribute-map (description?, attribute-map-entry+)>

<!-- Required for CMP -->
<!ELEMENT attribute-map-entry (bean-field-name, table-column-name)>

<!-- Required for CMP -->
<!ELEMENT bean-field-name (#PCDATA)>

<!-- Required for CMP -->
<!ELEMENT table-column-name (#PCDATA)>

<!-- Required for CMP -->
<!ELEMENT finder-descriptor (description?, method?, query-grammar?)>

<!-- Required for CMP -->
<!ELEMENT query-grammar (#PCDATA)>

The EJB instances are stored in a database that has been previously set up with a JDBC connection pool, which is identified by the pool-name element. The table-name and attribute-map elements map the EJB fields to the appropriate table columns in the database.

Finder descriptors are the WebLogic Enterprise implementation of the EJB find methods. The finder-descriptor elements are pairs of method signatures and expressions. You specify a method signature in the EJBHome interface, and you specify the method's expression in the deployment descriptor via the query-grammar element. The finder methods return an enumeration of EJBs. For more information about specifying finder descriptors, see the EJB XML Reference in the WebLogic Enterprise online documentation.

Example

Listing 7-6 is from the file weblogic-ejb-extensions.xml, which specifies the WebLogic extensions to the deployment descriptor DTD for the stateful session bean example to show specifying the persistence information.

Listing 7-6 Persistence Directory Root

---

      <persistence-store-descriptor>
        <persistence-store-file>
          <persistence-store-directory-root>
            c:\mystore
          </persistence-store-directory-root>
        </persistence-store-file>
      </persistence-store-descriptor>

Specifying the Module Initializer Class

If your EJB application uses a module initializer class, as explained in the section Step 2: Create the Module Initializer Object, you need to specify that class among the XML elements for startup and shutdown procedures in the WebLogic EJB extensions to the deployment descriptor DTD. The WebLogic Enterprise EJB container parses the XML at run time and performs the startup and shutdown processing.

Note: The statefulSession EJB sample application does not include a module initializer object.

Step 6: Modify the Deployment Descriptor

The Bean Provider specifies some initial deployment information in the deployment descriptor. The deployer typically needs to add to or modify that information, such as shown in Table 7-4.

Table 7-4 Deployment Descriptor Fields Modified By the Deployer

Field	Description
The EJB's name	You may change the enterprise bean's name defined in the ejb-name element.
Values of environment entries	You may change existing values or define new values for the environment properties.
Description fields	You may change existing or create new description elements.
Binding of enterprise bean references	You may link an enterprise bean reference to another enterprise bean in the EJB JAR file. You create the link by adding the ejb-link element to the referencing bean.
Security roles	You may define one or more security roles. The security roles define the recommended security roles for the clients of the enterprise beans. You define the security roles using the security-role elements. For more information about EJB security, see Using Security in the WebLogic Enterprise online documentation.
Method permissions	You may define method permissions, which are binary relationships between the security roles and the methods of the remote and home interfaces of the EJBs. You define method permissions using the method-permission elements.
Linking of security role references	If you define security roles in the deployment descriptor, you must link the security role references declared by the Bean Provider to the security roles. You define these links using the role-link element. For more information about EJB security, see Using Security in the WebLogic Enterprise online documentation.
Changing persistent storage information, if necessary	The deployer can change the type of persistent storage used by a bean. If the persistentStoreType is file, the serialized files are created in this directory. The default file is /pstore/bean_name.dat, where the directory pstore represents the directory from which the WebLogic Enterprise application was started, and bean_name is the fully qualified name of the EJB with underscores (_) replacing the periods (.) in the name. If the persistentStoreType is jdbc, the container looks for additional values to determine the appropriate values for the JDBC connection. Note that if the bean's persistence is stored in a database via a JDBC connection, the system administrator needs to add this information to the UBBCONFIG file as well. For more information, see Using the JDBC Drivers in the WebLogic Enterprise online documentation. Note that persistence information is specified in the WebLogic EJB extensions to the deployment descriptor DTD file, as described in the section Specifying Persistence Information.

However, if the Bean Provider, the Application Assembler, and the Deployer are the same person, all the information shown in the preceding table may have been specified already in the deployment descriptor step described in Step 3: Create the Deployment Descriptor.

Step 7: Package the Components Into a Deployable EJB JAR File

In this step, you package the deployment descriptor, the compiled files for the EJB classes, and any additional required classes into a deployable EJB JAR file. You can package multiple beans together, provided that there is a deployment descriptor for each bean.

You can use the WebLogic Enterprise ejbc command to create the deployable EJB JAR file. The ejbc command performs the following steps:

1. Parses the standard EJB deployment descriptor and WebLogic Enterprise extended deployment descriptor XML files.

2. Checks the deployment descriptors for semantic consistency, and writes any inconsistencies to standard output.

3. Generates the wrapper Java classes and compiles them. This is performed for each EJB in the deployment descriptor.

4. Packages the XML deployment descriptors and the generated class files into a deployable EJB JAR file.

If you have multiple bean packages meant to be assembled as a deployable unit, the bean packages must be specified in a single deployment descriptor.

The following command line builds the deployable EJB JAR file for the statefulSession bean example:

java weblogic.ejbc -validate -i ejb-jar.xml -x weblogic-ejb-extensions ejb-jar-file

In the preceding command line:

• The -i option specifies the name of the deployment descriptor, ejb-jar.xml.

• The -x option specifies the name of the WebLogic EJB extensions to the deployment descriptor DTD, weblogic-ejb-extensions.

• The file ejb-jar-file is the name of the EJB JAR file.

For more information about the ejbc command, see Commands, System Processes, and MIB Reference in the WebLogic Enterprise online documentation. Note that using the -validate option is recommended.

Step 8: Configure the EJB Application

Because the WebLogic Enterprise software offers great flexibility and many options to application designers and programmers, no two applications are alike. An application, for example, may be small and simple (a single client and server running on one machine) or complex enough to handle transactions among thousands of client and server applications. For this reason, for every WebLogic Enterprise EJB application being managed, the system administrator must provide a configuration file that defines and manages the components (for example, domains, server applications, client applications, and modules) of that application.

When system administrators create a configuration file, they are describing the WLE application using a set of parameters that the WLE software interprets to create a runnable version of the application. During the setup phase of administration, the system administrator's job is to create a configuration file. The configuration file contains the sections listed in Table 7-5.

Table 7-5 Configuration File Sections

Sections in the Configuration File	Description
RESOURCES	Defines defaults (for example, user access and the main administration machine) for the WebLogic Enterprise CORBA application.
MACHINES	Defines hardware-specific information about each machine running in the WebLogic Enterprise CORBA application.
GROUPS	Defines logical groupings of server applications or CORBA interfaces.
SERVERS	Defines the server application processes (for example, the Transaction Manager) used in the WebLogic Enterprise CORBA application.
SERVICES	Defines parameters for services provided by the WebLogic Enterprise application.
MODULES	Defines information about the EJB application process.
JDBCONNPOOLS	Describes the pooling of JDBC connections for Java servers.

When creating a configuration file for an EJB application meant to be run in a WebLogic Enterprise domain, note the following:

• The WebLogic Enterprise EJB container runs in a JavaServer, which you configure in the SERVERS section.

• You configure the EJB application server process using the ejb keyword in the MODULES section. Important: the server group and server ID (specified by the SRVGRP and SRVID keywords, respectively) for the EJB server process must match the server group and server ID for the JavaServer that runs the EJB container.

• You use the FILE parameter in the configuration information for your EJB application to specify the EJB JAR file.

• For complete details about the UBBCONFIG file, see Creating a Configuration File in the WebLogic Enterprise online documentation.

The following section shows an example configuration file used for an EJB application.

Example Configuration File

Listing 7-7 shows a configuration file for the statefulSession bean example. Note in the SERVERS section how the server group and server ID for the JavaServer, in which the EJB container runs, is the same as for the EJB application configured in the MODULES section.

Listing 7-7 Sample UBBCONFIG File

---

#--------------------------------------------------------- 
# D:\BEA\WLE51\test\ejb\basic\statefulSession\ubbconfig.nt   
# Generated for basic\statefulSession EJB Sample 
#--------------------------------------------------------- 
*RESOURCES                               
    IPCKEY    55432                  
    DOMAINID  ejbsample                    
    MASTER    SITE1                     
    MODEL     SHM                       
    LDBAL     N                         
#--------------------------------------------------------- 
*MACHINES                               
    "HOWE"                        
        LMID         = SITE1            
        APPDIR       = "D:\BEA\WLE51\test\ejb\basic\statefulSession"       
        TUXCONFIG    = "D:\BEA\WLE51\test\ejb\basic\statefulSession\tuxconfig"
        TUXDIR       = "d:\BEA\WLE51\m3"       
        MAXWSCLIENTS = 10               
#--------------------------------------------------------- 
*GROUPS                                 
    SYS_GRP                             
        LMID    = SITE1                 
        GRPNO   = 1                     
    APP_GRP                             
        LMID    = SITE1                 
        GRPNO   = 2                     
#--------------------------------------------------------- 
*SERVERS                                
    DEFAULT:                            
        RESTART = Y                     
        MAXGEN  = 5                     
    TMSYSEVT                            
        SRVGRP  = SYS_GRP               
        SRVID   = 1                     
    TMFFNAME                            
        SRVGRP  = SYS_GRP               
        SRVID   = 2                     
        CLOPT   = "-A -- -N -M"         
    TMFFNAME                            
        SRVGRP  = SYS_GRP               
        SRVID   = 3                     
        CLOPT   = "-A -- -N"            
    TMFFNAME                            
        SRVGRP  = SYS_GRP               
        SRVID   = 4                     
        CLOPT   = "-A -- -F"            
    JavaServer                          
        SRVGRP  = APP_GRP               
        SRVID   = 5                     
        CLOPT   = "-A "                 
        RESTART = N                     
    ISL                                 
        SRVGRP  = SYS_GRP               
        SRVID   = 6                     
        CLOPT   = "-A -- -n //HOWE:7001" 
#--------------------------------------------------------- 
*MODULES                                
    ejb                                 
        SRVGRP = APP_GRP                
        SRVID  = 5                      
        FILE   = "D:\BEA\WLE51\test\ejb\basic\statefulSession\ejb_basic_statefulSession.jar"    
*SERVICES                               

Compiling the Configuration File

There are two forms of the configuration file:

• An ASCII version of the file, created and modified with any editor. Throughout the WebLogic Enterprise documentation, the ASCII version of the configuration file is referred to as the UBBCONFIG file. The configuration file may, in fact, be given any file name.

• The TUXCONFIG file, a binary version of the UBBCONFIG file created using the tmloadcf command. When the tmloadcf command is executed, the environment variable TUXCONFIG must be set to the name and directory location of the TUXCONFIG file. The tmloadcf command converts the configuration file to binary form and writes it to the location specified in the command.

For more information about the tmloadcf command, see Commands, System Processes, and MIB Reference in the WebLogic Enterprise online documentation.

Bean Passivation Behavior -- the EJB Cache

The WebLogic Enterprise EJB container has the ability to cache beans across method invocations as well as across transactions. This significantly reduces the frequency of beans being passivated, thereby providing the performance improvement. EJB caching is enabled by default for stateful beans.

For more information about EJB caching, see the section Controlling the Passivation of Beans -- the EJB Cache.

Step 9: Create the Client Application

When you create a client application that can invoke methods on a session EJB deployed in the WebLogic Enterprise environment, you need to include code that does the following:

• Creates an InitialContext object

• Uses the lookup method on the InitialContext object to obtain a reference to the the EJB's home interface

• Invokes the create method on the EJB's home interface to create an instance of the EJB

• Invokes the business methods on the EJB

• Destroys the instance of the bean

The sections that follow show fragments from the statefulSession EJB application to show the basic building blocks of an RMI client application that invokes an EJB in the WebLogic Enterprise environment. For complete details on creating an RMI client application, see Using RMI in a WebLogic Enterprise Environment in the WebLogic Enterprise online documentation.

Creating an InitialContext Object

Each WebLogic Enterprise EJB client application needs to create an InitialContext object to store information about the EJB application and the WebLogic Enterprise domain so that the client application can run. The InitialContext object is typically created with the following data, which are passed as parameters to the constructor of the InitialContext object:

• The address of the entry points to the WebLogic Enterprise environment

• The name of the factory to access the WebLogic Enterprise domain and global naming service

• Security information, such as the type of authentication, the security principal name, credentials, roles, and passwords

• The URL for remote class loading

The statefulSession client application implements a method named newInitialContext, in which the InitialContext object is created as a hash table. This hash table specifies env as com.beasys.com.jndi.WLEInitialContextFactory. After the context is created, the client application has access to bean homes in the WebLogic Enterprise domain using WebLogic Enterprise as the name service provider.

The newInitialContext method is shown in the following code fragment:

  static public Context newInitialContext() throws Exception {
    Hashtable env = new Hashtable();
    
    // specify an IIOP Listener/Handler for the desired WLE target domain
    env.put(Context.PROVIDER_URL, url);
    
    // Name of the factory to access WLE domain and global naming service.
    env.put(Context.INITIAL_CONTEXT_FACTORY, 
             "com.beasys.jndi.WLEInitialContextFactory");
    /* Security style: strong for SSL, simple for Tuxedo, and none
     * for no authentication at all. If no value is specified then, Tuxedo
     * style authentication is attempted.
     */
    env.put(Context.SECURITY_AUTHENTICATION, "simple");
    if (user != null) {
      printTrace("user: " + user);
      
      /* Specifies the identity of the principal for authenticating the caller
       * to the WLE domain
       */
      env.put(Context.SECURITY_PRINCIPAL, user);
      if (password == null) {
        password = "";
      }
      
      // A string password is used for Tuxedo style authentication.
      env.put(Context.SECURITY_CREDENTIALS, password);
    } else {
      
      // User id is null.
      env.put(Context.SECURITY_AUTHENTICATION, "none");
    } 
    return new InitialContext(env);
  }

The RMI client application in the statefulSession bean example invokes this newInitialContext method to create its InitialContext object, on which the application can then make the appropriate invocations, as shown in the following statement:

Context ctx = newInitialContext();

The newInitialContext method also creates the InitialContext object with specific information related to WebLogic Enterprise security. For information about the security data in the InitialContext object, and other client application requirements related to WebLogic Enterprise security, see Using Security in the WebLogic Enterprise online documentation.

Obtaining a Reference to the EJB's Home Interface

The following code fragment, from the statefulSession client application, shows the following:

1. Looking up the name of the TraderBean's home interface, TraderHome.

2. Using the PortableRemoteObject to narrow the reference to type Trader.

   Object objref = ctx.lookup("statefulSession.TraderHome");
   TraderHome  brokerage = (TraderHome) PortableRemoteObject.narrow(objref, 
                                       TraderHome.class);

Creating an Instance of the EJB

Before a client application can invoke business methods on a bean, the bean needs to be instantiated. EJBs are instantiated when the client application invokes the create method on the EJB's home interface.

The following code fragment, from the statefulSession bean example, shows invoking the create method on the TraderHome class, which causes the TraderBean and its remote interface to be instantiated:

Trader trader = brokerage.create("Terry");

Destroying the Instance of the Bean

After a client application is finished with the bean, it is good programming practice to include an invocation to the bean's remove method, as in the following example:

trader.remove();

Step 10: Start and Run the WebLogic Enterprise EJB Application

Use the tmboot command to start the server processes in your WebLogic Enterprise EJB application. The EJB application is usually booted from the machine designated as the MASTER in the RESOURCES section of the UBBCONFIG file.

For the tmboot command to find executables, the WebLogic Enterprise system processes must be located in $TUXDIR/bin. Server applications should be in APPDIR, as specified in the configuration file.

When booting server applications, the tmboot command uses the CLOPT, SEQUENCE, SRVGRP, SRVID, and MIN parameters from the configuration file. Server applications are booted in the order in which they appear in the configuration file.

For details about starting and running the statefulSession bean example, see Guide to the EJB Sample Applications.

For more information about using the tmboot command, see Commands, System Processes, and MIB Reference in the WebLogic Enterprise online documentation.

Step 11: Dynamically Manage the EJB Deployment (Hot Redeployment)

This step is optional. The WebLogic Enterprise system provides a means, sometimes referred to as hot redeployment, to dynamically make the following changes to the modules in a running EJB application:

• Add new modules

• Remove existing modules

• Update deployed modules

  Note: A module in an EJB application is a unit of deployment that is more than simply the classes in an EJB JAR file. For example, a module can consist of support libraries.

With WebLogic Enterprise hot redeployment:

• You can change modules used in an EJB application without shutting the application down or starting or restarting JavaServers.

• Clients connected to other EJB modules in the WebLogic Enterprise domain that are not the target of a hot redeployment have no interruption in service.

• Client applications of a module affected by hot redeployment will experience an interruption of service, but the hot redeployment does not require the shutting down or starting of additional server processes.

• Hot redeployment is disabled by default.

To use hot redeployment to add, change, or remove a module in a running EJB application:

• Make sure that the module's classes are not present in the default CLASSPATH.

• In the UBBCONFIG file, enable hot deployment for the JavaServer by specifying the -Dwle.dynamic option in the CLOPT attribute.

• While the EJB application is running, use the following tmadmin commands to, respectively, add, remove, or change modules:

  • addmodule

  • removemodule

  • changemodule

    Notes: The TMIB T_MODULE class has been modified to represent modules that can and cannot be modified.

    If you attempt to redeploy a module in a JavaServer for which hot redeployment has not been enabled, no change to the module will occur.

For more information about using hot redeployment, see the following:

• For information about specifying the JavaServer in the UBBCONFIG file, see the topic "Starting JavaServer" in Creating a Configuration File.

• For information about specifying the -Dwle.dynamic option in the CLOPT attribute, see the section "Using Server Command-line Options" in Creating a Configuration File.

• For more information about the addmodule, removemodule, and changemodule commands, see the tmadmin command in Section 1 of the BEA Tuxedo Reference Manual.

 

---

WebLogic Enterprise EJB Sample Applications

WebLogic Enterprise provides the sample applications described in the following list. For more information about these samples, how they work, and how you can build and run them, see Guide to the EJB Sample Applications.

• samples.j2ee.ejb.basic.statelessSession

  Shows a stateless session bean in which the client application must maintain any state across invocations to that bean.

• samples.j2ee.ejb.basic.statefulSession

  Shows a session bean that uses stateful persistence.

• samples.j2ee.ejb.sequence.jdbc

  Shows an entity bean that automatically generates its primary key by calling directly to a database using a connection pool and JDBC.

• samples.j2ee.ejb.sequence.oracle

  Shows an entity bean that automatically generates its primary key by calling directly to a database using a connection pool and an Oracle database.

• samples.j2ee.ejb.subclass.parent

  Shows a stateless session bean called ParentBean that is the parent class for another bean, ChildBean.

• samples.j2ee.ejb.subclass.child

  Shows a stateless session bean called ChildBean that inherits methods from a ParentBean, and also shows one bean calling another bean.