Programming WebLogic jCOM

Calling into WebLogic Server from a COM Client Application

This chapter describes how to use WebLogic jCOM to call methods on a WebLogic Server object from a COM client.

• Special Requirement for Native Mode

• Calling WebLogic Server from a COM Client: Main Steps

• Preparing WebLogic Server

• Preparing the COM Client

• Running COM-to-WLS Applications in Native Mode

Special Requirement for Native Mode

Note that WebLogic Server must be installed on COM client machines in order for your COM-to-WLS application to run in native mode. However, this does not mean you need a distinct WebLogic Server license for each machine running a COM client.

For more information on native mode, see Running COM-to-WLS Applications in Native Mode

Calling WebLogic Server from a COM Client: Main Steps

This section summarizes the main steps to call into WebLogic Server from a COM client. Most are described in detail in later sections.

On the WebLogic Server side:

1. If you are using early binding, run the java2com tool to generate Java wrapper classes and an Interface Definition Libarry (IDL) file and compile the files. See Generate Java Wrappers and the IDL File—Early Binding Only.

2. Start the server. See Start the Server.

3. Enable COM calls on the server listen port. See Enable COM Calls on the Server Listen Port.

4. Grant access to server classes to COM clients. See Configure Access Control.

5. Configure any other relevant console properties. See Configure Other Console Properties.

6. Restart the server if you have changed the value of any static console properties, in order for the new values to take effect.

On the COM client side:

1. Install the jCOM tools files and, for native mode only, Weblogic Server class files. See Install Necessary Files.

2. If this is a zero-client installation:

   • Obtain an object reference moniker (ORM) from the WebLogic Server ORM servlet, either progammatically or by pasting into your application. See Obtain an Object Reference Moniker from the WebLogic Server Servlet—Zero Client Only.

3. If you are using early binding:

   • Obtain the IDL file generated on the WebLogic Server machine and compile it into a type library.

   • Register the type library and the WebLogic Server it will service.

   For both of these steps, see Generate Java Wrappers and the IDL File—Early Binding Only.

4. Register the WebLogic Server JVM in the registry. If want to communicate with the WebLogic Server in native mode, set that in this step. See Register the WebLogic Server JVM in the Client Machine Registry.

5. Code the COM client application. See Code the COM Client Application.

6. Start the COM client. See Start the COM Client.

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

1. 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 (typically c:\bea\jdk131) and WL_HOME is the root directory where WebLogic Platform software is installed (typically c:\bea\weblogic700).

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

   java com.bea.java2com.Main

The java2com GUI is displayed:

3. Input the following:

   Java Classes & Interfaces: jCOMHelper examples.ejb20.basic.containerManaged.AccountHome [list the wrapper classes to be converted here]
   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, you will 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->''''

   
    

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

Start the Server

Start WebLogic Server. See "Starting and Stopping WebLogic Servers".

Enable COM Calls on the Server Listen Port

While jCOM is installed automatically when you install WebLogic Server, you must enable it, which tells the server to listen for COM calls on its listen port:

1. Bring up the WebLogic Server Administration Console.

2. In the lefthand pane, click the name of the server

3. Display the jCOM properties screen by clicking the Connections tab and then the jCOM tab—both in the righthand pane.

4. Check the "COM Enabled" box.

5. Restart the server to make the setting take effect. If you are planning to set any jCOM properties via the Console, do so before restarting the server. (See Configure Other Console Properties.)

Configure Access Control

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

See the Zero Client example shipped with this release at WL_HOME/samples/server/src/examples/jcom/zeroclient.

In the Zero Client example, 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

1. In the lefthand pane of the WebLogic Server Administration Console, click the Services node and then click the JCOM node underneath it.

2. In the righthand pane, enter:

   java.util.*

3. Click Define Policy.

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

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

Note: The zeroclient example gives access to "everyone"; however, it is preferable to be as restrictive as possible when granting access.

6. Click Add.

7. Click OK.

8. In the bottom righthand corner of the window, click Apply.

Granting Access to ejb20.basic.beanManaged

The zeroclient example also requires access to the ejb20.basic.beanManaged class.

To accomplish this, repeat the steps in Granting Access to java.util.Collection and java.util.Iterator,replacing "java.util.*" with "ejb20.basic.beanManaged.*" in step 3.

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

For more information on granting and revoking access to classes, point your web browser to the 7.x Security section of the Console online help.

Configure Other Console Properties

Configure any other jCOM console properties that you require. For details, see the Console online help for the jCOM properties.

If any of these properties require a server restart to take effect restart the server now.

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. You will find them in the WL_HOME\server\bin directory on the machine where you installed WebLogic Server. They are:

• JintMk.dll

• ntvinv.dll

• regjvm.exe

• regjvmcmd.exe

• regtlb.exe

• regjvm (including all subfolders and files)

• regjvmcmd (including all subfolders and files)

• regtlb (including all subfolders and files)

For more information on the jCOM tools, see A Closer Look at the jCOM Tools.

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. However, this does not mean you need a distinct WebLogic Server license for each 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 will remain 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 via 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 be used to access WebLogic Server on the machine and port you have specified.

Generate Java Wrappers and the IDL File—Early Binding Only

Perform the client-side portion of the wrapper and Interface Definition Language (IDL) file generation:

1. Copy the IDL to the client machine:

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

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

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

   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 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 WebLogic Server JVM is registered in the client machine registry via the regjvm tool. For details, see Register the WebLogic Server JVM in the Client Machine Registry.

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 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 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 WebLogic will listen for incoming COM requests. By default, this is localhost:7001.

1. Invoke the regjvm GUI tool, which displays this screen.

   
    

2. 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:

   regjvmcmd servername localhost[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, you have to 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.

The code snippets in this section are taken from the Early Bound and Late Bound examples shipped with this product and available in SAMPLES_HOME\server\src\examples\jcom.

Late Bound Applications

In this extract from the Late Bound example, a 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.

Dim mobjHome As Object 

Private Sub Form_Load()

'Handle errors 

On Error GoTo ErrOut '

Bind the EJB AccountHome object via JNDI 

Set mobjHome = CreateObject("examplesServer:jndi:ejb20-containerManaged-AccountHome")

Known Problem and Workaround for Late Bound Clients

WebLogic jCOM has problems handling methods that are overloaded but have the same number of parameters. There is no such problem if the number of parameters in the overloaded methods are different.

When they're the same, calls fail.

Unfortunately, the method InitialContext.lookup is overloaded:

public Object lookup(String) 

public Object lookup(javax.naming.Name) 

To perform a lookup, you must use the special JNDI moniker to create an object:

Set o = CreateObject("servername:jndi:objectname") 

Early Bound Applications

The most obvious distinguishing feature of early bound code is that fewer variables are declared As Object. Objects can now be declared by using the type library you generated previously:

Declare objects using the type library generated in Generate Java Wrappers and the IDL File—Early Binding Only. In this Visual Basic code fragment, the IDL file is called containerManagedTLB and the EJB is called ExamplesEjb20BasicContainerManagedAccountHome:

Dim objNarrow As New containerManagedTLB.JCOMHelper

Now, you can call a method on the object:

Set mobjHome = objNarrow.narrow(objTemp, "examples.ejb20.basic.containerManaged.AccountHome")

Start the COM Client

Start up the COM client application.

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; interprocess 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:

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

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 JVM id box.

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

For detailed information on the regjvm tool, see A Closer Look at the jCOM Tools.

3. Insert the following code into the main section of your application code, to tell the WebLogic jCOM runtime that the JVM is ready to receive calls:

   com.bea.jcom.Jvm.register("MyJvm"):

   public class MyJvm {

   public static void main(String[] args) throws Exception {

   // Register the JVM with the name "firstjvm"

   com.bea.jcom.Jvm.register("firstjvm");

   Thread.sleep(6000000); // Sleep for an hour

   }

4. From Visual Basic you can now use late binding to instantiate instances of any Java class that can be loaded in that JVM:

   Set acctEJB = CreateObject("firstjvm.jndi.ejb20.beanManaged.AccountHome")

5. 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:\bea\jdk131 and WebLogic Server is installed in c:\bea\weblogic700\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:

MessageBox GetObject("MyJVM.jndi.ejb20.beanManaged.AccountHome")

For detailed information on the regjvm tool, see A Closer Look at the jCOM Tools.