Skip Headers
Oracle® Fusion Middleware Programming JCOM for Oracle WebLogic Server
12c Release 1 (12.1.1)

Part Number E24379-01
Go to Documentation Home
Home
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

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

This chapter includes the following sections:

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.

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 Language (IDL) file and compile the files. See Generate Java Wrappers and the IDL File—Early Binding Only.

  2. Enable COM calls on the server listen port. See Enable jCOM in the Oracle WebLogic Server Administration Console Help.

  3. Grant access to server classes to COM clients. See Configuring Access Control.

  4. Configure any other relevant console properties. See Servers: Protocols: jCOM in the Oracle WebLogic Server Administration Console Help.

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:

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

    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 (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_12.1 by default).

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

    java com.bea.java2com.Main
    

    The java2com GUI is displayed:

    Surrounding text describes java2comdefault.gif.
  3. 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 > ''''
    
    Surrounding text describes com_names.gif.
  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.

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

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

  2. In the right-hand pane, enter:

    java.util.*
    
  3. Click Define Security 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.

  6. Click Add.

  7. Click OK.

  8. In the bottom right-hand corner of the window, click Apply.

Granting Access to ejb20.basic.beanManaged

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

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:

  • 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 Chapter 5, "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.

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

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

The WebLogic Server JVM is registered in the client machine registry through 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 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 the java2com tool. 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.

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

    Surrounding text describes regjvm_dcom.gif.
  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, unregister the old entry, and then create a new one.

Surrounding text describes regjvm_dcom.gif.

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.

Dim mobjHome As Object 
Private Sub Form_Load()
'Handle errors 
On Error GoTo ErrOut '
Bind the EJB AccountHome object through 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":

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. 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 Chapter 5, "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:\Oracle\Middleware\jdk160 by default, and WebLogic Server is installed in c:\Oracle\Middleware\wlserver_12.1\server\lib\weblogic.jar, and your Java classes are in c:\pure, you would complete the regjvm tools screen as follows:

Surrounding text describes regjvm7.gif.

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 Chapter 5, "A Closer Look at the jCOM Tools."