Preparing WebLogic Server

The following sections discuss how to prepare WebLogic Server so that COM clients can call methods on WebLogic Server objects:

Generate Java Wrappers and the IDL File—Early Binding Only

Add the path to JDK libraries and weblogic.jar to your CLASSPATH. For example:

set CLASSPATH=%JAVA_HOME%\lib\tools.jar;
%WL_HOME%\server\lib\weblogic.jar;%CLASSPATH%

Where JAVA_HOME is the root folder where the JDK is installed (c:\Oracle\Middleware\jdk160 or c:\Oracle\Middleware\jrockit_160 by default) and WL_HOME is the root directory where WebLogic Platform software is installed (c:\Oracle\Middleware\wlserver_10.3 by default).

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

java com.bea.java2com.Main

The java2com GUI is displayed:

Input the following:

Java Classes & Interfaces: list of the wrapper classes to be converted

Name of generated IDL File: name of the IDL file

Output Directory: drive letter and root directory\TLB

where TLB signifies OLE Type Library.

The java2com tool looks at the class specified, 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 click the "Generate" button and produce wrappers and the IDL at this point, errors are generated. 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 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. Click Generate in the java2com GUI.

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 CLASSPATH.

Configuring Access Control

Grant the COM client user access to the classes that the COM client application needs to access. Your particular application dictates which classes to expose.

For example, assume that the COM client needs access to the following three classes:

java.util.Collection

java.util.Iterator

ejb20.basic.beanManaged

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

In the left-hand pane of the WebLogic Server Administration Console, click the Services node and then click the JCOM node underneath it.

In the right-hand pane, enter:

java.util.*

Click Define Security Policy.

In the Policy Condition box, double-click "Caller is a member of the group".

In the "Enter group name:" field, enter the name of the group of users to whom you're granting access.

Granting Access to ejb20.basic.beanManaged

Preparing the COM Client

The following sections describe how to prepare a COM client to call methods on WebLogic Server objects:

Install Necessary Files

There are a number of files that must be installed on your client machine in order to call methods on WebLogic Server objects. As noted below, some of these are only necessary if you are making method calls in native mode.

jCOM Tools Files

There are five files and three folders (including all subfolders and files) necessary for running the jCOM tools. These tools are located in the WL_HOME\server\bin directory on the machine where you installed WebLogic Server. They are:

WebLogic Server Class Files—Native Mode Only

In order to run a COM-to-WLS application in native mode, a COM client machine must have access to certain WebLogic Server class files. To obtain these files, install WebLogic Server on each COM client machine.

Obtain an Object Reference Moniker from the WebLogic Server Servlet—Zero Client Only

You can obtain an object reference moniker (ORM) from WebLogic Server. The moniker can be used from the COM client application, obviating the need to run regjvmcmd. The moniker remains valid for new incarnations of the server as long as the host and port of the server remain the same.

There are two ways to obtain an ORM for your COM client code:

Obtain it through a servlet running on WebLogic Server. Open a Web browser on WebLogic Server to http://[wlshost]:[wlsport]/bea_wls_internal/com

where wlshost is the WebLogic Server machine and wlsport is the server's port number.

Run the com.bea.jcom.GetJvmMoniker Java class, specifying as parameters the full name or TCP/IP address of the WebLogic Server machine and port number:

java com.bea.jcom.GetJvmMoniker [wlshost] [wlsport]

A long message is displayed which shows the objref moniker and explains how to use it. The text displayed is also automatically copied to the clipboard, so it can be pasted directly into your source. The objref moniker returned can access the WebLogic Server instance on the machine and port you have specified.

Generate Java Wrappers and the IDL File—Early Binding Only

If the java2com tool successfully executes on the WebLogic Server machine (see Preparing WebLogic Server), an IDL file is produced on the server machine. Copy this IDL file to the client machine, and place it in this COM application's \TLB subdirectory.

Note:

If the client and the server are on the same machine, this step is not necessary. The java2com tool outputs to the sample's \TLB subdirectory.

Compile the IDL file into a type library:

midl containerManagedTLB.idl

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

Register the type library and set the JVM it services:

regtlb /unregisterall
regtlb containerManagedTLB.tlb registered_jvm

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 registered_jvm passed to regtlb is important. It specifies the name of the JVM linked with the type library. The WebLogic jCOM runtime requires this information for linking type library defined object calls to the appropriate wrapper classes.

Some Notes about Wrapper Files

In general, wrapper files must be placed on the server and compiled. The IDL file must be placed on the client and compiled. If the server and client are on separate machines, and you created the wrappers and IDL on the client side, you must 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 thejava2comtool. If you attempt to run the java2com tool separately on both the server and the client, the wrappers and IDL file created would 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 you use the java2com tool to create wrappers for classes that contain (or reference) deprecated methods, you see deprecation warnings at compile time. disregard these warnings; WebLogic jCOM renders the methods accessible from COM.

The generated wrapper classes must be in your CLASSPATH. They cannot be just located in your EJB jar.

Register the WebLogic Server JVM in the Client Machine Registry

Register with the local Java Virtual Machine by adding the server name to the Windows registry and associating it with the TCP/IP address and client-to-server communications port where the WebLogic Server instance listens for incoming COM requests. By default, this is localhost:7001.

Invoke the regjvm GUI tool, which displays this screen.

If WebLogic Server is running on something other than localhost and listening on a port other than 7001, then fill in the hostname (or IP address) and port number

If you prefer, use the command-line version of regjvm:

regjvmcmdservernamelocalhost[7001]

Unregistering JVMs

The regjvm (or regjvmcmd) 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, unregister the old entry, and then create a new one.

To unregister a JVM in the regjvm tool window, select the JVM you wish to unregister and click Delete.

Alternatively, unregister the JVM with the command line tool regjvmcmd:

regjvmcmd /unregister servername

Select Native Mode, If Applicable

If your COM client is running in native mode, check the "Native Mode" or "Native Mode Out-of-Process" radio button in the regjvm window or invoke regjvmcmd with the /native parameter. For details on this step, see Running COM-to-WLS Applications in Native Mode.

Code the COM Client Application

You can now invoke methods on the WebLogic Server objects. How you code this naturally depends on whether you chose late binding or early binding.

Late Bound Applications

In the following sample Visual Basic Application, notice the declaration of the COM version of the Account EJB's home interface mobjHome. This COM object is linked to an instance of the AccountHome interface on the server side.

Start the COM Client

Running COM-to-WLS Applications in Native Mode

For COM-to-WLS applications, there's a distinction in native mode between "in-process" and "out-of-process":

Out-of-process: The JVM is created in its own process; inter-process communication occurs between the COM process and the WebLogic Server JVM process.

In-process: The entire WebLogic Server JVM is brought into the COM process; in effect, it's loaded into the address space of the COM client. The WebLogic Server client-side classes reside inside this JVM.

You determine which process your application uses by selecting the native-mode-in-process or native mode radio button in the regjvm GUI tool interface.

Native Mode with the JVM Running Out-of-Process

If you want your JVM to run out of process (but allow COM client access to the Java objects contained therein using native code), follow these steps:

Invoke the regjvm GUI tools to register your JVM as being native. The regjvm sets up various registry entries to facilitate WebLogic jCOM's COM-to-WLS mechanism. When you register the JVM you must provide the name of the server in the JVM id field. For example, if you enabled JCOM native mode on exampleServer then when you register with regjvm enter exampleServer in the JVM id box.

If your JVM is not already running, click the Advanced radio button and type its path in the "Launch Command" field.

Having registered the JVM, use the standard WebLogic jCOM regtlb command to allow early bound access to Java objects (regtlb takes as parameters the name of a type library, and a JVM name, and registers all the COM objects defined in that type library as being located in that JVM).

You can also control the instantiation of Java objects on behalf of COM clients by associating your own instantiator with a JVM (additional parameter to com.bea.jcom.Jvm.register(...))—a kind of object factory.

Native Mode with the JVM Running In-Process

Use this technique to actually load the JVM into the COM client's address space.

Again, use the regjvm command, but this time specify additional parameters.

Note:

When you register the JVM you must provide the name of the server in the JVM id field. For example, if you enabled JCOM native mode on exampleServer then when you register with regjvm enter exampleServer in the JV id box.

The simplest example would be to use Visual Basic to perform late bound access to Java objects. First register the JVM. If you are using Sun's JDK 1.3.1, which is installed under c:\Oracle\Middleware\jdk160 by default, and WebLogic Server is installed in c:\Oracle\Middleware\wlserver_10.3\server\lib\weblogic.jar, and your Java classes are in c:\pure, you would complete the regjvm tools screen as follows:

As you can see, you specify the JVM name, the CLASSPATH, and the JVM bin directory path.

From Visual Basic, you should now be able to call the GetObject method: