OTN WebServices Sample

Table of Contents

• Overview of the Sample Application
• Required Software
• Notations used
• Extracting the source code
• Configuring the Application
• Deploying and Running the Application
• Description of Sample Files
• Viewlets in this Sample
• Troubleshooting

This sample assumes the existence of an e-Business selling its merchandise worldwide. It features several products, the details of which are maintained in the database. This enterprise has a number of warehouses to cater to customers distributed geographically.

The sample is a JSP based web application that makes use of number of web services. The application would enable the customer to do the following :

• Login to the application
• Browse through the products available
• View product details like availability, price in local currency
• Place an order on the products of interest
• Select the shipping options available to the user
• Accept Credit Card number from the user and verify it
• Mail the order Invoice to the customer.

The following use case diagram depicts the functionality of the sample. The ovals displayed in yellow are web services hosted on Oracle9iAS. These web  services will be called by the e-Business application at different times.

The description of the 5 different types of webservices used by this sample are as follows:

1. Currency Exchange Service (3rd Party Service)

This service uses the Currency Exchange Service available at http://xmethods.com. This service is used by this application, to convert the product price, which is stored in US Dollars to user's local currency. The user's local currency information is stored in Customers table in the database.

See. Currency Exchange Service (Viewlet) to learn how to generate Stub for this 3rd Party Web Service.

2. Shipping Service (Stateful Java Web Service)

This service is deployed as Stateful Java WebService. There are two methods available with this method

• showShippingOptions(orderID)
• This method returns the list of shipping options available to the customer and stores the orderID in its State
• commitShippingOption(serviceID)
• This method commits shipping option by updating the order table with the selected shipping service and id. It uses the orderID saved in its state.

See. Shipping Service (Viewlet) to learn how this web service was developed.

3. Tax Calculator Service (Stateless PL/SQL Web Service)

The tax calculation business logic is developed in the TAX_CALCULATOR.CALCULATE_TAX stored procedure in the database. This Service exposes the PL/SQL stored procedure as Web Service.

See. Tax Calculator Service (Viewlet) to learn how this web service was developed.

4. Credit Card Verification Service (Stateless Session Bean Service)

This service verifies the validity of the credit card entered by the user. This service is deployed as Stateless Session Bean. The Bean contains the business logic, which performs simple validation like the card number is 16 digits and all are numeric and the bill amount is within $1,000 .

See. Credit Card Verification Service (Viewlet) to learn how this web service was developed.

5. Mail Service (Stateless Java Service)

This service is deployed as Stateless Java Service. This service uses Java Mail API's to send the Order Invoice as e-mail to the customer. The mail id of the customer is stored in the Customer Table in the database. Change this mail id in the database, to the mail account you would like to receive mails.

See. Mail Service (Viewlet) to learn how this web service was developed.

1) Oracle9i JDeveloper or higher (Note: JDeveloper is Oracle's Visual Java Development Tool and can be downloaded from location here ). This software is tested on Oracle9i JDeveloper Maintenance Release (Version 9.0.3.1).

2) Oracle9iAS Containers for J2EE (OC4J) Version 9.0.2.0.0 or later. It can be downloaded from here.

3) Oracle9i v9.0.1 or higher Client installation. (Note: The Client installation is not required if the database is installed on your machine or you have easy access to the machine where database is installed. )

4) Oracle9i v9.0.1 (Database) or higher running SQL*Net TCP/IP listener.

This section will describe the terms used in the document.

Step 1. Unjar the provided WebServicesSample.jar using the following command:

> jar xvf WebServicesSample.jar

JDeveloper places jar.exe in <JDEV_HOME>\jdk\bin. Make sure jar.exe is present in your system path.

Follow the steps given below to setup the database or follow Deploying & Running the Sample (Viewlet) to learn how to configure, deploy and run the sample.

Step 1: Connect to the database to which you would be using as system administrator

SQL> CREATE USER ws IDENTIFIED BY ws;
SQL> GRANT connect, resource TO ws;
SQL> CONNECT ws/ws@<database_tnsname>

where <database_tnsname> is the TNSNAME of the database where the user is created.

Step 2: Run tables.sql from <SAMPLE_HOME>\sql directory. This SQL Script, creates tables, data and PL/SQL procedure (the one used by TaxCalculation Service) required by the system.

Step 3: Change the Email_Id column in Customers table so that the emails are sent to your account. This step is optional.

Follow the steps given below to deploy and run the application or follow the viewlet present here.

Step 1: Open the Sample

Using JDeveloper File/Open option select the webservices.jws from the <SAMPLE_HOME> directory.

Step 2: Edit Properties

Edit the ConnectionParams.java in the biz.jpr project file. Enter the database machine details and OC4J details in this class file.

Note: For DHCP users
    Those who have configured DHCP should ensure that they use the IP address allocated to their machine. This can be found by using the ipconfig command to determine the IP address. This is needed for the external services on XMethods requiring a proxy,  to work in conjunction with internal EJB and other services.
 

Step 3: Deploy the Sample Application

• Ensure that OC4J is Started.
• Create an Application Server Connection by clicking on the Connections Node.
• Right click on Application Servers and select New Connection.
• Provide the appropriate connection information of the Application Server to which the sample is to be deployed.
• Select the webapp.deploy file in the biz.jpr
• Right click on webapp.deploy and select Deploy to <connection name>, where <connection name> is the name of the connection created in the previous step. This deploys all the services and the web application to OC4J.

Step 4: Run the Sample Application

• Access the page on the browser, using the url http://<hostname>:<port>/WS-Demo/Login.jsp

where <hostname> is the machine where OC4J is running, DHCP users should specify the IP address allocated to the machine.
           <port> is where OC4J listens for web requests.
            for example, http://incq221b.idc.oracle.com:8888/WS-Demo/Login.jsp

The following list includes list of files/directories in the <SAMPLE_HOME> directory.

This sections contains the lists of viewlets in this sample.

Problem :

The sample is installed on Base Install of Oracle9i JDeveloper 9.0.3.1 Maintenance Release and the following error is displayed on the log window when the user tries to compile the sample.

**** Error(27,25): cannot access class oracle.jdbc.pool.OracleConnectionCacheImpl; file oracle\jdbc\pool\OracleConnectionCacheImpl.class not found
**** Error(37,18): class OracleConnectionCacheImpl not found in class oracle.otnsamples.webservices.biz.PersistanceManager

The same error is received in few more java files.

Solution : Right click the project in which the Java file is present. Select Project Settings. Click on Libraries under the section Configurations/Development. On the right pane, click on New. In the popup window, under Library Name, enter Oracle JDBC jars. Now, click on the Edit button besides the Classpath.  In the popup window, click on Add Entry. Now select <JDEV_HOME>/jdbc/lib/classes12.jar and <JDEV_HOME>/jdbc/lib/nls_charset12.jar click Select. Now add this library to the Selected Libraries of each project where the error is received.

Please enter your comments about this sample in the OTN Sample Code Discussion Forum.