Stateful Session Bean Sample Application

 

This topic includes the following sections:

• How the Stateful Session Bean Sample Works

• Building and Running the Stateful Session Bean Sample

• Stopping the Sample Application

• Stateful Session Bean Javadoc

 

---

How the Stateful Session Bean Sample Works

This 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 client, and the other is a multithreaded client. The stateful session bean sample application implements the following classes:

Class	Description
Client	This 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 demonstrates calling a stateful session bean using multiple colocated clients: each thread is a trader, and performs repeated buying and selling of shares 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.
TradeResult	This bean contains the results of a buy/sell transaction.

 

---

Building and Running the Stateful Session Bean Sample

To build and run the stateful session bean sample application, complete the following steps:

1. Verify the environment variables.

2. Copy the files for the stateful session bean sample application into a work directory.

3. Change the protection attribute on the files for the stateful session bean sample application.

4. Execute the runme command.

The following sections describe these steps, and also explain the following:

• How to run the stateful session bean sample application

• Processes and files created by the stateful session bean sample application

Verifying the Settings of the Environment Variables

Before building and running the sample application, you need to ensure that certain environment variables are set on your system. In most cases, these environment variables are set as part of the installation procedure. However, you need to check the environment variables to ensure they reflect correct information.

Table 3-1 lists the environment variables required to run the stateful session bean sample application.

Table 3-1 Environment Variables

Environment Variable	Description
TUXDIR	The directory path where you installed the WebLogic Enterprise software. For example: Windows NT TUXDIR=c:\wledir UNIX TUXDIR=/usr/local/wledir
JAVA_HOME	The directory path where you installed the JDK software. For example: Windows NT JAVA_HOME =c:\JDK1.2 UNIX JAVA_HOME =/usr/local/JDK1.2

You may optionally set the following system environment variables to change their default value prior to running the stateful session bean sample application runme command. See the Administration Guide for more information about selecting appropriate values for these environment variables.

Table 3-2 lists the optional environment variables required to run the stateful session bean sample application.

Table 3-2 Optional Environment Variables

Environment Variable	Description
HOST	The host name portion of the TCP/IP network address used by the ISL process to accept connections from Java clients. The default value is the name of the local machine.
PORT	The TCP port number at which the ISL process listens for incoming requests; it must be a number between 0 and 65535. The default value is 2468.
IPCKEY	The address of shared memory; it must be a number greater than 32769 unique to this application on this system. The default value is 55432.

Verifying the Environment Variables

To verify that the information for the environment variables defined during installation is correct, complete the following steps:

Windows NT

1. From the Start menu, select Settings.

2. From the Settings menu, select the Control Panel.

   The Control Panel appears.

3. Click the System icon.

   The System Properties window appears.

4. Click the Environment tab.

   The Environment page appears.

5. Check the settings for TUXDIR and JAVA_HOME.

UNIX

1. Enter the ksh command to use the Korn shell.

2. Enter the printenv command to display the values of TUXDIR and JAVA_HOME, as in the following example:

   ksh prompt>printenv TUXDIR
   ksh prompt>printenv JAVA_HOME

Changing the Environment Variables

To change the environment variable settings, complete the following steps:

Windows NT

1. From the Start menu, select Settings.

2. From the Settings menu, select the Control Panel.

   The Control Panel appears.

3. Click the System icon.

   The System Properties window appears.

4. Click the Environment tab.

   The Environment page appears.

5. On the Environment page in the System Properties window, click the environment variable you want to change or enter the name of the environment variable in the Variable field.

6. Enter the correct information for the environment variable in the Value field.

7. Click OK to save the changes.

UNIX

1. Enter the ksh command to use the Korn shell.

2. Enter the export command to set the correct values for the TUXDIR and JAVA_HOME environment variables, as in the following example:

   ksh prompt>export TUXDIR=directorypath
   ksh prompt>export JAVA_HOME=directorypath

Copying the Files for the Stateful Session Bean Sample Application into a Work Directory

You need to copy the files for the stateful session bean sample application into a work directory on your local machine. The following steps describe how to copy all the example files into a work directory.

1. If you are using a UNIX system, enter the ksh command to use the Korn shell:

   prompt>ksh
   ksh prompt>

2. Create a work directory on your machine under the directory described in step 2 in the section Before you Build and Run the EJB Sample Applications.

3. Copy the contents of the following directory into the work directory:

   Windows NT

   %TUXDIR%\samples\j2ee\ejb\basic\statefulSession

   UNIX

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

The files copied into the work directory are in two categories:

• Files specific to the stateful session bean example

• Utility files used for building and running the example application

Sample Application Files

Table 3-3 lists and describes all the files for this sample application:

Table 3-3 Sample Application Files

File	Description
ejb-jar.xml	The XML deployment descriptor file used to help add the bean to the EJB container.
weblogic-ejb-extensions.xml	A file containing the WebLogic Enterprise extensions to the deployment descriptor DTD.
Client.Java	The Java source code for the client application.
TraderBean.java	The Java source code for the stateful session bean. This class contains the business logic method implementations and methods required by the EJB specification 1.1.
Trader.java	The Java source code for the Remote interface of the TraderBean class.
TraderHome.java	The Java source code for the Home interface of the TraderBean class.
TradeResult.java	Application-specific utility class used to carry a trade execution result between the EJB and the client.
ProcessingErrorException.java	Application-specific utility class used to carry a trade execution result between the EJB and the client.

Utility Files

Table 3-4 lists and describes the utility files for this sample application. These files are generated based on the WebLogic Enterprise installation environment. The following files are generated in the same directory as where the source files are found.

Table 3-4 Utility Files

File	Description
runme.cmd	The Windows NT batch file that contains commands to set the environment, boot the server, and execute the client for this sample.
runme.ksh	The UNIX Korn shell script that contains commands to boot the server and execute the client for this sample.
run_client.cmd	The batch file to run the client application on Windows NT systems.
run_client.ksh	The script file to run the client on UNIX systems.
run_mclient.ksh	The script file to run the multithreaded client application on UNIX systems.
run_mclient.cmd	The batch file to run the multithreaded client application on Windows NT systems.
setenv.cmd	The batch file to set the necessary environment variables on Windows NT systems.
setenv.ksh	The script file to set the necessary environment variables on UNIX systems.
ubbconfig	The WebLogic Enterprise server configuration file to be used on UNIX systems.
ubbconfig.nt	The WebLogic Enterprise server configuration file to be used on Windows NT systems.
index.html	File containing these instructions.

Changing the Protection Attribute on the Files for the Stateful Session Bean Sample Application

During the installation of the WebLogic Enterprise software, the sample application files are marked read-only. Before you can edit or build the files in the stateful session bean sample application, you need to change the protection attribute of the files you copied into your work directory, as follows:

Windows NT

prompt>attrib /S -r drive:\workdirectory\*.*

UNIX

prompt>ksh

ksh prompt>chmod +w /workdirectory/*.*

On the UNIX operating system platform, you also need to change the permission of runme.ksh and clean.ksh to give execute permission to those files, as follows:

ksh prompt>chmod +x *.ksh

Executing the runme Command

The runme command automates the following steps:

1. Loads the UBBCONFIG file.

2. Compiles the code for the stateful session bean sample application.

3. Starts the server application using the tmboot command.

4. Starts the client application.

5. Stops the server application using the tmshutdown command.

To build and run the stateless session bean sample application, make sure you have copied the scripts described in Before you Build and Run the EJB Sample Applications, and enter the runme command, as follows:

Windows NT

prompt>cd workdirectory

prompt>runme basic statefulSession

UNIX

ksh prompt>cd workdirectory

ksh prompt>./runme.ksh basic statefulSession

A number of messages are displayed, along with whether or not the build procedure was successful. Note that the sample is not only built, but also the servers are booted and the client is run once.

Running the Sample Manually

After you have executed the runme command, you can run the sample manually if you like. To run the samples manually, complete the following steps:

1. Change to the sample's work directory, if necessary.

2. Make sure that your environment is set correctly by entering the following command:

   Windows NT

   prompt>setenv

   UNIX

   prompt>. ./setenv.ksh

3. Boot the server and run the client by entering the following commands:

   Windows NT

   prompt>tmboot -y
   prompt>run_client.cmd

   UNIX

   prompt>tmboot -y
   prompt>./run_client.ksh

Processes and Files Generated by the Sample Application

When the you enter the tmboot command to start one of the EJB sample applications, the following server processes are started:

• TMSYSEVT

  The BEA Tuxedo system Event Broker.

• TMFFNAME

  The following TMFFNAME processes are started:

  • The TMFFNAME server process with the -N option and the -M option is the MASTER NameManager service. The -N option starts the NameManager service; the -M option starts this name manager as a MASTER. This service maintains a mapping of application-supplied names to object references.

  • The TMFFNAME server process with the -N option is a SLAVE NameManager service.

  • The TMFFNAME server with the -F option contains the FactoryFinder object.

• JavaServer

  The JavaServer takes one or more EJB JAR files that were created for the application.

• ISL

  The IIOP Listener/Handler.

 

---

Stopping the Sample Application

You can stop the stateful session bean sample application by entering the following command:

prompt>tmshutdown -y

 

---

Stateful Session Bean Javadoc

The Javadoc for the stateleful session bean example is in the following location:

Windows NT

%TUXDIR%/samples/j2ee/ejb/basic/statefulSession/index.html

UNIX

$TUXDIR\samples\j2ee\ejb\basic\statefulSession\index.html

If you are viewing this document in a browser, you can click the following link to display this Javadoc:

Package samples.j2ee.ejb.basic.statefulSession