3 Calling into WebLogic Server from a COM Client Application
Note:
WebLogic jCOM is deprecated as of WebLogic Server 12.2.1.4.0. jCOM has been provided as a migration path for interim solutions that require Java-to-COM integration. Oracle believes that web services and REST are the preferred way to communicate with Microsoft applications. Oracle recommends that you migrate legacy COM applications to .NET in order to use this type of communication.
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.
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:
-
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. -
Enable COM calls on the server listen port. See Enable jCOM in the Oracle WebLogic Server Administration Console Online Help.
-
Grant access to server classes to COM clients. See Configuring Access Control.
-
Configure any other relevant console properties. See Servers: Protocols: jCOM in the Oracle WebLogic Server Administration Console Online Help.
On the COM client side:
Preparing WebLogic Server
The following sections discuss how to prepare WebLogic Server so that COM clients can call methods on WebLogic Server objects:
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 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)
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 andwlsport
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:
The WebLogic Server JVM is registered in the client machine registry through the regjvm
tool. 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 thejava2com
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 thejava2com
tool, and vice versa. As a result, thejava2com
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 thejava2com
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.
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.
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")
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:
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.
Assume that the classes you want the Visual Basic client to call are in the directory c:\pure
; the JDK you are using is in c:\jdk1.7.0_15
; and WebLogic Server is installed in c:\Oracle\Middleware
. 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.