6.7.5: Advanced application assembly and deployment tutorial -- CMP bean application

During this tutorial, you will assemble and deploy a CMP bean application. This simple J2EE application consists of a single CMP entity bean and a Java application client. The client creates an EJB, invokes a remote method, then destroys it. We will start with an EJB 1.0 jar file.

Prerequisites

This tutorial assumes knowledge of the Application assembly tutorial and Application deployment tutorial, which focused on a Session bean application, but are also applicable for BMP bean applications. Indeed, many steps of this tutorial are abbreviated, with links to the steps in the assembly and deployment tutorials in case you need to refresh your memory.

This tutorial puts more attention on the new steps for CMP bean support, namely, creating database tables and configuring data sources in the application server runtime.

You will need a working, supported DB2 or Oracle database to verify your results using the tutorial steps as they are written. Of course, you can always use this tutorial to practice the steps, knowing that your data access is not set up yet.

Overview of steps (60 minutes)

  1. Obtain the example code
  2. Start the Application Assembly Tool
  3. Assemble an EJB module, converting from EJB 1.0 JAR to EJB 1.1
  4. Assemble an application client module
  5. Assemble a J2EE application
  6. Exit the Application Assembly Tool
  7. Start the server
  8. Open the administrative console
  9. Configure a data source
  10. Install the application
  11. Regenerate the Web server plug-in configuration
  12. Stop the application server and start it again
  13. Create database table or tablespace
  14. Ensure that the application, application server, and Web server are running
  15. Test the Java application client
Paths through the tutorial

Start the Application Assembly Tool

Start the Application Assembly Tool, as discussed in the Application assembly tutorial.

Assemble an EJB module, converting from EJB 1.0 JAR to EJB 1.1

  1. On the Welcome to Application Assembly Tool panel:
    1. Click the Existing tab.
    2. Click Browse next to the File name field.
    3. Navigate to the cmp.jar file that you previously downloaded and select Select.

      Browsing for the cmp.jar file

    4. Select OK.
  2. Click OK at the "...please specify the dependent classpath..." dialog.

  3.         This will convert the EJB 1.0 JAR file into an EJB 1.1 JAR file.
  4. Set the global JNDI name of the bean, and bind the data source:
    1. In the topology tree, expand the Entity Beans folder.
    2. Select the bean labeled:

    3.         com_ibm_websphere_gettingstarted_ejbs_SimpleContainerManaged
    4. Click it to display its properties.
    5. Select the Bindings tab.
      1. Set the JNDI Name to:
                      com/ibm/websphere/gettingstarted/ejbs/SimpleContainerManagedHome
        You can use a shorter name as long as you guarantee that it is unique among all installed applications. Using the fully qualified package name of the bean will accomplish this, usually.

      1. Enter Datasource JNDI Name:  jdbc/GsDataSource

        Specifying properties

      2. If using an Oracle database, enter the Oracle admin userid and password under Default Authorizations (this is not required for DB2).
      3. Click Apply.
  1. Save the JAR file using File -> Save As... and name it cmp11.jar.

Assemble an application client module

  1. Create a new application client using File -> Wizards -> Create Application Client Wizard.
  2. On the Specifying Application Client Module Properties panel:
    1. Enter the following:
    2. Specifying Application Client Module Properties

    3. Click Next.
  3. Click Add... on the Adding Files panel.
    1. Click Browse.
    2. Navigate to the client.jar that was previously downloaded, highlight the file and click Select.
    3. Select the com folder (in the right hand pane).
    4. Click Add.

      Adding the files

    5. Click OK.
    6. Click Next.
  4. On the Specifying Additional Application Client Module Properties panel:
    1. Enter cmp11.jar for Classpath.
    2. Click Browse next to Main Class field.
    3. Expand the topology tree in the left pane as far as it goes and select clients.
    4. Select SimpleContainerManagedClient.class in the right pane.

      Selecting the file

    5. Click OK.
    6. Click Next.
  5. Click Next on the Choosing Application Client Module Icons panel.
  6. Click Add on the Adding EJB References panel:
    1. Enter the following:
    2. Set Type: Entity

      Add EJB Reference properties

    3. Click OK.
    4. Verify that your EJB reference is displayed in the EJB References list.

      EJB References list displays the new reference

    5. Click Next.
  7. Click Next on the Adding Resource References panel.
  8. Click Finish on the Adding Environment Entries panel.
  9. Save the application client jar file using File -> Save As. Name it cmpApp.jar.
  10. Application displayed in assembly tool

Assemble a J2EE application

  1. Using AAT, create an .ear by clicking File -> Wizards -> Create Application Wizard.
  2. On the Specifying Application Properties panel:
    1. Enter the following:
    2. Click Next.
  3. Click Next on the Adding Supplementary Files panel.
  4. Click Next on the Choosing Application Icons panel.
  5. Click Add... on the Adding EJB Modules panel:
    1. Navigate to your cmp11.jar file, highlight the file and click Open.
    2. Click OK in the resulting dialog.

      EJB module is listed in Adding EJB Modules

    3. Click Next.
  6. Click Next on the Adding Web Modules panel.
  7. Click Add... on the Adding Application Client Module panel:
    1. Navigate to your cmpApp.jar file, hightlight the file and click Open.
    2. Click OK in the resulting dialog.

      Client module is listed in Adding Application Client Modules

    3. Click Next.
  8. Click Finish on the Adding Security Roles panel.
  9. Bind the EJB reference:
    1. Expand Application Clients
    2. Expand SimpleCMP
    3. Select EJB References.
    4. Select in the right pane the particular reference to your session bean called ejb/SimpleCMP.
    5. Select the Bindings tab.
    6. Enter the following for the JNDI name:
                    com/ibm/websphere/gettingstarted/ejbs/SimpleContainerManagedHome

    Specifying JNDI name

  10. Click Apply.
  11. Save the .ear file by clicking File -> Save As. Name it cmp.ear.

    Saving the file

  12. Generate code for deployment of the .ear file:
    1. Select the .ear file by selecting the top entry in the topology tree (named CmpApp).
    2. Right-click it.
    3. Select Generate Code for Deployment.
    4. In the Generate Code for Deployment panel:
      1. Accept the default for the Deployed module location.
      2. Select the appropriate database type from the list.
    5. Click Generate Now.
    6. When the deployment is complete, close this window.

    The file containing the code generated for deployment will be created called Deployed_cmp.ear.

It might take a while to generate the code for deployment. You can proceed to configure your data source, as described in the next few steps.

  The terminology is potentially confusing here. The file containing the code generated for deployment on the application server is called the Deployed_filename, although it has not been deployed on the server yet. At this point in the application assembly and deployment procedure, the name "Deployed_filename" is more anticipatory than accurate. However, the name will be suitable shortly. After you deploy the "Deployed" file, the name will be useful for distinguishing the file from the pre-deployed version (the one for which you have neither generated code for deployment nor installed on the application server).

Exit the Application Assembly Tool

Recall this step from the Application assembly tutorial.

Start the server

Recall this step from the Application deployment tutorial.

Open the administrative console

Recall this step from the Application deployment tutorial.

Configure a data source

The instructions differ according to whether you are using a DB2 database or Oracle database.

DB2 Database:

  1. In the administrative console, update the Sample DB Driver:
    1. In the console tree view, expand Resources -> JDBC Providers.
    2. Select Sample DB Driver to display its properties.
    3. Click the Node tabbed page.
    4. Check the Class Path to ensure it shows the location of the JAR file containing the DB2 JDBC driver classes (db2java.zip) on your system.
    5. Click Apply if you changed the classpath.
  2. Configure a new data source provider:
    1. In the tree view, expand Resources -> JDBC Drivers -> Sample DB Driver.
    2. Right-click Data Sources and select New from the resulting menu.
    3. Enter the following values. (If a field value is not specified, leave the field blank).
    4. Click OK.

Oracle Database:

  1. In the administrative console, create the OracleJdbcDriver:
    1. In the topology tree, expand Resources
    2. Select JDBC Drivers.
    3. Click New.
    4. Enter the following:
    5. Click OK.
    6. Save the configuration by clicking Save.
  2. In the administrative console,  configure a new data source:
    1. In the topology tree, expand Resources -> JDBC Drivers -> OracleJdbcDriver.
    1. Select Data Sources.
    2. Click New.
    3. Enter the following values. (If a field value is not specified, leave the field blank).
    4. Click OK.
    5. In the topology tree, expand Resources -> JDBC Drivers -> OracleJdbcDriver -> DataSources.
    6. Select GettingStartedDataSource.
    7. Select Property Set at bottom of screen.
    8. Select Resource Properties.
    9. Click New.
    10. Enter the following:
    11. Click OK.
    12. Click OK.
    13. Click OK.
    14. Save the configuration by clicking Save.  Save it under server-cfg.xml and click OK.

Install the application

Ensure you have finished generating code for deployment, before beginning this step.

  1. In the console tree view, right-click WebSphere Administrative Domain -> Enterprise Applications.
  2. From the resulting menu, click Install Enterprise Application to launch the Install Enterprise Application wizard.
  3. On the Specifying the Application or Module panel:

    1. Ensure that the Browse for file on node field is set to your current node.
    2. Ensure Install Application is selected.
    3. Click Browse, next to the Path field. Browse for the Deployed_cmp.ear file and select it.

      Verify that its name is displayed in the Path field now.

    4. Specify CmpApp as the Application name.
    5. Click Next.
  4. On the Mapping Users to Roles panel, click Next.
  5. On the Mapping EJB RunAs Roles to Users panel, click Next.
  6. On the Binding Enterprise Beans to JNDI Names panel, verify that the JNDI Name is set to com/ibm/websphere/gettingstarted/ejbs/SimpleContainerManagedHome, and then click Next.
  7. On the Mapping EJB References to Enterprise Beans panel, click Next.
  8. On the Mapping Resource References to Resources panel, click Next.
  9. On the Specifying the Default Datasource for EJB Modules panel, verify that the JNDI Name is set to jdbc/GsDataSource, and click Next.
  10. On the Specifying Data Sources for Individual CMP Beans panel,verify that the JNDI Name is set to jdbc/GsDataSource, and click Next.
  11. On the Selecting Virtual Hosts for Web Modules panel, ensure that the Virtual Host is set to default_host, then click Next.
  12. On the Selecting Application Server panel, ensure that the modules in CmpApp are going to reside on Application Server "Default Server," then click Next.
  13. Click Finish on the Completing the Application Installation Wizard panel.
  14. When prompted whether to regenerate code, click No.
  15. Look for the message confirming successful installation of the application. It might be a minute before it is displayed.

You can now view the CmpApp in the console tree view.

Regenerate the plug-in configuration

Recall this step from the basic Application deployment tutorial.

Stop the server and start it again

Recall this step from the basic Application deployment tutorial.

Create database table or tablespace

The instructions differ according to whether you are using a DB2 database or an Oracle database.

DB2 Database:

  1. Open a command window.
  2. Type db2cmd (NT/Windows 2000) or db2 (Unix) to start a DB2 command window.
  3. If you do not already have a database named SAMPLEDB, you must create one:
    1. db2 create database SAMPLEDB
  4. Extract the DDL from the deployed jar file:
    1. In the WebSphere administrative console tree view, select Applications -> CmpApp -> EJB Modules to display the list of EJB modules in the top right part of the console.
    2. Right-click the EJB module and select Export Table DDL from the resulting menu.
  5. Create the table:
    1. db2 connect to SAMPLEDB
    2. db2 -t -f META-INF\Table.ddl

    3. A table named COM_IBM_WEBSPHERE_GETTINGSTAR1 will be added to the SAMPLEDB database.
  6. Exit the db2 command window.

Oracle Database:

  1. Open a command window.
  2. Extract the DDL from the deployed jar file:
    1. jar -xvf %was_home%\installedApps\Deployed_cmp.ear\cmp11.jar META-INF\Table.ddl
  3. Create the tablespaces:
    1. svrmgrl
    2. connect <oracle db userid>/<oracle db password>
    3. @META-INF\Table.ddl

    4. A tablespace named COM_IBM_WEBSPHERE_GETTINGSTAR1 will be added database.
  4. Exit the oracle command window.

Ensure that the application, application server, and Web server are running

Recall learning this step in the Application testing tutorial.

Test the Java application client

  1. Open a system command prompt.
  2. Change directory to:
    product_installation_root/bin
  3. Enter the command:
    launchClient ../temp/tutorial/cmp/Deployed_cmp.ear
    
    (Remember, on Windows systems, the forward slashes should be backslashes).
What's next?

Proceed to the Application removal and cleanup tutorial if you would like to uninstall the applications that you introduced into the server runtime during the tutorial.