Stateful Simple EJB Cart Sample Application

Samples Index

> 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 8.1 2005Q1. 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
> - Compiling and Assembling the Sample Application
> - Deploying the Sample Application
> - Running the Sample Application
> - Troubleshooting
> Overview

> 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:

> 1. Compile and Assemble Web Application. For example:
> Execute asant under <install_dir>/samples/ee-samples/failover/apps/sfsbfailover/simple/
> The default target core will be executed to rebuild the .jar and .ear files.
> 2. Deploy the application.
> Once you have re-created the sample application from scratch proceed to Deploying the Sample Application.
> 3. Clean the web application project area. For example:
> Execute asant clean
> This will remove the sample application assemble and build directories.
> Deploying the Sample Application

> 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.

> - UNIX
> Execute <install_dir>/bin/asadmin start-domain domain1
> - Windows
> Start->Programs->Sun Java(TM) System Application Server->Start Application Server
> Select one of the following approaches to deploying the application:
> - 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-based Deployment

> 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 asant script

> 1. Go to the src directory of the sample. For example:
> cd <install_dir>/samples/ee-samples/failover/apps/sfsbfailover/simple
> 2. 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.
> Using the asadmin command
> 1. Go to the root of the sample directory. For example:
> cd <install_dir>/samples/ee-samples/failover/apps/sfsbfailover/simple
> 2. Execute asadmin to deploy application to the local application server instance. For example:
> asadmin deploy --user <adminuser> --password <adminpassword> --host <DAShost> -port <admin server port> --availabilityenabled=true --target <cluster-name> sfsbFailover.ear
> Where <adminuser> is the Domain Administration Server's admin username, <adminpassword> is the admin user's password, <DAShost> is the machine on which Domain Administration Server is installed and running, <DASport> is port at which Domain Administration Server is running and target> is the application cluster on which the sample application is to be deployed. If you would like to verify the registration of the application, you may proceed to Verifying Deployment. Otherwise, proceed to Running the Sample Application.

> GUI-based Deployment

> Since a pre-built Enterprise Archive (EAR) file for the sample application is included with the application server, you can use the Sun Java (tm) System Application Server Administration Tool to quickly deploy it to the Application Server.

> 1. From your web browser, access the Sun Java (tm) System Application Server by entering the URL. For example:
> https://<DAShost>:<DASport>
> 2. Enter the server administrator's username and password to access the admin server.
> 3. On the left panel, navigate the tree by clicking on the following:
> Cluster -> <cluster-name>
> 4. On the right panel, the Applications tab will be pre-selected. In the " --New--" drop down list select "Enterprise Application". The "Deployment Page" will load in the right frame.
> 5. Set "Upload" to "Yes" and click on `Browse' to select the .ear file (from disk) to be deployed (sfsbFailover.ear) Click `Next' on the top right hand corner of the frame. .
> 6. Enter the application name as sfsbFailover. Enable "Availability" checkbox and add a target cluster to deploy the application on from the displayed list in the "Targets" section.
> 7. Click OK

> If the deployment succeeds, you will see the `Enterprise Applications' panel and under `Deployed Enterprise Applications' you will see the sfsbFailover application as deployed.
> Verifying Deployment

> 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:

> 1. Execute the command asadmin list-components to look at applications deployed with a server instance. For example:
> asadmin list-components --user <adminuser> --password <adminpassword> --host <DAShost> --port DASport> --target <cluster-name>
> Generating Javadocs

> To better understand the sample application source code, you can refer to the related javadocs.

> To generate javadocs run one of the following commands:

> asant javadocs

> or

> asant all

> After javadocs are generated, you can access them at <install_dir>/samples/ee-samples/failover/apps/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://Whost:Wport/sfsbFailover`
> where `Whost` is the hostname of webserver having the loadbalancer plugin setup and configured and `Wport` is the port at which that webserver is running.
> 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.
> - Modify XML configuration file of <install_dir>/domains/domain1/config/sun-acc.xml for ORB host and port. For example,
>   .
>   .
>   .
>   </message-security-config>
>   <property name="com.sun.appserv.iiop.loadbalancingpolicy" value="ic-based" />
>   <property name="com.sun.appserv.iiop.endpoints" value="instance-ONE-host:instance-ONE-orb-port,instance-TWO-host:instance-TWO-orb-port"/>
>   </client-container>
>   The values for the orb ports can be see from <install_dir>/samples/ee-samples/cluster.properties file.
> - Get client file, i.e.
>   <as_install_dir>/domains/domain1/applications/j2ee-apps/sfsbFailover/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 XML configuration file
>     <acc_install_dir>/appclient/config/sun-acc.xml
>     for ORB host and port. For example,
>     .
>     .
>     .
>     </message-security-config>
>     <property name="com.sun.appserv.iiop.loadbalancingpolicy" value="ic-based" />
>     <property name="com.sun.appserv.iiop.endpoints" value="instance-ONE-host:instance-ONE-orb-port,instance-TWO-host:instance-TWO-orb-port"/>
>     </client-container>
>   - 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 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 (the request is served in the order configured in the sun-acc.xml as mentioned above using the property with name="com.sun.appserv.iiop.endpoints") and hit the Enter key, 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.
>   java -classpath <CP> <ClientApp> com.sun.CORBA.connection.ORBSocketFactoryClass=com.sun.enterprise.iiop.EEIIOPSocketFactory org.omg.PortableInterceptor.ORBInitializerClass=com.sun.appserv.ee.iiop.EEORBInitializer org.omg.CORBA.ORBClass=com.sun.enterprise.iiop.POAEJBORB org.omg.CORBA.ORBSingletonClass=com.sun.corba.ee.internal.corba.ORBSingleton javax.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=instance-ONE-host:instance-ONE-orb-port,instance-TWO-host:instance-TWO-orb-port
>   where
>   - CP includes three jar files for CLASSPATH which are sfsbFailover.jar, appserv-rt.jar and j2ee.jar.
>     The file of sfsbFailoverClient.jar is copied to the current directory from the deployment directory, e.g.
>     <as_install_dir>/domains/domain1/applications/j2ee-apps/sfsbFailover
>     The other jars are copied to the current directory from appserver installation, e.g.
>     <as_install_dir>/lib

>     If you intend to run the client application on a remote machine, you need to transfer the sfsbFailoverClient.jar and the two appserver jar files to the client machine.

>   - ClientApp refers to the client program. In this example, it is,
>     samples.sfsbfailover.client.CartClient
>   - instance-ONE-host:instance-ONE-orb-port,instance-TWO-host:instance-TWO-orb-port: The values for the hostnames and orb ports can be see from <install_dir>/samples/ee-samples/cluster.properties file.
>   As a complete example for the command, it looks like the following for this sample,
>   java -classpath sfsbFailoverClient.jar:appserv-rt.jar:j2ee.jar samples.sfsbfailover.client.CartClient com.sun.CORBA.connection.ORBSocketFactoryClass=com.sun.enterprise.iiop.EEIIOPSocketFactory org.omg.PortableInterceptor.ORBInitializerClass.com.sun.appserv.ee.iiop.EEORBInitializer org.omg.CORBA.ORBClass=com.sun.enterprise.iiop.POAEJBORB org.omg.CORBA.ORBSingletonClass=com.sun.corba.ee.internal.corba.ORBSingleton javax.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 (the request is served in the order configured in the sun-acc.xml as mentioned above using the property with name="com.sun.appserv.iiop.endpoints") and hit the Enter key, 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/logs/server.log to learn what went wrong.

> Copyright © 2004 Sun Microsystems, Inc. All rights reserved.

Last Updated October 25, 2004