Microsoft SDK for Java

Using COM Objects in Java

This topic addresses the basics of using COM objects in Java and covers the following information:

Object Allocation compares C++ and Java object allocation.

Reference Counting compares C++ and Java reference counting.

Supporting Multiple Interfaces compares C++ and Java multiple interface support.

Implementing IDispatch discusses automatic IDispatch when implementing Automation objects.

Implementing COM Interfaces discusses importing COM interfaces into Java.

Parameters Passed by Reference shows how to retrieve a reference with Java.

To use a COM object as if it were a Java object, each COM object must have a Java-Callable Wrapper (JCW) for exposing its functionality. A JCW is a Java class that has some Microsoft-specific attributes that tell the Microsoft VM how to map the Java object to the COM component that it represents. Jactivex automatically generates JCW Java classes from any dynamic-link library (DLL) containing COM objects, or from any type library produced from a compiled COM object's Microsoft Interface Definition Language (MIDL) definition. Jactivex provides a way to generate classes that you can quickly and easily integrate with your project to leverage existing COM facilities.

To create a JCW, you insert special comments called @com directives in Java source code. Similar @dll directives give Java access to the Microsoft® Win32® APIs using Microsoft® J/Direct™.

Note   By default, jvc disables the @com and @dll directives. To enable these, use the jvc /x- option.

The @com directives specify how the Java object maps to the COM equivalent and vice versa. These mappings allow you to customize the Java representation of the COM object to suit a particular application. When these source files are compiled, the @com directives generate Java class attributes, which the Microsoft VM uses to map the COM object to the Java object.

The following table lists the COM-specific directives that the Microsoft Java compiler uses to create a JCW. For a complete description of the directive parameters available for each directive and how to use them, see the Compiler Directives Reference.

Directives Description
@com.class(GUID, security, casting) Specifies that this Java object represents a COM coclass with the given GUID, casting support, and Java security requirements.
@com.interface(GUID, thread, type) Indicates that this Java interface represents a COM interface with the specified GUID, threading model, and types.
@com.method(dispid, vtable, and so on) Marks the Java method as a COM interface method, which should be exposed in the object's vtable, dispatch table, or neither.
@com.parameters Used to specify which parameters are in, out, or a return value and how they should be mapped to COM and from COM to Java.
@com.register Used by the Microsoft® Visual J++® vjreg tool to register the compiled Java class as a COM object in the system registry.
@com.typeinfo Specifies that additional information from the type library represents this COM object.
@com.transaction Indicates various transaction situations in which the Microsoft Transaction Server can host COM objects.
@com.struct Specifies that the Java class will be a Java-Callable Data Wrapper (JCDW). 
@com.structmap Indicates how the field in a JCDW should map to COM and from COM back to this field in Java. This directive can also be used to custom marshal the data between Java and COM and to specify the data's offset from the beginning of the JCDW.

Create a new instance of a COM object in Java by instantiating a JCW Java class. The Microsoft VM creates the COM object that it refers to in addition to tracking its references. A QueryInterface is performed when a JCW is cast to an implemented COM interface using the Java cast operation. When the Microsoft VM sees this operation, it queries the underlying COM object for the interface represented by the JCW being cast to. The resulting interface is returned from the operation. The Java object can then call any methods on the second COM interface as it would any other Java object. The Microsoft VM caches the queried interfaces so that subsequent cast operations are fast.

The key to integrating Java and COM, while maintaining consistency with the Java programming model, is for the Microsoft VM to handle all garbage collection of COM objects, and to map the QueryInterface calls to simple casting operations. This functionality is directly related to how the COM IUnknown interface behaves in Java. The Microsoft VM accomplishes integration by not exposing any of the IUnknown methods to the Java developer and by internally tracking the reference counts. As a result, the developer is freed from possible bugs related to unbalanced reference counts, and avoids the redundant operation of implementing each of the IUnknown methods for each Java/COM object.

The Microsoft VM contains JCDW classes for the COM VARIANT and SAFEARRAY data types. Variants are objects that hold primitive data types, IUnknown, or IDispatch references. Variants can be used as parameters where multiple data types may be passed as parameters, and the actual data type will be determined at runtime. Variants are commonly used in Visual Basic and in COM components for passing data of variable type through Automation interfaces. 

A SafeArray object is a COM data type that allows Visual Basic to interact with COM components to pass around variable sized arrays. SafeArrays contain Variant-compatible types and information that describes the type of Variant contained, the starting position of the first element, and the overall length of the SafeArray. The Variant and SafeArray JCDWs contain Java methods that wrap the COM functions used to access the native data types. This makes using Java Variants and SafeArrays intuitive for developers and allows for easy interaction with Visual Basic through COM.

Note   When passing an array of JCDW's between COM/Microsoft® Win32® APIs and Java, in either direction, if the JCDW contains complex types such as Strings, then these complex types may not be properly propagated to memory that is not garbage collected. For normal JCDW parameters, the marshaling engine always attempts to propagate structs, but this code is missing from the case of marshaling arrays.

© 1999 Microsoft Corporation. All rights reserved. Terms of use.