4 Calling into a COM Application from WebLogic Server

This chapter describes how to prepare and deploy a WLS-to-COM application: an application that uses WebLogic jCOM to call methods on a COM object from WebLogic Server.

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 Requirements for Native Mode

Note these two special requirements for WLS-to-COM applications that use native mode:

  • In order for a COM application to run in native mode, WebLogic Server must be installed on the COM application machine.

  • In order to run in native mode, WebLogic Server must be running on a Windows machine.

Calling a COM Application from WebLogic Server: Main Steps

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

On the COM side:

  1. Code the COM application. See Code the COM Application.

  2. Generate Java classes from the COM objects with the com2java tool. See Generate Java Classes with the com2java GUI Tool.

  3. Package the classes for use by WebLogic Server. See Package the Java Classes for WebLogic Server.

  4. Start the COM application. See Start the COM Application.

On the WebLogic Server side:

  1. Enable COM calls on the server listen port. See Enable jCOM in the Oracle WebLogic Server Administration Console Online Help.
  2. Configure any other relevant console properties. See Servers: Protocols: jCOM in the Oracle WebLogic Server Administration Console Online Help.

    If you have chosen to have WebLogic Server and the COM application communicate in native mode, enable it in the WebLogic Server Administration Console. See the DCOM Versus Native Mode for help deciding whether to use native mode.

  3. Use the COM objects as you would any other Java object.

Preparing the COM Application

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

Code the COM Application

Code your COM application as desired.

Generate Java Classes with the com2java GUI Tool

Running the com2java GUI tool against a COM type library generates a collection of Java class files corresponding to the classes and interfaces in the COM type library.

Here we demonstrate Java class generation with the GUI tool. To read more about the WebLogic jCOM tools in general, see A Closer Look at the jCOM Tools.

  1. To run the com2java GUI tool, perform the following steps:

    1. Change to the WEBLOGIC_HOME/server/bin directory (or add this directory to your CLASSPATH)

    2. Open a command shell on the COM machine and invoke the com2java.exe file:

      > com2java
  2. Select the appropriate type library in the top field, and fill in the Java package text box with the name of the package to contain the generated files. The com2java tool remembers the last package name you specified for a particular type library.

  3. Click Generate Proxies to generate Java class files.

Package the Java Classes for WebLogic Server

If you call a COM object from an EJB, you must package the class files generated by com2java into your EJB .jar in order for WebLogic Server to find them. Place the generated files in a specific package. For example you may want to put all the files for the Excel type library in a Java package called excel.

For more information on packaging EJB .jar files, see Implementing EJBs in Developing Enterprise JavaBeans, Version 2.1, for Oracle WebLogic Server.

Start the COM Application

Once you have generated the Java class files and packaged them appropriately, simply start your COM application, so that the COM objects you want to expose to WebLogic Server are instantiated and running.

Using Java Classes Generated by com2java

For each COM class that the com2java tool finds in a type library, it generates a Java class which you use to access the COM class. These generated Java classes have several constructors:

  • The default constructor, which creates an instance of the COM class on the local host, with no authentication

  • A second constructor, which creates an instance of the COM class on a specific host, with no authentication

  • A third constructor, which creates an instance of the COM class on the local host, with specific authentication

  • A fourth constructor, which creates an instance of the COM class on a specified host, with specific authentication

  • A final constructor, which can wrap a returned object reference which is known to reference an instance of the COM class

Here are sample constructors generated from the DataLabelProxy class:

public DataLabelProxy() {} 

public DataLabelProxy(Object obj) throws java.io.IOException {
super(obj, DataLabel.IID); 
} 
protected DataLabelProxy(Object obj, String iid) throws
java.io.IOException 
{
super(obj, iid);
} 
public DataLabelProxy(String CLSID, String host, boolean
deferred) throws java.net.UnknownHostException,
java.io.IOException{ super(CLSID, DataLabel.IID, host, null); 
} 
protected DataLabelProxy(String CLSID, String iid, String host,
AuthInfo authInfo) throws java.io.IOException { super(CLSID,
iid, host, authInfo); 
} 

Using Java Interfaces Generated from COM interfaces by com2java

A method in a COM interface may return a reference to an object through a specific interface.

For example the Excel type library (Excel8.olb) defines the _Application COM Interface, with the method Add which is defined like this in COM IDL:

[id(0x0000023c), propget, helpcontext(0x0001023c)] 
HRESULT Workbooks([out, retval] Workbooks** RHS); 

The method returns a reference to an object that implements the Workbooks COM interface. Because the Workbooks interface is defined in the same type library as the _Application interface, the com2java tool generates the following method in the _Application Java interface it creates:

/** * getWorkbooks. 
* 
* @return return value. An reference to a Workbooks 
* @exception java.io.IOException If there are communications problems. 
* @exception com.bea.jcom.AutomationException If the remote server throws an exception. */ 
public Workbooks getWorkbooks () throws java.io.IOException, com.bea.jcom.AutomationException;
It is revealing to look at the implementation of the method in the generated _ApplicationProxy Java class:
/** 
* getWorkbooks. 
* 
* @return return value. An reference to a Workbooks 
* @exception java.io.IOException If there are communications 
problems. 
* @exception com.bea.jcom.AutomationException If the remote 
server throws an exception. 
*/ 
public Workbooks getWorkbooks () throws java.io.IOException, 
com.bea.jcom.AutomationException{ com.bea.jcom.MarshalStream 
marshalStream = newMarshalStream("getWorkbooks"); 
marshalStream = invoke("getWorkbooks", 52, marshalStream); 
Object res = marshalStream.readDISPATCH("return value"); 
Workbooks returnValue = res == null ? null : new 
WorkbooksProxy(res); 
checkException(marshalStream, 
marshalStream.readERROR("HRESULT")); 
return returnValue;
}

As you can see, the getWorkbooks method internally uses the generated WorkbooksProxy Java class. As mentioned above, the com2java tool generates the method with the Workbooks return type because the Workbooks interface is defined in the same type library as _Application.

If the Workbooks interface were defined in a different type library, WebLogic jCOM would have generated the following code:

/** 
* getWorkbooks. 
* 
* @return return value. An reference to a Workbooks 
* @exception java.io.IOException If there are communications 
problems. 
* @exception com.bea.jcom.AutomationException If the remote server 
throws an exception. 
*/ 
public Object getWorkbooks () throws java.io.IOException, 
com.bea.jcom.AutomationException;
In this case, you would have to explicitly use the generated proxy class to access the returned Workbooks:
Object wbksObj = app.getWorkbooks(); 
Workbooks workbooks = new WorkbooksProxy(wbObj);