Programming WebLogic jCOM

Calling into a COM Application from WebLogic Server

The following sections describe 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.

• Special Requirements for Native Mode

• Calling a COM Application from WebLogic Server: Main Steps

• Preparing the COM Application

• Preparing 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. However, this does not mean you need a distinct WebLogic Server license for each 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. Start the server. See Start the Server.

2. Through the WebLogic Server Administration Console, enable and configure COM as desired. See Enable COM Calls on the Server Listen Port.

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 will remember 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. You will probably want to have 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 the chapter "Packaging EJBs for the WebLogic Server Container" in Programming WebLogic Enterprise JavaBeans.

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 instanciated and running.

Preparing WebLogic Server

The following sections describe how to prepare a WebLogic Server so it can call methods on a COM application's objects.

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 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 "Native Mode Enabled" or any other jCOM properties via the Console, do so before restarting the server.

Enable Native Mode, If Desired

If you have chosen to have WebLogic Server and the COM application communicate in native mode, enable it now, through the WebLogic Server console. See the DCOM Versus Native Mode in Overview of WebLogic jCOM,for help deciding whether to use native mode.

To enable native mode:

1. Bring up the 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 "Native Mode Enabled" box.

Configure Other Relevant Console Properties

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

You will have to restart the server if you make jCOM configuration changes. The Administration Console will also indicate the server should be restarted to activate your changes.

Prepare Your Server Code to Call the COM Objects

Prepare your server code to call the COM objects.

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);