![]() |
Stateful Simple EJB Cart Sample Application |
Stateful Simple EJB Cart Sample Application
This document describes how to utilize the Stateful Simple EJB Cart sample application in conjunction with Sun Java System Application Server Enterprise Edition 7 2004 Q2.This document also describes how to test the high availability feature in appserver for Stateful session bean with web client and rich client.
This sample application document contains the following sections:
Overview
- Overview
- Compiling and Assembling the Sample Application
- Deploying the Sample Application
- Running the Sample Application
- Troubleshooting
The cart sample demonstrates the use of stateful session bean. Typical use of a stateful session bean is a shopping cart. The session bean (CartEJB) represents a shopping cart in an online bookstore. The bean's client may add a book to the cart, remove a book, or retrieve the cart's contents. The sample is comprised of an EJB and a servlet. The appserver makes the Cart EJB highly available. If one server goes down the conversational state (i.e the cart contents) is migrated transparently to another available server instance in the cluster.
Compiling and Assembling the Sample Application
To recompile, assemble, and deploy the application, see the Sample Application Build Facility document for details on using a build facility to quickly perform these tasks.To rebuild the entire application from scratch, follow these steps:
Deploying the Sample Application
- Compile and Assemble Web Application. For example:
- Execute asant under <install_dir>/samples/ee-samples/sfsbfailover/simple/src/
- The default target core will be executed to rebuild the .jar and .ear files.
- Deploy the application.
- Once you have re-created the sample application from scratch proceed to Deploying the Sample Application.
- Clean the web application project area. For example:
- Execute asant clean
- This will remove the sample application assemble and build directories.
A pre-built sfsbFailover.ear file is supplied with the application server installation. The pre-built sfsbFailover.ear file is an Enterprise Archive (.ear) file that contains, the EJB .jar file, web application .war file and the client jar file of the application. Within each file resides the XML deployment descriptor files, application class files, and other content required by the application. You can use the pre-built .ear file to deploy the application. If you want to experience compiling and assembling the application from scratch, follow the instructions in Compiling and Assembling the Sample Application.To deploy the application, the administrative server needs to be running. To start the administrative server if it is not already started, do one of the following, depending on your oeprating system.
Select one of the following approaches to deploying the application:
- UNIX
- Execute <install_dir>/domains/domain1/admin-server/bin/startserv
- Windows
- Start->Programs->Sun Java(TM) Systeem Application Server->Start Application Server
Command Line-based Deployment
- Command Line-based Deployment describes how to manually register the application in Sun Java (tm) System Application Server using a Command Line Interface (CLI). This is the fastest means of deploying the sample application.
- GUI-based Deployment describes how to use the Sun Java(TM) System Application Server Deployment Tool to import and deploy the sample application.
Command Line Interface is the fastest means of deploying the application. If you want to deploy through a GUI tool, follow the instructions for GUI Based Deployment. CLI deployment of the application can be done by either the Using the asant script or by Using the asadmin command.
Using the asadmin command
- Go to the src directory of the sample. For example:
- cd <install_dir>/samples/ee-samples/sfsbfailover/simple/src
- Run asant using deploy task. For example:
- %asant deploy
- It is an interactive command that may prompt you for the admin-server host, admin-server port, admin user name, admin password, and appserv instance. This also registers the resources to the Sun Java(TM) System Application Server.
The deployment process involves the following operations:
- Go to the root of the sample directory. For example:
- cd <install_dir>/samples/ee-samples/sfsbfailover/simple
- Execute asadmin to deploy application to the local application server instance. For example:
- asadmin deploy -u <user-name> -w <password> -H <hostname> -p <admin server port> --instance <instance name> sfsbFailover.ear
If you would like to verify the registration of the application, you may proceed to Verifying Deployment. Otherwise, proceed to Running the Sample Application.
- Authenticates against the local application server's administrative server
- The EAR file is transferred to the administrative server
- The administrative server begins the registration process:
- Parses the EAR file and embedded JAR and WAR files
- Explodes the bits into repository
- Registers the J2EE application "sfsbFailover" by updating server.xml
To deploy the EAR file, follow these steps:
Verifying Deployment
- Log in to the web-based administration tool from the browser.
- Navigate as follows:
- Application Server Instances --> <server instance> --> Applications --> Enterprise Applications
- Click Deploy.
- Click Browse to locate the sfsbFailover.ear file.
- The ear file is located under <install_dir>/samples/ee-samples/sfsbfailover/simple.
- Click OK.
- Enter sfsbFailover in the Application Name field.
- Click OK.
- Click the sfsbFailover link to verify that the application is deployed.
As an optional step, you can use the Sun Java(TM) System Application Server Administration Tool to verify that the application has been registered. Otherwise, proceed directly to Running the Sample Application.
To verify the registration of the application, follow these steps:
Generating Javadocs
- Execute the command asadmin list-components to look at applications deployed with a server instance. For example:
- asadmin list-components -u <username> -w <password> -H <host> -p <admin-port> <server instance name>
- Alternately, you may navigate the Admin tool GUI to the following:
- App Server Instances>server1>Applications.
- On the left frame, Click on Enterprise Apps to display list of applications deployed on server.
To better understand the sample application source code, you can refer to the related javadocs.
To generate javadocs run one of the following commands:
After javadocs are generated, you can access them at <install_dir>/samples/ee-samples/sfsbfailover/simple/javadocs/index.html
Running the Sample Application
1. Web-based client.
To see the failover of the SFSB happening, configure your loadbalancer in the web server for the cluster comprising multiple appserver instances.
This is needed to make request independent of which server instance is serviceing the request.
From your browser, access the application page from http://host:port/sfsbFailover, where the host and port are of webserver.
You now enter the sfsbFailover bookstore . Enter the name of a book and add the book to your cart by clicking on 'Add Book To Cart'.
Similarly, you can remove a book from your cart. The updated contents of the cart are shown at the bottom of the page.
To test the failover of the SFSB happening, add few books to the cart. The contents of the cart are shown. Then stop the appserver instance which served the previous requests.Add another book to your cart. The request is now served by another available server instance in the cluster. The conversational state of the session bean is transparently migrated to this server.You can see book is added to the the original contents of the cart.You can also test the failover behaviour by removing the book from the cart.
2. RMI/IIOP-based client with ACC.
The Java client will be run on the same machine where the Application Server is running.
- Get client file, i.e.
<as_install_dir>/domains/domain1/server1/applications/j2ee-apps/sfsbFailover_1/sfsbFailoverClient.jar
- Go to the directory,
<as_install_dir>/bin
- Run client application, e.g.
appclient -client <path>/sfsbFailoverClient.jar
- If the Java client is running on a different machine than where the Application Server is running, then follow these steps to package the APplication client container.
- Package Application Client Container.
Application Client Container (ACC) is a set of java classes, libraries and other files used to execute a first tier application client program in it own JVM. It communicates with the Application Server using RMI-IIOP.On the first machine where application server is running, package ACC. Go to the directory of
<as_install_dir>/bin
execute the script as following,
package-appclient
It creates the package as
<as_install_dir>/lib/appclient/appclient.jar
- Transfer the container and client files.
Copy appclient.jar and sfsbFailoverClient.jar from the first machine to the second machine.Note that the appclient.jar is intended to be used on a remote machine with same type of operating system. For example, appclient.jar created on a Solaris system will not function on a Win32 system.
- Install the container.
On the second machine, unpack ACC, i.e. applicient.jar, under a directory of your choice, e.g.
<acc_install_dir>
This installs ACC in
<acc_install_dir>/appclient
- Configure the container.
On the second machine:
- Modify environment in the file of
<acc_install_dir>/appclient/config/asenv.conf
For example,
AS_INSTALL=<acc_install_dir>/appclient
AS_WEBSERVICES_LIB=<acc_install_dir>/appclient/lib
AS_IMQ_LIB=<acc_install_dir>/appclient/imq/lib
AS_ACC_CONFIG=<acc_install_dir>/appclient/config/sun-acc.xml
AS_JAVA=<Location of JDK Installed>
- Modify client script in the file of
<acc_install_dir>/appclient/bin/appclient
Change the path to the environment file, asenv.conf from
. ${IAS_CONFIG}/asenv.conf
to
. <acc_install_dir>/appclient/config/asenv.conf
- Modify XML configuration file of
<acc_install_dir>/appclient/config/sun-acc.xml
for ORB host and port. For example,
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE client-container SYSTEM "file:<acc_install_dir>/appclient/lib/dtds/sun-application-client-container_1_0.dtd ">
<client-container>
<target-server name="acchost" address="ashost" port="3700"/>
<client-credential user-name="j2ee" password="j2ee"/>
<log-service file="" level="WARNING"/><property name="com.sun.appserv.iiop.loadbalancingpolicy" value="ic-based" />
<property name="com.sun.appserv.iiop.endpoints" value="host1:port1,host2:port2"/>
</client-container>- In this example, Application Server is running on the machine with hostname ashost and with default ORB-port 3700, and Application Client Container is on the machine with hostname acchost.
- Run client application
On the second machine, e.g. (acchost),
- Go to the directory,
<acc_install_dir>/appclient/bin
- Run client application, e.g.
appclient -client <path>/sfsbFailoverClient.jar
- You will see the host and port of the first machine from screen,
......
INFO: ACC014: ORB host name: [ashost]
......
INFO: ACC013: ORB port number: [3700]
......
- You will see interactive console, which helps you to also test the high availability of the SFSB, InitialContext, Home reference and remote reference.After creating the InitialContext the interface stops for user to press enter. The user can stop the server where the InitialContext was created and enter, the refernce is failedover to another available server instance. The user can test the failover bahaviour for home reference, remote reference as well in the same way.
3. Local or remote RMI/IIOP-based client without ACC.
The java client is executed without using the interface of Application Client Container. It can be executed on the local machine (ashost) or a remote machine. The client application runs from the command line, i.e.where
java -classpath <CP> <ClientApp> Djava.library.path=$AS_INSALL/lib:/usr/lib/mps: -Dcom.sun.CORBA.connection.ORBSocketFactoryClass=com.sun.enterprise.iiop.EEIIOPSocketFactory -Dorg.omg.PortableInterceptor.ORBInitializerClass.com.sun.appserv.ee.iiop.EEORBInitializer -Dorg.omg.CORBA.ORBClass=com.sun.enterprise.iiop.POAEJBORB -Dorg.omg.CORBA.ORBSingletonClass=com.sun.corba.ee.internal.corba.ORBSingleton -Djavax.rmi.CORBA.UtilClass=com.sun.corba.ee.internal.POA.ShutdownUtilDelegate
java.naming.factory.initial=com.sun.appserv.naming.S1ASCtxFactory com.sun.appserv.iiop.loadbalancingpolicy=ic-based com.sun.appserv.iiop.endpoints=host:port,host:port
As a complete example for the command, it looks like the following for this sample,
- CP includes four jar files for CLASSPATH which are sfsbFailover.jar, appserv-rt.jar, appserv-ext.jar and appserver-rt-ee.jar.
The file of sfsbFailoverClient.jar is copied to the current directory from the deployment directory, e.g.
<as_install_dir>/domains/domain1/server1/applications/j2ee-apps/sfsbFailover_1
The other jars are copied to the current directory from AS installation, e.g.
<as_install_dir>/libIf you intend to run the client application on a remote machine, you need to transfer the sfsbFailoverClient.jar and other three appserver jar files to the client machine. Although the sfsbFailoverClient.jar file is used in this example to run application client with or without an ACC, it contains more files than absolutely necessary for the situation in which an ACC is not used. The minimal files required to run the example on a remote machine without an ACC are the appserv-ext.jar file and the following files as extracted from the sfsbFailoverClient.jar file:
samples/ejb/stateful/simple/ejb/Cart.class - Remote Interface
samples/ejb/stateful/simple/ejb/CartHome.class - Home Interface
samples/ejb/stateful/simple/ejb/_Cart_Stub.class - Remote Stub
samples/ejb/stateful/simple/ejb/_CartHome_Stub.class - Home Stub
samples/ejb/stateful/simple/client/CartClient.class - Client Application Main Class
The appserv-ext.jar file is required on the client machine because it contains the javax.ejb package that the client needs, and also contains the implementation and interface for J2EE APIs that the client may need.- ClientApp refers to the client program. In this example, it is,
samples.ejb.stateful.simple.client.CartClient
- URL refers to the comma seperated list of application server running as part of one cluster with hostname (e.g. ashost) and with an ORB-port (e.g. 3700 ). For example,
ashost:3700,ashost:3701,ashost:3702java -classpath sfsbFailoverClient.jar:appserv-ext.jar:appserv-rt.jar:appserv-rt-ee.jar samples.ejb.stateful.simple.client.CartClient -Djava.library.path=$AS_ISNTALLlib:/usr/lib/mps: -Dcom.sun.CORBA.connection.ORBSocketFactoryClass=com.sun.enterprise.iiop.EEIIOPSocketFactory -Dorg.omg.PortableInterceptor.ORBInitializerClass.com.sun.appserv.ee.iiop.EEORBInitializer -Dorg.omg.CORBA.ORBClass=com.sun.enterprise.iiop.POAEJBORB -Dorg.omg.CORBA.ORBSingletonClass=com.sun.corba.ee.internal.corba.ORBSingleton -Djavax.rmi.CORBA.UtilClass=com.sun.corba.ee.internal.POA.ShutdownUtilDelegate java.naming.factory.initial=com.sun.appserv.naming.S1ASCtxFactory com.sun.appserv.iiop.loadbalancingpolicy=ic-based com.sun.appserv.iiop.endpoints=localhost:3700,localhost:3701
You will see interactive console, which helps you to also test the high availability of the SFSB, InitialContext, Home reference and remote reference.After creating the InitialContext the interface stops for user to press enter. The user can stop the server where the InitialContext was created and enter, the refernce is failedover to another available server instance. The user can test the failover bahaviour for home reference, remote reference as well in the same way.
Troubleshooting
- Make certain that you run the asant undeploy command before redeploying this sample to make sure that all modules are undeployed properly.
- Although the war, ear, context-root and servlet alias names in this sample are all "sfsbFailover", it is not necessary that it be so. The application will work as expected if the names of each of these attributes is unique. Rebuild the application after changing the context-root (in application.xml), the servlet alias (in web.xml) and the war and ear names, redeploy and test the sample to confirm this.
- If you encounter problems when running the application, review the log files at <install-dir>/domains/domain1/<server-instance>/logs/server.log to learn what went wrong.
Copyright © 2002 Sun Microsystems, Inc. All rights reserved.