Using a COM Object From Java

The jactivex tool allows you to load and invoke OLE Automation objects directly from your Java source. There is also some limited support for types not supported by Automation using the Custom Marshaling feature. This section includes the following topics:

New Features

Importing a COM Class Using the Jactivex Tool

Using a COM Object in Your Java Code

Importing a COM Class Using the Jactivex Tool

To use a COM class from Java, you must first import it into Java using the jactivex command-line tool. The jactivex tool, when used with the /javatlb switch, generates .java files for the classes and interfaces described by a type library. These .java files, once compiled into .class files, allow Java programs to use COM services.

The typical way to use the jactivex tool to import a COM class is as follows:

		jactivex /javatlb filename

where filename is the name of the type library that defines the class that you want to import. The filename should have one of the following extensions: .tlb, .olb, .ocx, .dll, or .exe.

Suppose you ran jactivex using the following command:

		jactivex /javatlb  widgets.tlb

This command first creates a \Widgets subdirectory underneath the trusted library directory specified by the registry key HKEY_LOCAL_MACHINE\Software\Microsoft\Java VM\TrustedLibsDirectory. If the trusted library directory is \Windows\Java\Trustlib, the preceding command creates the directory \Windows\Java\Trustlib\Widgets, and fills it with .java files—one for each class, structure, enumeration, and interface described by the widgets.tlb type library. If the type library contains an importlib statement, jactivex creates a separate Java package in a separate directory for the imported type library.

For more information about installing and using the jactivex tool, see the description of jactivex in the Introduction to Jactivex section of the Tools article.

Using a COM Object in Your Java Code

The following example is presented to help you understand how to use COM objects in your code. Suppose comserver.dll, which defines a CComBeeper class and an IComBeeper interface, is registered as having type library information. Running the jactivex tool (with the /javatlb switch) on comserver.DLL would create a package named comserver, containing the Java class CComBeeper and the Java interface IComBeeper.

Once you've run jactivex on comserver.dll, you can use the import statement in your Java source code to easily refer to classes in the comserver package. For example:

import comserver.*;   // import comserver package 

This statement is identical to Java's syntax for importing an entire package. It is not strictly necessary, however. In Java, any class can be referenced using its fully qualified name (for example, java.awt.Canvas), as long as a class fitting that name can be found when searching the class path. The import statement allows you to refer to the class using its short name (for example,Canvas).

The same rule applies to importing COM classes. The import statement is not required to use the COM class. It simply allows the class to be referenced using its short name. Any COM class can always be referenced using its fully qualified name.

Instead of importing the entire package, you could explicitly import individual classes within a type library. To import individual classes, use the following syntax, which is identical to Java's syntax for importing a single class:

import comserver.IComBeeper;  
import comserver.CComBeeper;  

The Java classes that wrap COM classes can be used the same way you use other Java classes. For example, the following code declares a reference of type IComBeeper, initializes it by creating an instance of the COM class CComBeeper, gets and sets the value of a property of the object, and then calls two methods on the object:

IComBeeper testBeep = (IComBeeper)new CComBeeper();
int myTone = testBeep.getSound();
testBeep.putSound(64);
testBeep.Beep();

Because CComBeeper is a COM class, you must use one of its interfaces to manipulate an instance of the class. COM does not support accessing properties or methods on a class independently from its interfaces. For example, the following statements would be legal Java code, but will cause errors when used with a COM class:

CComBeeper testBeep = new CComBeeper(); // Don't do with COM class.
int myTone = testBeep.getSound();       // Causes runtime error with COM class.

Note An important restriction on using Java classes that wrap COM classes is that you cannot use an instance of the class directly; you must use the instance through an interface. However, if you generate the .java files by using the jactivex tool with its /javatlb /xi option, you can call methods on the object directly without first casting to an interface pointer. For more information on using the jactivex tool, see the Introduction to Jactivex.