CMP Roster Sample Application for Enterprise Edition

  Samples Index

 
CMP Roster Sample Application for Enterprise Edition
 

This document describes how to utilize the CMP Roster sample application in conjunction with Sun Java (tm) System Application Server Enterprise Edition 8.1 2005Q1.

This sample application document contains the following sections:

Overview

The CMP Roster sample application is a set of CMP 2.0 EJBs with Local interfaces. This application demonstrates the use of container managed persistence and relationships between entity beans. The application allows user to insert data into database for the first time run or after data has been removed from the database, select different data displaying selections, invalidate current HttpSession, and remove data from database.  To demonstrate the high availability of servers in the cluster, the LocalEJBHome reference of the entity bean is stored in a HttpSession which allows it to failover to another server instance when a servicing server instance is unhealthy or unavailable.  Load Balancer and with at least two Application Server instances and two nodes of HADB  are required as minimum for configuration. The instruction for deployment and registering resources are for one application server instance, you should repeat the same for other instances.
 

Compiling and Assembling the Application



This section contains instructions to build and assemble the CMP Roster sample application from scratch using Command Line Interface (CLI). See the Sample Application Build Facility document for details on using asant facility to quickly perform these tasks.
  • To rebuild the sample from scratch, do the following:
    •  
    • Go to the ee-samples/failover/apps/roster directory

    •  
    • Execute the command <install_dir>/bin/asant

    • The default target core will be executed to compile java files and rebuild the .jar and .ear files.
  1. Clean the application project area using the asant clean command. For example:
  2. <install_dir>/bin/asant clean
Deploying the Sample Application

In this section, you will learn how to deploy the roster sample application.

            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 Administration Tool to 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 described in this section.

    Deploying the pre-built RosterApp.ear file is simple. Deploy either Using the asant script or by Using the asadmin command.
     

    Using the asant script

    Please start your database server, if not started.

    Execute the following steps:
     

    1. Go to the src directory of the sample
    2. cd <install_dir>/samples/ee-samples/failover/apps/roster

       
    3. Run asant using deploy task
    4. <install_dir>/bin/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
    2. cd <install_dir>/samples/ee-samples/failover/apps/roster

       
    3. Execute asadmin to deploy application to the application server cluster. For example:
    4. <install_dir>/bin/asadmin deploy -user <adminuser> -password <adminpassword> --host <DAShost> --port <DASport> --availabilityenabled=true --target <cluster-name> RosterApp.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:
    2. https://<DAShost>:<DASport>
    3. Enter the server administrator's username and password to access the admin server.
    4. On the left panel, navigate the tree by clicking on the following:
    5. Cluster -> <cluster-name>
    6. 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.
    7. Set "Upload" to "Yes" and click on `Browse' to select the .ear file (from disk) to be deployed (RosterApp.ear) Click `Next' on the top right hand corner of the frame. .
    8. Enter the application name as RosterApp. Enable "Availability" checkbox and add a target cluster to deploy the application on from the displayed list in the "Targets" section.
    9. Click OK


      If the deployment succeeds, you will see the `Enterprise Applications' panel and under `Deployed Enterprise Applications' you will see the RosterApp 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, do the following:

Execute the command asadmin list-components to display applications deployed with a server instance.

<install_dir>/bin/asadmin list-components --user <adminuser> --password <adminpassword> --host <DAShost> --port <DASport> <clustername>

For example:

<install_dir>/bin/asadmin list-components --user admin --password admin123 --host localhost --port 4849 cluster1

You should see output similar to what is displayed below:

RosterApp <j2ee-application>




Undeploying the Sample Application

    To undeploy the application, do the following:

  • Go to the ee-samples/failover/apps/roster directory

  •  
  • Execute the command asant undeploy

  •  


Registering Resources



JDBC resources required by this sample application are automatically configured when the application is deployed using asant deploy. If however, you are delpoying the sample application using the asadmin commands, you need to create the JDBC resources manually with the asadmin command. Please start your database server, if not started.  Now execute the following steps to register resources if you already have a connection to any database:

JDBC connection pool

asadmin create-jdbc-connection-pool --host <DAShost> --port <DASport> --user <adminuser> --password
<adminpassword> --datasourceclassname <datasource classname> --property
User=<database username>:Password=<database password>:<url-property>="<database jdbc url>"  --target <cluster-name>  rosterPool

In case of PointBase, please use DatabaseName as <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".

JDBC resource

- JNDI name should be "jdbc/roster" as the name is used in the deployment descriptor

asadmin create-jdbc-resource --host <DAShost> --port <DASport> --user <adminuser> --password <adminpassword>
--connectionpoolid  rosterPool jdbc/roster

 

Persistence Manager Factory resource

- JNDI name should be "jdo/roster" as the name is used in the deployment descriptor

asadmin create-persistence-resource --host <admin host> --port <admin port> --user <user> --password <password>  --target <cluster-name> --jdbcjndiname  jdbc/roster   --factoryclass com.sun.jdo.spi.persistence.support.sqlstore.impl.PersistenceManagerFactoryImpl jdo/roster
 

For more information on using PointBase, please refer to the Using PointBase with the Samples document.


 
Running the Sample Application



In order to run the sample application, you must first do the following:
You are now ready to run the sample application by doing the following: On your browser go to the url : http://<Whost>:<Wport>/RosterClient

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. The following images are from running the sample.
 


Figure 1 - RosterApp
 
 


Figure 2  -  RosterApp: select different display option
 


Figure 3  -  RosterApp: List of League display option
 


Figure 4  -  RosterApp: Players of Sport display option

Now, stop the instance that served the request. (See Running the sample Applications section here to see how to do this). After the instance is shut down completely, go to the selection page and list any of the display options. The contents will be displayed without you needing to populate the database once again.


 


Figure 5  -  RosterApp: Invalidate the current HttpSession



Generating javadocs

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

To generate javadocs, run the following command from .../ee-samples/failover/apps/roster:

        asant javadocs

After javadocs are generated, you may access them at samples/ee-samples/failover/apps/roster/javadocs/index.html.
 
 

Troubleshooting


  • If you encounter problems when running the application, review the log files at <install-dir>/domains/domain1/logs/server.log and <install_dir>/nodeagents/<agent-name>/<instance-name>/logs/server.log (also check which instance served the request) to learn what exactly went wrong.

  •  
  • Check to see if the database is running.

  •  
  • To reset your database, run the command asant sql if using PointBase

  •  
  • To redeploy the sample, please undeploy the sample first. Use the commands asant undeploy, asant clean and then asant all.

  •  
 

Copyright © 2004 Sun Microsystems, Inc. All rights reserved.
Last Updated June 13, 2004