Early Bound Example:

Visual Basic to WebLogic EJB

This example demonstrates how to access an EJB deployed on WebLogic Server from a Visual Basic client using early binding.

There are two ways of accessing COM objects from Visual Basic: early bound, and late bound access. Early bound access provides you with information about the object you are accessing while you are building your program. This is useful when trying to debug clients. It is also faster when running your program to use early bound access. However, early binding is complex to implement as it requires the generation of wrappers and a type library, and the manual placement of these generated files on the correct machine.

This example is based on the WebLogic Enterprise JavaBean container-managed persistence example, which is included in the standard WebLogic kit. For more information on this WebLogic Enterprise JavaBean example see the samples\examples\ejb20\basic\containerManaged\package-summary.html file located under the WebLogic installation. This example assumes you have previously successfully run the WebLogic container-managed example.

The container-managed persistence example has a Java client which accesses a bank account and performs account transactions. In this WebLogic jCOM example, a VB client is created which simulates the container-managed persistence client example. The EJB itself remains unchanged, and has no knowledge that it is being accessed as a COM object.

The following sections describe how to build and run this example:

• Prerequisites
• Steps to Build and Run this Example

Prerequisites

In this example, the server can run on a Java™ 2 Platform, Enterprise Edition 1.3. The COM client must run on a Microsoft Windows platform.

This example requires that the following be installed:

On the WebLogic Server machine:

• WLS 7.0

On the Windows VB client machine (which may be the same as the server machine):

• VB 6.0
• WebLogic jCOM 7.0 tools
• midl (Microsoft IDL Compiler and its dependencies)

To load the tools on your client machine, copy them from the WL_HOME\bin directory on the WLS server machine.

This example and all the pre-made files referred to can be found (assuming you have installed WLS to the default directory) in the installed WebLogic Examples jCOM directory under SAMPLES_HOME\server\src\examples\jcom.

Steps to Build and Run this Example

The following steps are required to implement early-bound COM-to-Java communication:

1. Generate the Wrappers and Type Library
2. Edit the startExamplesServer Script
3. Start the WebLogic Examples Server
4. Verify the WebLogic Examples Server Configuration
5. Register the Examples Server JVM in the Client Machine's Registry
6. Create or Modify the VB Client Source Code
7. Run the VB Client Example

Generate the Wrappers and Type Library

On the Server Machine

Perform these steps on the server machine:

1. Set the examples environment by running the setExamplesEnv script:

cd SAMPLES_HOME\server\config\examples

setExamplesEnv

Here we are setting the environment variables that point to the root WLS directory and the root JDK directory.

2. Change to the SAMPLES_HOME\server\src\examples\jcom\earlybound directory in preparation for running a series of ant commands:

cd SAMPLES_HOME\server\src\examples\jcom\earlybound

3. Run the ant init command to clean out old directories and files and create the necessary directories:

ant init

4. Compile the jCOM helper class, which contains a method to narrow an object obtained from WebLogic Server to a local object:

ant compile.helper

5. Generate java wrappers and an IDL file with the java2com tool:

ant java2com

The java2com GUI is displayed:

In the Java Classes & Interfaces field, you must enter the names of the classes you want to use.






Note:  Pregenerated java classes have been provided in the TLB_pregenerated directory.

6. Input the following:

Java Classes & Interfaces: JCOMHelper examples.ejb20.basic.containerManaged.AccountHome
Name of generated IDL File: containerManagedTLB
Output Directory: (drive letter and root directory of this sample)\TLB\

The java2com tool looks at the class we specify, and at all other classes that it uses in the method parameters. It does this recursively. You can specify more than one class or interface here, separated by spaces.

All Java classes that are public, not abstract, and have a no-parameter constructor are rendered accessible as COM Classes. Other public classes, and all public interfaces are rendered accessible as COM interfaces.

If you were to click the "Generate" button and produce wrappers and the IDL at this point, you would encounter errors when you attempted to compile the generated wrappers and IDL. This is because certain classes are omitted by default in the java2com tool. By looking at the errors generated during compilation, you would be able to determine which classes were causing problems.



To fix the problem, click on the "Names …" button in the java2com tool and remove any references to the class files you require. In this example we must remove the following references:

*.toString->''''
class java.lang.Class->''''



Once these references have been removed, you can generate your wrappers and IDL.

Note: You must do this manually; the batch file cannot do this for you.

7. Compile the java wrapper files:

   ant compile.wrappers

The java2com tool generates Java classes containing DCOM marshalling code used to access Java objects. These generated classes are used behind the scenes by the WebLogic jCOM runtime. You simply need to compile them and make sure that they are in your server's CLASSPATH. If you change the CLASSPATH contents, restart the server, as the server only knows what's in its CLASSPATH at boot time. It is not sufficient to put the classes in the EJB .jar file (or webapp file); they must be in the CLASSPATH.

Note:  To compile the pregenerated java wrappers located in the TLB_pregenerated directory, use the ant compile.pregen.wrappers ant target.

On the Client Machine

Perform these steps on the client machine (note that the steps vary depending on whether the COM client and WebLogic Server are running on the same machine):

1. Copy the IDL to the client machine:

If the java2com tool was successfully executed above, an IDL file will have been produced on the server machine. Copy this IDL file to the client machine, and place it in this example's \TLB subdirectory.

Note: If you are running the client and the server on the same machine this step is not necessary, since the java2com tool should already output to the sample's \TLB subdirectory (we specified it as the java2com output directory above).

2. Compile the IDL file into a type library:

Here is the syntax if your client machine is also running WebLogic Server:

cd SAMPLES_HOME\server\src\examples\jcom\earlybound

ant compile.idl

Here is the syntax if WebLogic Server is not running on the client machine:

midl .\containerManagedTLB.idl

We call the Microsoft IDL compiler MIDL.EXE to carry out the compilation. The result of the compilation is a type library called containerManagedTLB.tlb.

Note:  A precompiled containerManagedTLB.tlb type library has been provided in the TLB_pregenerated directory.

3. Register the type library and set the JVM it will service:

   Here is the syntax if your client machine is also running WebLogic Server:

   cd SAMPLES_HOME\server\src\examples\jcom\earlybound

   ant reg.tlb

   This unregisters all type libraries and then re-registers them.

   Here is the syntax if WebLogic Server is not running on the client machine:

   .\regtlb /unregisterall
   .\regtlb containerManagedTLB.tlb examplesServer

The first line above calls the regtlb.exe in order to un-register any previously registered type library versions. The second line then registers the newly compiled type library.

The second parameter "examplesServer" passed to regtlb is important. "examplesServer" specifies the name of the JVM that will be linked with the type library. The WebLogic jCOM runtime requires this information for linking type library defined object calls to the appropriate wrapper classes.

The examplesServer is registered in the client machine registry via the regjvm tool. See Register the Examples Server JVM in the Client Machine's Registry for details.

Notes:

• In general, wrapper files must be placed on the server and compiled. The IDL file must be placed on the client and compiled. If you are running the server and client on separate machines, and you created the wrappers and IDL on the client side, you will have to distribute the wrapper files you have just compiled to the server. If you created the wrappers and IDL on the server side, then you must move the IDL file to the client, where it can be compiled to a type library.



• The wrapper files and IDL file must be created by a single execution of the java2com tool. If you attempt to run the java2com tool separately on both the server and the client, the wrappers and IDL file you create will not be able to communicate. The IDL and wrappers have unique stamps on them for identification; wrappers can only communicate with IDL files created by a common invocation of the java2com tool, and vice versa. As a result, the java2com tool must be run once, and the files it creates distributed afterward. If you make a mistake or a change in your Java source code and you need to run the java2com tool again, you must delete all of your wrapper files, your IDL file, and your TLB file, and redo all the steps.



• When using the java2com tool to create wrappers for classes that contain (or reference) deprecated methods, you will see deprecation warnings at compile time. These warnings can be disregarded; WebLogic jCOM will render the methods accessible from COM nevertheless.

Edit the startExamplesServer Script

The startExamplesServer script is located in SAMPLES_HOME/server/config/examples. Edit the script to add the following jars to the server CLASSPATH:
   %CLIENT_CLASSES%\jcom_earlybound.jar
   %CLIENT_CLASSES%\ejb20_basic_containerManaged_client.jar

Start the WebLogic Examples Server

Start the WebLogic Examples Server. Click these links for details on starting the server on a Windows Machine, or on a UNIX Machine.

Verify the WebLogic Examples Server Configuration

Verify that the WebLogic Examples Server is configured properly to run this example.

Verify that the Container-Managed Persistence Example Is Deployed

In the lefthand pane of the WebLogic Server Console, click Deployments and then EJB.

"ejb20.basic.containerManaged" should be one of the bullet items displayed.

Verify that the Container-Managed Persistence Example Is Targeted to the Examples Server

1. In the lefthand pane of the WebLogic Server Console, click Deployments and then EJB.
2. Click "ejb20_basic_containerManaged.
3. In the righthand pane, select the "Targets" tab.

Verify that "examplesServer" is listed under "Chosen".

Verify that the Server Port is Listening for COM Calls

1. In the lefthand pane of the WebLogic Server Console, click Servers and then exampleServer.
2. In the right hand pane, select the jCOM tab.

The "COMEnabled" box should be checked. If not, do so now.

Verify that the Security Settings Are Correct

In this section, you verify that access is granted to the WebLogic Server classes that the COM client application needs to access.

For this example, the COM client needs access to the following four classes:

• java.util.Collection
• java.util.Iterator
• JCOMHelper
• ejb20.basic.containerManaged

Verifying Access to java.util.Collection and java.util.Iterator

1. In the lefthand pane of the WebLogic Server Console, click the Services node and then click the JCOM node underneath it.
2. In the righthand pane, enter the following:

java.util.*

3. Click Define Policy.
4. Verify that the Policy Statement box contains the statement "Caller is a member of the group everyone".

If the statement is there, access to java.util.Collection and java.util.Iterator is granted to everyone; your COM client application can successfully access these classes.

5. If the Policy Statement box does not contain this statement, you must add it.

To do that:

1. In the Policy Condition box, double-click "Caller is a member of the group".
2. In the box that is displayed, enter "everyone" in the "Enter group name:" field.
3. Click Add.
4. Click OK.
5. In the bottom righthand corner of the window, click Apply.

Verifying Access to JCOMHelper

1. In the lefthand pane of the WebLogic Server Console, click the Services node and then click the JCOM node underneath it.
2. In the righthand pane, enter the following:

JCOMHelper

3. Click Define Policy.
4. Verify that the Policy Statement box contains the statement "Caller is a member of the group everyone".

If the statement is there, access to the JCOMHelper class is granted to everyone; your COM client application can successfully access this class.

5. If the Policy Statement box does not contain this statement, you must add it.

To do that:

1. In the Policy Condition box, double-click "Caller is a member of the group".
2. In the box that is displayed, enter "everyone" in the "Enter group name:" field.
3. Click Add.
4. Click OK.
5. In the bottom righthand corner of the window, click Apply.

Verifying Access to ejb20.basic.containerManaged

1. In the lefthand pane of the WebLogic Server Console, click the Services node and then click the JCOM node underneath it.
2. In the righthand pane, enter the following:

ejb20.basic.containerManaged.*

3. Click Define Policy.
4. Verify that the Policy Statement box contains the statement "Caller is a member of the group everyone".

If the statement is there, access to the ejb20.basic.containerManaged.* package is granted to everyone; your COM client application can successfully access these classes.

5. If the Policy Statement box does not contain this statement, you must add it.

To do that:

1. In the Policy Condition box, double-click "Caller is a member of the group".
2. In the box that is displayed, enter "everyone" in the "Enter group name:" field.
3. Click Add.
4. Click OK.
5. In the bottom righthand corner of the window, click Apply.

Note that because of the final asterisk, you're granting access to the entire ejb20.basic.containerManaged package.

For more information on granting and revoking access to classes, point your web browser here:

http://edocs.bea.com/wls/docs70/ConsoleHelp/security_7x.html

Register the Examples Server JVM in the Client Machine's Registry

On the client machine, register with the local Java Virtual Machine by adding the name "examplesServer" to the Windows registry and associating it with the TCP/IP address and client-to-server communications port where WebLogic will listen for incoming COM requests. By default, this is localhost:7001.

regjvmcmd examplesServer localhost[7001]

If the Examples Server is running on something other than localhost and listening on a port other than 7001, then pass that hostname (or IP address) and port number to regjvmcmd.

Note: The regjvmcmd.exe tool does not overwrite old entries when new entries with identical names are entered. This means that if you ever need to change the hostname or port of the machine with which you wish to communicate, you have to unregister the old entry. You can do this using the command line tool regjvmcmd.exe, or by using the GUI tool regjvm.exe. To use the command line tool, simply execute this statement:

regjvmcmd /unregister examplesServer

This will unregister the JVM ejb so that it can later be re-registered with a new destination hostname and port. If you prefer to work in a graphical environment, execute the regjvm.exe file.

If you haven't already loaded the regjvmcmd.exe and the regjvm.exe tools on your client machine, you can find them in the WL_HOME\bin directory on your WLS server machine.

Create or Modify the VB Client Source Code

On the client machine, load the VB source code, containerManaged.vbp. In the Projects menu, select References.

Scroll down until you find "containerManagedTLB" and activate its check box. Click OK. If this entry isn't there then the type library has not been registered using the WebLogic jCOM regtlb command as described as above.

The most obvious difference between this example and the late bound example is that there are fewer variables declared As Object. Objects can now be declared by using the type library:

Dim mobjHome As containerManagedTLB.ExamplesEjb20BasicContainerManagedAccountHome

Advantages are gained by having design time information about the various methods and properties of the objects. For this to work, the following is also required:

Notice the objTemp object using a late bound method to obtain a reference to the containerManaged example's AccountHome object. This late bound object is passed to the bridge's "narrow" method, and is given an early bound object in return.

The rest of the example source is identical to that of the late bound example, with the notable exception of object declaration. As mentioned above, objects are no longer declared As Object, but rather the type library is used to cast them in to their early bound form. For example, an Account object:

Run the VB Client

To access the EJB from Visual Basic:

1. Press F5 to run the sample.
2. Enter an "Account Name" and an "Amount" and click "Create". You can then deposit and withdraw from the newly created account, remove the account, or create more accounts.

Error messages will be displayed in the light-gray textbox at the bottom of the form. You will be notified when the example starts if there have been any problems connecting with the WebLogic Server EJB.