4 Calling into a COM Application from WebLogic Server

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 Fusion Middleware Oracle WebLogic Server Administration Console Help.

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

   If you have chosen to have WebLogic Server and the COM application communicate in native mode, enable it in the Administration Console. See the Chapter 2, "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:

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 Chapter 5, "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 will remember the last package name you specified for a particular type library.

3. Click Generate Proxies to generate Java class files.

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 be used to 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 makes use of 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);