COM integration with the Oracle9i EJBs: Purchase Order

This example shows you how you can allow COM clients, such as Visual Basic™ clients, to access Enterprise JavaBeans™ (EJBs) hosted in Oracle 9i™, using J-Integra®.

This example is based on Oracle's Purchase Order EJB. In this example we will create a Visual Basic client that uses the J-Integra® bridge to access Oracle's EJBs. The following diagram shows the overal concept of accessing Oracle's Purchase Order EJB from a VB client using J-Integra®.

In order to run the example, you will need the J-Integra® kit, as well as Oracle9i, and Visual Basic. You can run Oracle9i on any platform it supports, and you will not need to install a JVM on the Windows client machine, although you can run everything on the same machine if you wish.

This makes for a compelling solution from the deployment perspective, since nothing needs to be installed or configured on the Windows client machines .

Prerequisites

You should be familiar with Oracle9i™ Application Server and be able to install and configure your application server to access and run the examples provided by Oracle
Download and install J-Integra®.
Ensure that you have installed the J-Integra® license.

Compile and Deploy Extra EJBs

This example uses one of Oracle's standard examples: PurchaseOrder. You can find this example under ORACLE_HOME\javavm\demo\examples\ejb\entities\purchase.

You can deploy this EJB by running the makeit.bat batch file that is located in the ORACLE_HOME\javavm\demo\examples\ejb\entities\purchase folder. You may need to modify common.bat before launching makeit.bat. The common.bat fiel is in ORACLE_HOME\javavm\demo and configures some of the environment variables that are used in makeit.bat.

After running makeit.bat, run runit.bat to make sure that the PurchaseOrder example has been deployed correctly into your Oracle Application Server. Our Visual Basic client needs some extra EJBs in order to perform its job. We have developed these extra EJBs the same way Oracle has developed its own example.

SKU EJB

This is an Entity Bean that interacts with the skus table. You will find the complete source code and helper files of this EJB in the jintegra\examples\vb-ejb\oracle\PurchaseOrder\Server\sku directory when you download J-Integra®.

Take a look at the SKU Enterprise Java Bean source code and helper files.

The following instruction guides you in deploying this EJB onto your Oracle Application Server.

In the sku folder there are two batch files: makeit.bat and runit.bat. You will use these two batch files to deploy and test the SKU EJB. These two batch files call common.bat, which ships with Oracle Application Server, to configure the environment. In order to take advantage of the provided batch files and also common.bat, you must put the EJB, XML, and batch files in the correct folders. Here is a diagram of the directory structure you need to deploy this EJB:
- Copy SKUBean.java into the server sub-folder.
- Copy Client.java into the client sub-folder, and copy SKUHome.java, and SKURemote.java into skucommon.
- Copy makeit.bat, runit.bat, SKU.xml, and SKUMap.xml into the sku folder. If you copy the sku folder under ORACLE_HOME\javavm\demo\examples\ejb\entities, you can run makeit.bat and runit.bat without any modification. Otherwise, you have to modify these two batch files to reflect your configuration.
Open a DOS session and go to sku folder. Run makeit.bat. If your directory structure is correct, Oracle Application Server should be able to deploy this EJB.
To make sure the deployment went OK, run runit.bat. It should display the content of the skus table in your database.

POQuery EJB

This is an Entity Bean that interacts with the pos table. You will find the complete source code and helper files of this EJB in the jintegra\examples\vb-ejb\oracle\PurchaseOrder\Server\poquery directory when you download J-Integra®.

Take a look at the POQuery Enterprise Java Bean source code and helper files.

The following instructions guide you in deploying this EJB into your Oracle Application Server.

Under the poquery folder there are two batch files: makeit.bat and runit.bat. You will use these two batch files to deploy and test the POQuery EJB. These two batch files call common.bat, which ships with the Oracle Application Server, to configure the environment. In order to take advantage of the provided batch files and also common.bat, you must put the EJB, XML, and batch files in the correct folders. Here is a diagram of the directory structure that you need to deploy this EJB:
- Copy POQueryBean.java into the server sub-folder.
- Copy Client.java into the client sub-folder, and copy POQueryHome.java and POQueryRemote.java into pocommon.
- Copy makeit.bat, runit.bat, POQuery.xml, and POQueryMap.xml into the poquery folder. If you copy the poquery folder under ORACLE_HOME\javavm\demo\examples\ejb\entities, you can run makeit.bat and runit.bat without any modification to these two batch files. Otherwise, you have to modify these two batch files to reflect your configuration.
Open a DOS session and go to the poquery folder. Run makeit.bat. If your directory structure is correct, the Oracle application server should be able to deploy this EJB.
To make sure the deployment went OK, run runit.bat. It should display the content of the pos table in your database.

LineItems EJB

This is an Entity Bean that interacts with the pos table. You will find the complete source code and helper files of this EJB in jintegra\examples\vb-ejb\oracle\PurchaseOrder\Server\lineitems directory when you download J-Integra®.

Take a look at the LineItems Enterprise Java Bean source code and helper files.

The LineItems table does not have a primary-key; however, it has two foreign keys, one to the pos table and one to the skus. Because of this we have to create a special class that combines these two fields and builds a primary-key.

Under the lineitems folder there are two batch files: makeit.bat and runit.bat. You will use these two batch files to deploy and test the LineItems EJB. These two batch files call common.bat, which ships with the Oracle Application Server, to configure the environment. To take advantage of the provided batch files and common.bat, you must put the EJB, XML, and batch files in the correct folders. Here is a diagram of the directory structure you need to deploy this EJB:
- Copy LineItemsBean.java into the server sub-folder.
- Copy Client.java into the client sub-folder, and copy LineItemsHome.java, LineItemsRemote.java, and LineItemsPK.java in licommon.
- Copy makeit.bat, runit.bat, LineItems.xml, and LineItemsMap.xml into the lineitems folder. If you copy the lineitems folder under ORACLE_HOME\javavm\demo\examples\ejb\entities, you can run makeit.bat and runit.bat without any modification to these two batch files. Otherwise you have to modify the two batch files to reflect your configuration.
Open a DOS session and go to the lineitems folder. Run makeit.bat. If your directory structure is correct, the Oracle application server should be able to deploy this EJB.
To make sure the deployment went OK, run runit.bat. It should display the content of the LineItems table in your database.

VB Client

This is an advanced example that deals with more than one EJB. It has two forms and user can use this application to create new Purchase Orders or perform a query against Purchase Order records. You should read the Hello World Example and the Customer Example before working on this example.

The example talks to one of Oracle's standard examples: PurchaseOrder. You will find this example under ORACLE_HOME\javavm\demo\examples\ejb\entities\purchase. There are three more EJBs involved on this example. We have followed the same path which Oracle took in developing their examples. This means each extra EJB has its own folder in which it has the batch files to build and run the EJB, the XML descriptor files, and also each folder contains three sub-folders: client, common, and server. With the provided files you should be able to build these extra EJBs as you build Oracle's. Please refer to Create, Compile, and Deploy Extra EJBs for full detail of these extra EJBs.

You will find the Visual Basic client application in jintegra\examples\vb-ejb\oracle\PurchaseOrder\Client\vb directory when you download J-Integra®.

Open the Visual Basic project called PurchaseOrder.vbp. There are two forms on this application: Purchase Order Form and Query Form.

Take a look at the Purchase Order Form source code.

Take a look at the Query Form source code.

Compile the J-Integra® Bridging Server

The Visual Basic example uses the GetObject function to create the home objects of the different EJBs used in this application. When the Visual Basic client invokes GetObject, a J-Integra® bridging server picks up the call, creates the appropriate object, and returns it to the Visual Basic client. The J-Integra® bridging server is a simple Java application that listens to all incoming requests on a specific TCP port. When it receives a request, it creates a Java object and returns the object to the requester. You will find the J-Integra® bridging server in jintegra\examples\vb-ejb\oracle\PurchaseOrder\Client\java directory when you download J-Integra®.

Take a look at the J-Integra® Bridge source code.

Open a DOS session and go to the java sub-folder. Setup your CLASSPATH environment variable. You must include jintegra.jar to your CLASSPATH. Also you must include the path to Oracle jar files in your CLASSPATH.
Run the following command to compile the J-Integra® bridging server:
```
javac COMtoOracle.java
```

Register a Listening JVM

The Visual Basic client invokes GetObject to get the Home object of the Purchase Order EJB. The first part of the parameter of this method identifies the server that can process the request. The name of this server is oraclejvm. In this step we register this server so when the Visual Basic client invokes GetObject, the operating system will find the server that is capable of responding to the request.

To register a J-Integra® bridging server, use the regjvm.exe tool, located in jintegra\bin folder. Go to that folder and run regjvm.exe.
Click New JVM and enter oraclejvm as the name of the new JVM. Click OK.
You can specify the host computer in which the J-Integra® bridging server will reside. Also you can specify the TCP/IP port which this server will listen to. The default host name is localhost and the default port is 1350.

Start J-Integra® bridging server

Now we are ready to launch the J-Integra® bridging server. Because this server is going to create different EJBs related to Purchase order objects, it must have access to the classes related to these EJBs. You must make sure that the PurchaseOrder, SKU, POQuery, and LineItems EJBs run on your system, which means you have to deploy them into your Application Server.

When you deployed these EJBs, you used makeit.bat command. Each makeit.bat command creates a few .jar files. We are interested in the .jar files that contain the Home and Remote interfaces of each EJB and their corresponding helper classes. The makeit.bat file puts these class files in a .jar file called common. The exact .jar file for the four EJBs used in this example are: common.jar for PurchaseOrder EJB, skucommon.jar for SKU EJB, pocommon.jar for POQuery EJB, and licommon.jar for LineItems EJB.

These .jar files are located in the root folder of each EJB. If your J-Integra® bridging server is running on the same computer as your Oracle Application Server, you just need to include the path to these jar files into your CLASSPATH environment. If the J-Integra® bridging server is riunning on a different machine, then you should copy these .jar files onto that machine and then include the path to them in your CLASSPATH.

Set the CLASSPATH to include the jintegra.jar, common.jar, pocommon.jar, skucommon.jar, licommon.jar, and Oracle's library files.
Start the J-Integra® bridging server by entering the following command (replace the username and password with appropriate values. The username and password correspond to a valid username/password on the database in which the PurchaseOrder EJB has been deployed):
```
java -DJINTEGRA_DCOM_PORT=1350 COMtoOracle username password
```

Run the VB Client

Before running the VB client make sure the Purchase Order example runs successfully. Also run the extra EJBs provided by this example to make sure they are also deployed correctly.

Go to the Purchase\vb sub-folder and double-click PurchaseOrder.exe. Upon loading the form, the VB client uses the default values for the host name, SID, and J-Integra® bridging server to connect to the Oracle Application Server. If the default values are not correct for your configuration, the VB client displays a message and disables all the action buttons. In this case, enter the correct values for the host name, SID, and J-Integra® bridging server and click Activate.
Select an item from the SKU list, enter an amount and click Add. Add more items to the current purchase order.

You can remove an item from the list by selecting it from the Purchase Order list and then clicking Remove.

You can also modify a line item by selecting it and then choosing a different item on the SKU list, and/or changing the amount and then clicking Update.
When you finished a purchase order, click Submit to submit the purchase order. The VB client creates a new PurchaseOrder EJB object and updates the pos table. If the update was successfull, the VB client will display a message.
To perform a query against the Purchase Order table, click Query. The VB Client will display the Query form.
If you are looking for a specifc purchase order and/or a apurchase order with a specific status, enter the purchase order and/or select the status and then click Query. If you do not specify any purchase order or status, the VB client displays all Purchase Order records in the pos table.
Select an item from the Purchase Order list. The VB client will display all items included in that purchase order.