Sun ONE logo     
SimpleBank BMP Robean Sample Application



SimpleBank BMP Robean Sample Application


This document describes how to utilize the SimpleBank BMP Robean sample application in conjunction with Sun ONE Application Server version 7.

This sample application document contains the following sections:



Overview

This sample demonstrates the support for Read Only Beans (ROBs) in the Sun ONE application server. ROBs are entity beans that are never modified by an EJB client. Entity beans can be declared as ROBs by specifying the is-read-only-bean element in the sun-ejb-jar.xml. The data that an ROB represents may be updated by external means. ROBs are useful when the data they represent does not change or the change is not frequent. In such cases the cost of ejbStore can be avoided by the use of ROBs.

There are certain restrictions on ROBs. ROBs cannot start their own transactions, only container transactions are allowed. Container will not call ejbStore on ROBs. The ejbLoads will be called only when a bean is created or when a transactional method is called or at refresh intervals. ROBs Home interface need not have ejbCreate and ejbRemove methods.

The state of ROBs can be refreshed by different means:

  • Invoking a transactional method can refresh the state of ROB. In the sample all the methods of CustomerTransactionalEJB are defined as transactional. To refresh the state of CustomerTransactionalEJB, servlet invokes getBalance method of CustomerTransactionalEJB which is transactional.

  • The state of ROBs can be refreshed periodically by specifying the refresh-period-in-second in sun-ejb-jar.xml. If the period specified is negative, the state of ROB will never be refreshed. If the period specified is '0', the state of ROB will always be refreshed. If the period specified is greater than zero, the state of ROB will be refreshed periodically at that rate. In the sample CustomerRefreshEJB has refresh period of 60 seconds, so the state of CustomerRefreshEJB is refreshed every minute.

  • The state of ROBs can be refreshed programmatically. The beans which update data used by the ROBs, need to notify the ROBs to refresh their state. The state of the ROB can be updated with the help of ReadOnlyBeanNotifier. The state of CustomerProgRefreshEJB in the sample is updated programmatically as follows:

    ReadOnlyBeanNotifier notifier = ReadOnlyBeanHelper.getReadOnlyBeanNotifier("java:comp/env/ejb/customerProgRefresh");

    notifier.refresh(new PKString1(SSN));


In order to successfully deploy and run the SimpleBank BMP Robean sample application, Database resources (PointBase) needs to be setup with the Application Server.

If you want to run this sample on Oracle Database, please refer to (How to run sample applications with Oracle ) .



Compiling and Assembling the Application



This section contains instructions to build and assemble the SimpleBank BMP Robean sample application using a Command Line Interface (CLI). Please refer to the Sample Application Build Facility document for details on using a build facility.

To rebuild the entire application from scratch, follow these steps:

  1. Compile and Assemble the application.

    Execute the asant command under <install_dir>/samples/ejb/bmp/robean/src.

    The default target core is executed to rebuild the .ear file.

  2. Deploy the application.

    After you have re-created the sample application from scratch, proceed to Deploying the Sample Application.

  3. Clean the application project area.

    Execute the command asant clean to clean the application area.

  4. Undeploy the application.

    Execute the command asant undeploy to undeploy the application.

  5. Build Javadocs.

    Execute the command asant javadocs to create Javadocs.

    The Javadocs are created under <install_dir>/samples/ejb/bmp/robean/javadocs.



Deploying the Sample Application



In this section, you will learn how to deploy the SimpleBank BMP Robean sample application.

A pre-built bmp-robean.ear file is supplied with the application server installation. The pre-built bmp-robean.ear file is the Enterprise Archive (.ear) file of the application, which contain the ejb jar and war files. Within the ejb jar and war files reside 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 compile and assemble the application from scratch, follow the instructions under Compiling and Assembling the Application.

To deploy the application, the administrative server needs to be running.

To start the administrative server if it is not already started:

  • For UNIX:

    Execute <install_dir>/domains/domain1/admin-server/startserv

  • For Windows:

    Start->Programs->Sun ONE Application Server 7->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 ONE 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 ONE Application Server Deployment Tool to import and deploy the sample application.

Command Line-based Deployment

Since a complete EAR file is supplied, the fastest means of setting up the application is to use the command line utilities as described in this section. The deployment process includes deploying the application .ear file to the Sun ONE application server. CLI deployment of the application can be performed using either the asant script or the asadmin command.

To deploy the application using the asant command:

  1. >cd <install_dir>/samples/ejb/bmp/robean/src

  2. Execute the asant deploy command.

    It is an interactive command that might prompt you to provide the admin-server host, admin-server port, admin user name, admin password and server instance name.

You are now ready to exercise the application by Running the Sample Application.

To deploy the application file using the asadmin command:

  1. >cd <install_dir>/samples/ejb/bmp/robean

  2. Execute the following command:

    asadmin deploy -u <user-name> -w <password> -H <hostname> -p <admin server port> --instance <instance name> bmp-robean.ear.

  3. Now you need to register the resources to the Sun ONE application server. Proceed to Registering Resources.
The deployment process involves the following operations:

  • It 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

    • Explodes the bits into the repository

    • Registers the J2EE application bmp-robean by updating the server.xml file.

GUI-based Deployment

  1. Log in to the web-based administration tool from the browser.

  2. Navigate as follows:

    Application Server Instances --> <server instance> --> Applications --> Enterprise Apps

  3. Click Deploy.

  4. Click Browse to locate the bmp-robean.ear file.

    The file is located under <install_dir>/samples/ejb/bmp/robean.

  5. Click OK.

  6. Enter bmp-robean in the Application Name field.

  7. Click OK.

  8. Click the bmp-robean link to verify that the application is deployed.

  9. Now you need to register the resources to the Sun ONE application server. Proceed to Registering Resources.


Registering Resources

This section describes how to create resources required for running bmp-robean application. You do not need to register them separately when you deploy the application using the asant deploy command. However, the resources can be registered as follows:

  • JDBC Resource and its Associated Connection Pool

    asadmin create-jdbc-connection-pool --host <admin host> --port <admin port> --user <user> --password <password> --instance <server instance name> --datasourceclassname <datasource classname> --property User=bmp:Password=bmp:<url-property>="<database jdbc url>" bmp-robean-pool

    In case of PointBase, please use DatabaseName as <url-property>. In case of Oracle, please use <url-property>. You will need to escape ":" and "/", in <database jdbc url>. An example of <database jdbc url> is "jdbc\:pointbase\:server\:\/\/localhost\:9092\/sun-appserv-samples".

    asadmin create-jdbc-resource --host <admin host> --port <admin port> --user <user> --password <password> --instance <server instance name> --connectionpoolid bmp-robean-pool jdbc/bmp-robean

  • Reconfiguring Server Instance

    asadmin reconfig --host <admin host> --port <admin port> --user <user> --password <password> <server instance name>



Running the Sample Application

Perform the following steps to run the sample application:

  1. Go to http://<hostname>:<port>/SimpleBank/index.html

  2. Enter 123456789 as Customer Social Security Number.

    Click Enter.

  3. Enter amount in $ text box and click Update.

    Current Balance will be updated.

  4. Click on Get Trans. Balance.

    Transactional Refresh will be updated.

  5. Click on Get Prog. Balance.

    Programmatic Refresh will be updated.

  6. Wait for one minute.

    The page will be refreshed and Time-based Refresh will be updated.


Generating javadocs

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

To generate javadocs, run one of the following commands:

asant javadocs

or

asant all

After javadocs are generated, you may access them at <install_dir>/samples/ejb/bmp/robean/javadocs/index.html.



Troubleshooting



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 exactly went wrong.



Copyright © 2002 Sun Microsystems, Inc. All rights reserved.

Last Updated August 12, 2002