Sun java System logo     
CMP Simple Sample Application



CMP Simple Application


This document describes how to utilize the CMP Simple sample application in conjunction with the Sun Java (tm) System Application Server 7.

This sample application document contains the following sections:



Overview

This sample is based on the Product EJB sample included in Sun's J2EE Developer's Guide, version 1.2.1 . This will illustrate the functionality for CMP 1.1. The following instructions describe how to assemble and deploy the same EJB to Sun Java (tm) System Application Server and how to access the EJB from both a simple Java client application using RMI/IIOP as well as from a Servlet client using HTTP. Although the client application and EJB offer minimal functionality, this sample should provide you with a basic understanding of RMI/IIOP and CMP support in Sun Java (tm) System Application Server.

The CMP 1.1 EJB in this sample has three CMP fields:


CMP field

Java type

productId

java.lang.String

description

java.lang.String

price

double

And it has two custom finder methods:


Custom Finder Method

description

findByDescription

find all the product matching the given description

findInRange

find all the product lie in given price range


Compiling and Assembling the 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 the J2EE application.

    Execute the asant command under <install_dir>/samples/ejb/cmp/simple/src

    The default target core is 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 application.

  3. Clean the application project area.

    Execute the asant clean command to clean the application area.

  4. Undeploy the application.

    Execute the asant undeploy command to undeploy the application.



Deploying the Application

A pre-built cmp-simple.ear file is supplied with the application server installation. The pre-built cmp-simple.ear file is an Enterprise Archive (.ear) file that contains, the EJB .jar file, the web applicatation .war file, and the Application 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 Application.

To deploy the application, the administrative server needs to be running. To start the administrative server if it is not already started:

UNIX

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

Windows

    Start->Programs->Sun Java (tm) System Application Server 7->Start Application Server

Select one of the following approaches to deploy the application:

  • Command Line-based Deployment describes how to manually register the application using a Command Line Interface (CLI). This is the fastest means of deploying the application.

  • Web-based Deployment describes how to use the web based administration tool to 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 using either the asant script or using the asadmin command.

Deployment process includes deploying the application EAR, configuring datasbase and registering required resources to Sun Java (tm) System application server. Installation comes with already configured pointbase database. If you choose to use prepopulated pointbase database, you do not need to configure database. Otherwise please follow Configuring oracle database instructions.


Deploy the Application Using asant

Please start your database server, if not started.

If you choose to use the PointBase database, execute the following steps:

  • cd <install_dir>/samples/ejb/cmp/simple/src

  • Execute the asant deploy command. 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.

If you choose to use oracle database please execute the following steps.

  • cd <install_dir> /samples/ejb/cmp/simple/src

  • Execute the asant deploy-ora. It is interactive command which may ask for admin-server host, admin-server port, admin user name, admin password and appserv instance.

  • Note that, it assumes the db host as localhost, db port as 1521 and sid as sun-appserv-samples. If you want to use different parameters, please use asant deploy-ora -Ddb.host=<db host> -Ddb.port=<db port> -Ddb.sid=<db sid>

This will also register the resources to Sun Java (tm) System application server. Now you are ready to run the application.


Deploy the Application File Using the asadmin Command

  • cd <install_dir>/samples/ejb/cmp/simple

  • Execute the command asadmin deploy --user <user-name> --password <password> --host <hostname> --port <admin server port> --instance <instance name> cmp-simple.ear

Now you need to register the resources to the Sun Java (tm) System 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 and embedded .jar and .war files.

    • Explodes the bits into the repository.

    • Registers the J2EE application cmp-simple by updating the server.xml file.

If you want to verify the registration of the application, proceed to Verifying Registration.


Web-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 Applications

  3. Click Deploy.

  4. Click Browse to locate the cmp-simple.ear file.

    The ear file is located under <install_dir>/samples/ejb/cmp/simple.

  5. Click OK.

  6. Enter cmp-simple in the Application Name field.

  7. Click OK.

  8. Click the cmp-simple link to verify that the application is deployed.

  9. Now you need to register the resources to the Sun Java (tm) System application server. Proceed to Registering Resources.


Configuring Oracle Database


The product application requires the following database setup prior to running:

  1. Ensure Database Requirements are Met

    See the Sun Java (tm) System Application Server Release Notes for database version requirements. The Product sample includes schema script for Oracle.

  2. Create an RDBMS User

    • cd <install_dir>/samples/ejb/cmp/simple/src/sql

    • sqlplus to oracle as system user

    • SQL> @createUser

    • exit sqlplus

  3. Create and Populate the Product RDBMS Tables

    • cd <install_dir>/samples/ejb/cmp/simple/src/sql

    • sqlplus to oracle as cmp user

    • SQL> @product.sql;

    • exit sqlplus

  4. Register JDBC Driver

    Make sure that JDBC driver zip/jar files are in classpath-suffix attribute of java-config element in server.xml of the instance running this product application. You may like to edit this file if necessary. Please make sure that the server.xml is also copied to backup directory. And then restart the server instance.

Registering Resources


This section describes how to create resources required for running cmp-simple 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:

  • Please start your database server, if not started.
  • 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=cmp:Password=cmp:<url-property>="<database jdbc url>" cmp-simple-pool

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

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

  • Persistence Manager Factory Resource

    asadmin create-persistence-resource --host <admin host> --port <admin port> --user <user> --password <password> --instance <server instance name> --jdbcjndiname jdbc/cmp-simple --factoryclass com.sun.jdo.spi.persistence.support.sqlstore.impl.PersistenceManagerFactoryImpl jdo/cmp-simple

  • Reconfiguring Server Instance

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



Running the Sample Application

The application be executed, using web client and using appclient container.

    Note

    • Before you run the application, you need to start up your PointBase Server. Refer here for how to start up your PointBase Server. If you try to run the application without starting PointBase Server, you will need to start PointBase Server and restart application server, before running the application.



Execute Servlet Client

To run the web application, go to the following URL:

http://<web server hostname>:<port>/product/ProductServlet

If your deployment process was successful, the servlet sends the following information to your browser:

Ceramic Dog: 10.0
Ceramic Dog: 14.0
Chrome Fish: 22.0
999: Ivory Cat 19.0
789: Ivory Cat 33.0
123: 14.0
456: 13.0
999: 19.0

Compare the resulting web page with the ProductServlet.java source code.

After servlet application completes, the PRODUCT table should contain the following rows:

SQL> select * from product;
DESCRIPTION PRICE PRODUCTID
----------- ----- ------------------------------

Ceramic Dog 14 123
Wooden Duck 13 456
Ivory Cat 19 999
Ivory Cat 33 789
Chrome Fish 22 876

Execute Rich Client

To run the rich client, please do following:

  1. execute appclient as follows:

    appclient -client <install_dir>/domains/<domain-instance>/<server-instance>/applications/j2ee-apps/cmp-simple_1/cmp-simpleClient.jar.
    Please note that, you may have to use directory different than cmp-simple_1, in case of multiple subsequent deployments.

The application should print the following messages:

Ceramic Dog: 10.0
Ceramic Dog: 14.0
Chrome Fish: 22.0
999: Ivory Cat 19.0
789: Ivory Cat 33.0
123: 14.0
456: 13.0
999: 19.0

Compare the resulting web page with the ProductClient.java source code.

After servlet application completes, the PRODUCT table should contain the following rows:

SQL> select * from product;
DESCRIPTION PRICE PRODUCTID
----------- ----- ------------------------------

Ceramic Dog 14 123
Wooden Duck 13 456
Ivory Cat 19 999
Ivory Cat 33 789
Chrome Fish 22 876


Note Before rerunning the application client again, ensure that you clean the database table by removing all rows from the table.The application will not work correctly unless you clean up.

You can do the following to clean the database.

  • cd <install_dir>/samples/ejb/cmp/simple/src/

  • asant sql




Verifying Registration


 
As an optional step, you can use the Sun Java (tm) System Application Server Administration Tool to verify that the application has been registered. If you do not want to verify that the application has been registered, proceed directly to Running the Sample Application.

To verify the registration of the application, execute the asadmin command to look at applications deployed with a server instance:

asadmin list-components --host <admin host> --port <admin port> --user <user> --password <password> --type application <server instance name>

You can also execute the asadmin command to look at application status:

asadmin show-component-status --host <admin host> --port <admin port> --user <user> --password <password> --instance <instance name> --type application <application name>


Generating Javadocs


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

To generate javadocs run the following command:

asant javadocs

or

asant all

After javadocs are generated, you can access them at

<install_dir>/samples/ejb/cmp/simple/javadocs/index.html



Troubleshooting



Make certain that you run the asant undeploy command before redeploying this sample to make sure that all modules are undeployed and the resources are disabled.

If you don't receive data in the browser (see a blank page) and the server log shows a "ORA-00001: unique constraint ..." message in the server.log, the condition is most likely one in which the sample was run at least partially before. Please clean your database before rerunning the application.

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.

Last Updated July 12, 2002