Sun ONE logo     
CCI Connector Sample Application



CCI Connector Sample Application


This document describes how to utilize the CCI Connector sample application in conjunction with Sun ONE Application Server version 7.

This sample application document contains the following sections:



Overview

The CCI Connector sample application shows how to connect to a Resource Adapter using CCI API's of J2EE's Java Connector Architecture (JCA).

The CCI sample application connects to the PointBase database using the resource adapter (RA) from J2EE Reference Implementation (cciblackbox-tx.rar). A session bean connects to the PointBase database using this resource adapter, then counts the number of rows in the Coffee table, inserts 3 rows, and then returns the new count. The database is the EIS (Enterprise Information System) for this sample.

The deployment descriptor (ra.xml) has been modified to point to the PointBase database, with sun-ra.xml added. These can be found in install_root/samples/connectors/cci/src

sun-ra.xml contains the following nformation:

  • JNDI Name

  • Pooling configuration

  • Security role map.

For more information, please refer to sun-connector_1_0-0.dtd under install_root/lib/dtds directory.

The Directory Structure of the Sample Application is:

src - install_root/samples/connectors/cci/src

It contains all the source code for sample applicaton. This directory has all the deployment descriptors. The directories which are located under this one are:

  • samples

    Contains EJB and EJB client code; this is the client to the resource adapter.

  • sql

    Sql files are used to create the tables and procedures. Please note that in the PointBase database, the procedure body is implemented in Java (SampleExternalMethods.java).

The assemble directory (install_root/samples/connectors/cci/assemble) contains the following directories which are deployed as part of the this sample. The connector (CciBlackBoxLocalTx) is deployed as a standalone module. The ejb and client are deployed as an application (CoffeeApp).

    • client

    • jar

    • ear

    • rar

This sample is picked up from J2EE Reference Implementation. Please refer to http://java.sun.com/j2ee/tutorial/1_3-fcs/doc/Connector.html for more information.


Setting up for Pointbase Database

In order to successfully deploy and run the CCI Connector sample application, the Pointbase database first needs to be configured.

To configure the database, do the following:

  1. Go to the PointBase server directory. For example:

    install_root/pointbase/server

  2. Edit the file StartServer.sh and add the following to the classpath: install_root/samples/connectors/cci/src/sql

    This step is necessary in order to make the stored procedures used in this sample available to PointBase. Please refer to install_root/pointbase/docs/pbdeveloper.pdf for more details on PointBase procedures and functions.

  3. Start the database server by running the following script:

    ./StartServer.sh


Setting up for Oracle Database

If using Oracle, please do the following steps :

  1. Create user "CCI", password as "CCI". Instructions to create user account is mentioned in the document Using oracle with samples . Please note that this sample connects to database directly using JDBC URL, and does not use the datasource and connection pool resources of Sun ONE Application server. For this reason the steps of running this sample on Oracle differs for that described in Using oracle with samples .
  2. Add oracle jdbc driver (eg. ojdbc14.jar) in your server instance's classpath. This can be done by going to the Administration module, go the the server instance (eg server1), click on "JVM Settings", then "Path Settings", add the oracle jdbc driver to CLASSPATH suffix, "Save", "Apply changes" and restart the server instance.
  3. Edit your samples/connectors/cci/src/build.xml and change the following:
    • <property name="db.file" value="sql/cci-ora.sql"/>
    • <property name="jdbc.drivers" value="oracle.jdbc.driver.OracleDriver" />
  4. Edit samples/connectors/cci/src/ra.xml and change the following:
    • <config-property-value> jdbc:oracle:thin:@oracle-host:oracle-port:oracle-sid </config-property-value>
      Substitute oracle-host, oracle-port (1521 is default) and oracle-sid with the correct values


Compiling and Assembling the Application



This section contains instructions to build and assemble the CCI Connector sample application.

To easily compile, assemble and deploy the application, see the Sample Application Build Facility document for details on using asant facility to quickly perform these tasks.

  1. To rebuild the entire application from scratch, do the following:

    Execute the command "asant core" under connectors/cci/src

  2. To clean up the sample application project area, do the following:

    Execute the command "asant clean".

    This will will delete the connectors/cci/assemble and connectors/cci/build directories.



Deploying the Sample Application

This section contains instructions to deploy the CCI Connector sample application.

To deploy the application, do the following:

  • Execute the command "asant deploy" under connectors/cci/src/

    It will be necessary to restart the application server.

To undeploy the application, do the following:

  • Execute the command "asant undeploy"

    This will undeploy both the connector and the sample application that tests connector.

To undeploy the connector alone, do the following:

  • Exceute "asant undeploy_connector"



Running the Sample Application

In order to run the sample application, you must first do the following:

Now you are ready to run the sample application by doing the following.

  1. Go to the directory install_root/domains/<domain-name>/<server-instance>/applications/j2ee-apps/cci_1

  2. Run the following command:

    appclient -client cciClient.jar -name CoffeeClient -textauth

    You should see the following output lines displayed:

    Coffee count = 0

    Inserting 3 coffee entries...

    Coffee count = 3

    Jul 16, 2002 12:13:18 PM com.iplanet.ias.appclient.Main <init>


Generating javadocs

To better understand the 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 have been generated, you may access them at install_root/samples/connectors/cci/javadocs/index.html.



Troubleshooting



  • If you encounter problems when running the application, review the log files at install_root/domains/<domain-name>/<server-instance>/logs/server.log to learn what exactly went wrong.

  • If the rar file gets deleted, then please download it from J2EE 1.3 web site at http://java.sun.com/j2ee/sdk_1.3/ and the download J2EETM Connector Architecture 1.0.1 Sample. Copy cciblackbox-tx.rar to install_root/samples/connectors/cci directory.

  • Check if the database is configured as described above.

  • If the error in server.logs reads "No suitable driver found", check your JVM options (server1->JVM Settings->JVM options). If missing, add the property -Djdbc.drivers=com.pointbase.jdbc.jdbcUniversalDriver (for PointBase). Restart server instance and test again.

  • To reset your database, run the command "asant sql".

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

  • This sample may not work if you do have a pre Oracle 9 version of JDBC Driver. This is a known issue with Oracle. Please try with 9.0.1 driver.

  • The sample can not be deployed from the application server administration GUI, if Run verifier option is selected. Solution is, try deploying the application without Run verifier, or deploy using asant.

  • The sample can not be deployed using asadmin with option --verify=true. Solution is, try deploying the application without the option --verify=true, or deploy using asant.



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

Last Updated July 18, 2002