2.2 Installing the SOA Order Booking Demonstration Application

The SOA Order Booking application runs using Oracle SOA Suite and an Oracle database. To install the SOA Order Booking application, you must:

1. Meet installation requirements and prerequisites. For details, see Section 2.2.1, "System Requirements" and Section 2.2.2, "Application Installation Prerequisites".

2. Install the database tables into an Oracle database. For details, see Section 2.2.3, "Installing the Database Schema".

3. Create a connection pool, data source, and a database adapter connection for the application's container. This allows the application to access the database. For details, see Section 2.2.4, "Configuring the Container".

4. Deploy the individual applications to the container using Oracle JDeveloper.

2.2.1 System Requirements

There are no system requirements in addition to those to install and run Oracle SOA Suite. For more information, refer to Oracle Application Server Installation Guide for Microsoft Windows. You must install Oracle SOA Suite, Oracle JDeveloper, and the SOA Order Booking application on Windows.

2.2.2 Application Installation Prerequisites

The SOA Order Booking application requires an existing Oracle database and Oracle SOA Suite. You deploy the SOA Order Booking application using Oracle JDeveloper.

Do the following before installing the SOA Order Booking application:

• Install an Oracle database: The SOA Order Booking application requires a database for its data. The SQL scripts were written for an Oracle database, so you will need some version of an Oracle RDBMS, such as 9i, 10g, or XE. The scripts will not install into Oracle Lite. If you wish to use Oracle Lite or some other database, then you will need to modify the database scripts accordingly. You can download an Oracle database from:

  http://www.oracle.com/technology/
  
  

  Specifically, Oracle Express Edition (XE) is a small footprint database and is recommended. You can download it from:

  http://www.oracle.com/technology/products/database/xe/
  
  

• Install Oracle SOA Suite. You can download Oracle SOA Suite 10.1.3.1.0 from:

  http://www.oracle.com/technology/soa/
  
  

• Install Oracle JDeveloper: You need Oracle JDeveloper 10.1.3.1 Studio Edition to deploy certain parts of the SOA Order Booking application and to view the application's projects. You can download Oracle JDeveloper from:

  http://www.oracle.com/technology/products/jdev/
  
  

  
  

  Note: Ensure you download and install 10.1.3.1 (not to be confused with 10.1.3.0) and that it is the Studio edition, not the J2EE or Java edition. You can verify these details in Oracle JDeveloper from the Help > About menu option.

  
  

• Download the SOA Order Booking application zip file (SOADEMO.zip). Extract this zip file to a working directory. This directory will be referred to as DEMO_HOME for the remainder of this document. You can download the application zip file from:

  http://www.oracle.com/technology/soa/
  
  

2.2.3 Installing the Database Schema

All the tables required for the SOA Order Booking application are contained in one schema. In a real-world SOA application, it is unlikely that all the tables would be in the same schema, or even the same database or location.

Installing the schema involves creating a user and running SQL scripts that install the schema and populate the tables with sample data.

To install the schema:

1. Connect to your database and create a user named soademo.

   SQL> create user soademo identified by soademo;
   SQL> grant resource, connect to soademo;
   
   

2. Connect to the database as user soademo:

   SQL> conn soademo/soademo
   
   

3. From the DEMO_HOME directory, run the following scripts in the order listed:

   • createSchemaObjects.sql

   • populateSchemaTables.sql

   
   

   Note: Ignore any issues the first time you run these scripts when objects are dropped. These errors are fine, as the objects have not been created yet.

   
   

2.2.3.1 The SOA Order Booking Schema

In a real-world SOA application, it is unlikely that all the tables would be in the same schema. Table 2-1 shows each table installed in the SOADEMO schema, along with a description of the data stored in the table, the application that uses the table, and where, in a real-world scenario, the table would likely exist.

Table 2-1 Tables in the SOADEMO Schema

Table	Description	Application	Location
ADDRESS	Contains address information.	Customer Service	In the Global Company enterprise, however, it would not exist in the same database as product and order information.
CUSTOMER	Contains customer information, such as name, email, and credit card number.	Customer Service	In the Global Company enterprise, however, it would not exist in the same database as product and order information.
CUSTOMER_ADDRESS	Maps a customer to an address. This mapping table allows a customer to have more than one address, and an address to belong to more than one customer.	Customer Service	In the Global Company enterprise, however, it would not exist in the same database as product and order information.
EJB_TAB_ID_GEN	Sequence table for IDs used in the Customer Service application.	Customer Service	In the Global Company enterprise, however, it would not exist in the same database as product and order information.
FEDEXSHIPMENT	Contains shipping details for an order.	Fulfillment ESB	Federal Express
ITEMS	Contains information regarding the items contained in an order.	SOAOrder Booking	Global Company. This is a "legacy" table that is integrated into the flow, as opposed to a table created for the flow.
ORDERS	Contains information regarding an order. A sequence creates the order IDs.	SOAOrder Booking	Global Company. This is a "legacy" table that is integrated into the flow, as opposed to a table created for the flow
PRODUCT	Contains the products offered for sale on the web site.	SOADEMO-CLIENT	Global Company

The SSN table is used by the Oracle Application Server Quick Tour and is not covered in this document.

Figure 2-1 shows the schema for the SOA Order Booking application.

Figure 2-1 The SOA Order Booking Schema

2.2.4 Configuring the Container

Once you install Oracle SOA Suite, you need to create a connection pool, data source, and database adapter for the SOA Order Booking application.

To configure the container:

1. Point your browser to the Enterprise Manager for your installation of Oracle SOA Suite. You will use the Enterprise Manager to configure the application server and containers.

   For example:

   http://localhost:8888
   
   

   8888 is the default HTTP port. Use the port number that the installer selected for your environment. If port 8888 does not work for you and you are not sure what your port number is, use a text editor and open this file:

   ORACLE_HOME\install\readme.txt
   
   

   Look for the line Access the Oracle SOA Suite 10g Application Server Welcome Page via the following URL and the next line will show you the URL for your Enterprise Manager welcome page.

2. From the right-hand side Manage Your SOA Suite portlet, click the Application Server Control link.

   The Application Server Control Console displays the administrator logon dialog box.

3. Enter a valid username and password for Oracle Enterprise Manager 10g. By default, oc4jadmin is the administrator user. The password for this user was set during the Oracle SOA Suite installation.

4. Create a connection pool and JDBC data source for the OC4J instance.

   A data source enables you to retrieve a connection to a database server. A managed data source uses a connection pool to efficiently manage a database connection. You must define one connection pool and its connection factory.

   1. Select the home OC4J link.

      The OC4J: home page appears.

   2. Click the Administration tab.

   3. In Services > JDBC Resources, click the Go To Task icon.

      The JDBC Resources pages appears.

   4. In the Connection Pools section, click the Create button.

      The Create Connection Pool - Application page appears.

   5. Accept defaults, and click Continue.

      The Create Connection Pool page appears.

   6. Enter the following values, leaving the defaults for the other fields:

      Element	Value
      Name	soademo_pool
      JDBC URL	URL for your database. For example: jdbc:oracle:thin:@localhost:1521:orcl
      Username	soademo
      Password	Password entered when creating the soademo user in the database

      
      

   7. Click Test Connection.

      The Test Connection page appears.

   8. Click Test.

      The JDBC Resources page updates with a successful connection confirmation message. If you get an error message, check the URL and credentials to ensure that you entered the right information.

   9. Click Finish.

   10. Under Data Sources, click Create.

       The Create Data Source - Application & Type page appears.

   11. Accept the defaults, and click Continue.

       The Create Data Source - Managed Data Source page appears.

   12. Enter the following values, leaving the defaults for the other fields:

       Element	Value
       Name	soademoDS
       JNDI Location	jdbc/soademoDS
       Connection Pool	soademo_pool

       
       

   13. Click Finish.

   14. Back in the Data Sources section, locate the soademoDS data source, and click the Test Connection icon.

       The Test Connection page appears.

   15. Click Test.

       The JDBC Resources page updates with a successful connection confirmation message.

5. Create a database adapter connection factory.

   This connection factory will be used by an outbound database adapter within a process flow written in Business Process Execution Language (BPEL), using the Java Transaction API (JTA). Because of this, you need to define an xaDataSourceName that points to a transaction-level global data source in the data-sources.xml file, as opposed to the locally transacted data source (dataSourceName).

   1. At the top of the JDBC Resources page, click the OC4J:home breadcrumb link.

      The OC4J: home page appears.

   2. Click the Applications tab.

   3. In the table of applications, click the default link.

      The Application: default page appears.

   4. In the Modules section, click the DbAdapter link.

      The Resource Adapter: Database Adapter page appears.

   5. Click the Connection Factories tab.

   6. At the top of the page, click the Create button.

      
      

      Note: Do not click the Create button in the Shared Connection Pools section.

      
      

      The Create Connection Factory: Select Interface page appears.

   7. Accept the default interface, and click Continue.

      The Create Connection Factory page appears.

   8. In the JNDI Location field, enter eis/DB/soademo.

   9. In the Configuration Properties section, for xADataSourceName, enter jdbc/soademoDS.

   10. Leave the defaults for the other fields.

   11. Click Finish.

   12. Leave the Application Server Control Console running, as you need it for the next task.

The container is now configured for the SOA Order Booking application.

2.2.5 Noting the Important Port Numbers

The SOA Order Booking application has some configuration files that use the default port numbers. Your installation may not be using the default port numbers and may need to be reconfigured. you can use the Application Server Control Console to find the port numbers being used in your environment.

To find the port numbers:

1. From Application Server Control Console, click the Cluster Topology breadcrumb link.

2. In the Administration section towards the bottom of the page, select Runtime Ports.

   The Runtime Ports page shows the ports being used by your installation, as shown in Figure 2-2.

   Figure 2-2 The Runtime Ports Page

   
   

   These are the important ones to note for the SOA Order Booking application installation:

   • OPMN Request (defaults to 6003)

   • OC4J:home HTTP (defaults to 8888)

   • OC4J:home RMI (defaults to 12401)

   If your ports are the same as the defaults, listed above, then you will not need to change any configuration files used in deployment, as they already use those defaults. If one or more of your ports are different, then note them down for now. In some later installation steps you will be asked to refer to these port numbers.

2.2.6 Creating Connections in Oracle JDeveloper

Before you can use Oracle JDeveloper to deploy the application to the server, Oracle JDeveloper needs to know how to connect to the server. This includes the application server and the database.

To create these connections in Oracle JDeveloper:

1. Start Oracle JDeveloper by running JDEV_HOME\jdeveloper.exe.

2. Create a connection to the database using the SOADEMO schema:

   1. Click the Connections tab, or if it not currently displayed, choose View > Connection Navigator.

   2. Double-click on the Database folder to open the Create Database Connection wizard.

   3. Complete the wizard, ensuring that you enter the following:

      - On the Step 1 of 4: Type 1 page, enter soademo for Connection Name.

      - Enter the appropriate values for where you installed the schema.

3. Create the application server connection:

   1. Double-click Application Server to open the Create Application Server Connection wizard.

   2. On the Step 1 of 4: Type page, perform the following and then click Next.

      Element	Action
      Connection Name	Enter a connection name of your choice.
      Connection Type	Select Oracle Application Server 10g 10.1.3.

      
      

   3. On the Step 2 of 4: Authentication page, perform the following and then click Next.

      Element	Action
      User	Enter a valid user name for the application server.
      Password	Enter a valid password for the user name.
      Deploy Password	Click this checkbox.

      
      

   4. On the Step 3 of 4: Connection page, perform the following and then click Next.

      Element	Action
      Host Name	Enter the host name in which you installed Oracle SOA Suite.
      OPMN	Enter the OPMN request port. The default is 6003. See Also: Section 2.2.5, "Noting the Important Port Numbers" to find out what the port number is for your environment
      Group/OC4J Instance Name	Enter home.

      
      

   5. On the Step 4 of 4: Test page, click Test the Connection.

      If the test does not succeed, use the Back button to verify and change values.

   6. Click Finish.

4. Create a connection to the Oracle BPEL Process Manager and Oracle Enterprise Service Bus (ESB) integration server.

   Creating this connection enables you to deploy business processes to Oracle BPEL Process Manager and services to the Enterprise Service Bus.

   1. Double-click Integration Server to open the Create Integration Server Connection wizard.

   2. On the Step 1 of 3: Name page, enter a name of your choice.

   3. On the Step 2 of 3: Connection page, perform the following and then click Next.

      Element	Action
      Application Server	Select the name of the application server you created in Step 3.
      Host Name	Enter the host name in which you installed Oracle SOA Suite
      Port	Enter the port for the Oracle HTTP Server installed with Oracle SOA Suite. The default is 8888. See Also: Section 2.2.5, "Noting the Important Port Numbers" to find out what the port number is for your environment

      
      

   4. On the Step 3 of 3: Test page, click Test the Connection.

      If the test does not succeed, use the Back button to verify and change values.

   5. Click Finish.

2.2.7 Deploying the Separate SOA Order Booking Applications

The SOA Order Booking application actually consists of a number of applications orchestrated to work together to fulfill a customer's order. Specifically, the following applications are part of the SOA Order Booking application:

• CreditService: Validates a customer's credit information.

• CustomerService: Represents an existing CRM application within the Global Company enterprise.

• FulfillmentESB: Provides the ESB flow used to determine the shipping vendor for an order

• OrderBookingESB: Provides the ESB flow used to route order information from the web client and invoke the Order Booking BPEL flow. While the web client could directly invoke the BPEL flow, ESB is used so that more than one client can submit an order.

• RapidService: Provides the web service used to communicate with Rapid Manufacturer to provide a price for a given order. This service is meant to demonstrate a synchronous service interaction.

• SelectManufacturer: Provides the BPEL flow used by Select Manufacturer to provide a price for a given order. This flow is meant to demonstrate integrating with an asynchronous service.

• SOADEMO-CLIENT: Provides the web-based application that enables end users to register themselves as customers, and then order electronics online from Global Company.

• SOAOrderBooking: Provides the BPEL flow that handles the processing of the order.

Note: The SOA Order Booking application also contains two other projects. The DatabaseSchema project contains the scripts needed to create the schema for the applications. The DHLShipment project is used only by Oracle Application Server Quick Tour, and is not documented in this guide.

You use the connections you created in Oracle JDeveloper to deploy the different applications included in the SOA Order Booking application.

To deploy the SOA Order Booking application:

1. Open the applications in Oracle JDeveloper:

   1. In the JDeveloper main menu, choose File > Open.

   2. Navigate to DEMO_HOME and open the SOADEMO.jws file.

   3. Choose File > Open again, and navigate to DEMO_HOME/SOADEMO-CLIENT and open the SOADEMO-CLIENT.jws file.

   Figure 2-3 shows the Application Navigator after you open the two application files. For a description of each of these applications, see Section 2.3, "An Overview of the SOA Order Booking Application".

   Figure 2-3 The SOA Order Booking Applications in Oracle JDeveloper

   
   
   
   

   Caution: The following steps MUST be executed in the order documented, or the applications will not properly deploy.

   
   

2. Deploy the FulfillmentESB project:

   1. Expand SOADEMO.

   2. If you are using port 8888 as your HTTP port, then proceed to Step g. If you are not using the default HTTP port, expand the Resources node and double-click the PurchaseOrder_To_DHLShipmentProcessRequest.xsl file to open it.

      Disregard any errors that appear.

   3. In the PurchaseOrder_To_DHLShipmentProcessRequest.xsl file, replace all instances of 8888 with your port number. See Section 2.2.5, "Noting the Important Port Numbers" to find out what the port number is for your environment.

   4. Click the Source sub-tab, located at the bottom of the PurchaseOrder_To_DHLShipmentProcessRequest.xsl page, to switch to the Source view, as shown in Figure 2-4.

      Figure 2-4 Source Tab

      
      

   5. Replace all instances of 8888 with your port number. See Section 2.2.5, "Noting the Important Port Numbers" to find out what the port number is for your environment.

   6. Choose File > Save to save your work.

   7. Right-click FulfillmentESB and select Register with ESB > <IntegrationServer_Connection_Name>.

   8. Click OK in the ESB Registration Summary dialog.

3. Deploy the Select Manufacturer BPEL process flow using Ant:

   1. Expand SelectManufacturer/Resources.

   2. Open the build.properties file and verify that the values are correct.

      If the values are not correct, change the values and then save the file. To determine correct port information, see Section 2.2.5, "Noting the Important Port Numbers".

   3. In the Application Navigator, right-click build.xml and choose Run Ant.

   4. Configure Ant to use the build.properties file:

      • Click the Properties tab.

      • Remove all properties.

      • In the Property Files section, click Add.

      • In the Add Ant Property dialog, select the build.properties file, click Open, and then click OK.

        This will start the deployment process, which may take anywhere from 30 to 60 seconds. You can monitor the progress in the Messages window, in the Apache Ant - Log tab, in the Apache Ant subtab. You will know the deployment is complete when you see the text BUILD SUCCESSFUL.

4. Deploy the Credit Service application:

   1. Expand CreditService/Resources.

   2. Right-click the WebServices.deploy file, and choose Deploy to > <ApplicationServer_Connection_Name>.

   3. In the Configure Application dialog, click OK.

      When deployment completes, the Deployment - Log displays a Deployment finished message.

5. Deploy the Customer Service application:

   1. Expand CustomerService/Resources.

   2. Right-click the CustomerService.deploy file and choose Deploy to > <ApplicationServer_Connection_Name>.

   3. Click OK in the Configure Application dialog.

      When deployment completes, the Deployment - Log displays a Deployment finished message.

6. Deploy the Rapid Service application:

   1. Expand RapidService/Resources.

   2. Right-click the WebServices.deploy file and choose Deploy to > <ApplicationServer_Connection_Name>.

   3. Click OK in the Configure Application dialog.

      When deployment completes, the Deployment - Log displays a Deployment finished message.

7. Deploy the SOA Order Booking BPEL flow using Ant:

   1. Expand SOAOrderBooking/Resources.

   2. Open the build.properties file, and verify that the values are correct.

      If the values are not correct, change the values, and then save the file. To determine correct port information, see Section 2.2.5, "Noting the Important Port Numbers".

   3. If you are using port 8888 as your HTTP port, then proceed to Step k. If you are not using the default HTTP port, expand the Integration Content node and double-click the bpel.xml file to open it.In the bpel.xml file, replace all instances of 8888 with your port number. See Section 2.2.5, "Noting the Important Port Numbers" to find out what the port number is for your environment.Choose File > Save to save your work, and then restart Oracle JDeveloper.Under the Integration Content node, double-click the CreditValidatingService.wsdl file to open it.Click the Source sub-tab to switch to the Source view.Replace all instances of 8888 with your port number. See Section 2.2.5, "Noting the Important Port Numbers" to find out what the port number is for your environment.Choose File > Save to save your work.Repeat Steps f through i for CustomerSvc.wsdl and RapidService.wsdl.Right-click the build.xml file and choose Run Ant.

   4. Configure Ant to use the build.properties file.

      • Click on the Properties tab.

      • Remove any properties.

      • In the Property Files section, click Add.

      • In the Add Ant Property File, select the build.properties file, click Open, and then click OK.

        This will start the deployment process, which may take anywhere from 30 to 60 seconds. You can monitor the progress in the Messages window, in the Apache Ant - Log tab, in the Apache Ant subtab. You will know the deployment is complete when you see the text BUILD SUCCESSFUL.

8. Deploy the Order Booking ESB project:

   1. If you are using port 8888 as your HTTP port, then skip this step and proceed to Step c. Using a text editor, open the following files and change all references of 8888 with your port number. See Section 2.2.5, "Noting the Important Port Numbers" to find out the HTTP port for your environment.

      DEMO_HOME\OrderBookingESB\OrderBooking.esbsys

      DEMO_HOME\OrderBookingESB\OrderBooking_OrderBookingProcess.esbsvc

   2. Choose File > Save to save your work.

   3. Right-click OrderBookingESB and choose Register with ESB > <IntegrationServer_Connection_Name>.

   4. Click OK in the Summary dialog.

9. Deploy the SOADEMO-CLIENT web client:

   1. If you are using port 8888 as your HTTP port, then skip this step and proceed to Step c. Using a text editor, open the following files and change all references of 8888 with your port number. See Section 2.2.5, "Noting the Important Port Numbers" to find out the HTTP port for your environment.

      DEMO_HOME\SOADEMO-CLIENT\CustomerService\src\oracle\soademo\view\services\runtime\CustomerServiceSoapHttp_Stub.java

      DEMO_HOME\SOADEMO-CLIENT\OrderService\src\oracle\soademo\view\services\runtime\__soap_initiate_ppt_Stub.java

   2. Choose File > Save to save your work.

   3. Expand SOADEMO-CLIENT/Assembly/Application Sources.

   4. Right-click the SOADEMO.deploy file and choose Deploy to > <ApplicationServer_Connection_Name>.

   5. Click OK in the Configure dialog.

2.2.8 Configuring the ESB Port

If your HTTP port is 8888, which is the default, then you do not need to configure the ESB port. Otherwise, follow these steps:

To configure the ESB port:

1. Point your browser to the Welcome to Oracle SOA Suite (10.1.3.1.0) page. For example:

   http://localhost:8888
   

   
   

   Tip: To determine the port number is for your environment, see Section 2.2.5, "Noting the Important Port Numbers".

   
   

2. From the right-hand side Manage Your SOA Suite portlet, click the ESB Control link.

   The Oracle Enterprise Manager 10g ESB Control displays.

3. In the Services pane, select the DefaultSystem group.

   Configuration information appears in the right-hand pane.

   Figure 2-5 Oracle ESB Control

   
   

4. In the Port field, change the HTTP port to the HTTP port number used in your environment.

   
   

   Tip: To determine the port number is for your environment, see Section 2.2.5, "Noting the Important Port Numbers"

   
   

5. Click Apply.

6. Repeat Steps 3 through 5 for other groups in the Services pane: BPELSystem, OrderBooking, and Fulfillment.

7. Close the Oracle Enterprise Manager 10g ESB Control.