Setup

This section explains the steps to install and configure the BC4J-VSM sample application. It contains the following sections:

• Notations Used
• Downloading and Extracting the source code
• Configuring the Application
• Deploying and Running the Application
• From Oracle9i JDeveloper
• From Stand-Alone OC4J
• Troubleshooting 

The application files are stored in an archive named vsm-bc4j.jar. Download the archive and extract it to a convenient directory. Execute following command to extract the files:

 jar xvf vsm-bc4j.jar

All the files are extracted into the VSM-BC4J directory. The directory structure is described in detail in the Implementation section.

1. Open a SQL*Plus prompt  and run the VSM-BC4J/config/webstore.sql script. This will create two database users:

• bc4jvsm/welcome - Required tables and initial data.
• bc4jvsm_internal/welcome - Used by the BC4J framework to handle transactions and other details.

2. Edit  VSM-BC4J/config/Message.properties. Change the SMTP host name to your SMTP server. Change the following line

mail.smtp.host = <smtp.host>

3. Create a certificate to sign the JARs needed by JClient application. To do this, open a command prompt and run
          
   keytool -genkey -alias mykey -keypass welcome -storepass welcome
   
   This will generate a key pair (a public key and associated private key), wrap the public key into an X.509 v1 self-signed certificate, which is stored as a single-element certificate chain. This certificate chain and the private key are stored in a new keystore entry identified by alias.
   By default keystore is a file named .keystore generated in the user's home directory, determined by the "user.home" system property.
         Note:
   -keypass : The private key password
   -storepass : The password which is used to protect the integrity of the keystore database.
   
   For more help on this, see the topic Developing Java GUI Clients-> Working with Java Web Start and JClient Applications in JDeveloper Online Help.

4. Go to <JDEV_HOME>/BC4J/bin and run
                             create_jclient_ear.bat sign on Windows or
                             create_jclient_ear.sh sign  on Linux.
   This will create  bc4jlibs.ear in <JDEV_HOME>/BC4J/jlibs, which will be used for deploying JClient Admin application for VSM. The jars in this EAR are signed.

5. Edit VSM-BC4J/src/ctbuild.xml and modify the properties ct.proj.dir and mt.proj.dir to point to the folder VSM-BC4J .

6. Copy the files <JDEV_HOME>/j2ee/home/lib/mail.jar,
   <JDEV_HOME>/j2ee/home/lib/activation.jar,
   <JDEV_HOME>/j2ee/home/lib/http_client.jar and
   <JDEV_HOME>/soap/lib/soap.jar
   to VSM-BC4J/public_html folder.
   These are the extra libraries that are needed by JClient application.

7. Copy  <JDEV_HOME>/BC4J/lib/datatags.jar and  <JDEV_HOME>/jakarta-struts/lib/struts.jar to VSM-BC4J/webroot/WEB-INF/lib folder.

8. Go to the <JDEV_HOME>/BC4J/bin directory and run bc4j2oc4j.bat on Windows or bc4j2oc4j on Linux.
   

Note: If you encounter any problems, check the Troubleshooting section.

• General Steps
• Running the application using Oracle9i JDeveloper
• Running the application using OC4J

General Steps

1. Open the workspace VSM-BC4J/VSM-BC4J.jws in Oracle9i JDeveloper.

2. Create two database connections , one for each of the users created in step 1.
   Go to File->New-General->Connections->Database Connections
   and follow the wizard.  In "Step 1:Type" screen of the wizard , use database user names as connection names.
   In "Step 2: Authentication " screen of the wizard select the Check box labeled "Deploy Password" for both connections.

3. After this you will have two connections with names bc4jvsm and bc4jvsm_internal.

4. Right click on VSMWebapp.jpr and select Project Settings->Configurations->Developement->Libraries. In the list of 'Selected Libraries' on the  right-hand side, select Struts Commons. Press Edit and make sure that Struts Commons classpath is pointing to jars in <JDEV_HOME>/jakarta-struts/lib.
   If not, make the changes.

5. Right click on VSM-BC4J.jws and select "Rebuild VSM-BC4J.jws". This will compile all the files and  place them in VSM-BC4J/classes  and
   VSM-BC4J/controller_classes  folders.

Running the application using Oracle9i JDeveloper

Running the VSM web application :

Right-click on the project VSMWebapp.jpr and select "Run".

This will deploy the application to embedded OC4J ,open the default browser and present you with the main page of the application

Also this will deploy the Credit Card validation web service to embedded OC4J. The VSM Web application will access the web service to validate credit card numbers. The endpoint for this web service is specified in VSM-BC4J/config/Message.properties file.

Note: If you encounter any problems while deploying or running the application, check the Troubleshooting section.

Running the VSM Administration Client using Java Web Start:

1. Navigate to VSM-JClient.jpr->Ant Buildfiles -> ctbuild.xml . Right click on this file and select  Build Target->sign. This will create the necessary jar files and sign them.

2. Navigate to VSM-JClient.jpr->HTML Sources -> LocalAdminRunner.html. Right click on this file and select "Run". This will deploy the JClient application files and the required JNLP (Java Network Launch Protocol) files to embedded OC4J.

3. Create an application server connection by navigating to File->New->General->Connections ->Application Server connections and using the wizard.

1. Provide the Connection Name as 'Local'
2. Provide  User Name/Password as admin/welcome.
3. Provide URL as "ormi://localhost:23891".
   Embedded OC4J listens on port 23891 by default.
   Provide Target Web Site as "default-web-app

4. Test the connection and press Finish.

4. Go to VSM-BC4J/src. Open deploy_bc4jlibs.bat or deploy_bc4jlibs.sh, change JDEV_HOME, SERVER, PASSWORD and PORT variables so as to point to proper values. Where SERVER is the IP address of the server where OC4J is running, PASSWORD is the admin password and PORT is the rmi port of the local application server.

5. Now run deploy_bc4jlibs.bat on Windows or deploy_bc4jlibs.sh on Linux

6. Navigate to VSM-BC4J.jpr->Web Services->oracle.otnsamples.vsm.services.CreditCardServicesWS. Right Click and select  Run.This will deploy the Credit Card validation web service to embedded OC4J. JClient application will access the web service to validate credit card numbers. The endpoint for this web service is specified in VSM-BC4J/config/Message.properties file.

7. In the browser, click on Launch JClient Project. This will start JWS , which downloads and starts the VSM Local Administration Application.

Note: If you do not want to use JWS for running the VSM JClient application, you can run it from JDeveloper directly, by performing step 5 as described above and  running AdministrativeServiceForm.java   in VSM-JClient->Sources->oracle.otnsamples.vsm.client.admin.

Running the application using OC4J

1. Start  an instance of OC4J  using java -jar oc4j.jar from <OC4J_HOME>/j2ee/home folder.
2. Create an application server connection by navigating to File->New->General->Application Server connections. Follow the wizard.
       Step 1 : Provide the Connection Name as 'Remote'
       Step 2:  Provide  User Name/Password of OC4J
       Step 3:  Change URL to the URL of OC4J 
       Step 4 : Test the connection and press Finish.
   

Running the VSM web application :

1. Modify  webservices.endpoint in VSM-BC4J/config/Message.properties to point to OC4J.

2. Navigate to VSMWebapp.jpr ->Deployment->VSMWebEar.deploy in Oracle9i JDeveloper . Right click and select "Deploy to Remote".

3. Open a browser and point to http://<oc4j_server>:<port>/bc4jvsm/home.do. This will present you with the main page of the application.

Running the VSM Administration Client using Java Web Start:

1. Select the VSM-JClient.jpr project and then select Project->Show Categories from the menu. Navigate to VSM-JClient.jpr->Ant Buildfiles -> ctbuild.xml . Right click on this file and select  Build Target->sign.
   This will create the necessary jar files and sign them.

2. Navigate to VSM-BC4J.jpr->Deployment->WebServices.deploy. Right Click and select  Deploy To Remote.This will deploy the Credit Card validation web service to