INFO: JACTIVEX /X:m- DISABLES Automarshaling of COM INTERFACES

ID: Q177167

The information in this article applies to:

Microsoft SDK for Java, versions 2.0, 2.01, 2.02, 3.0, 3.1, 3.2

SUMMARY

When using COM objects in Java, there are threading issues that can cause unusual behavior. Depending on the threading model of the COM object, the Virtual Machine will either freely make calls to the COM object or use a special marshalling thread to make the calls to the COM object.

In certain scenarios, calls using the special thread can cause call blocking problems.

Using switches on the JActiveX tool, you can choose to not marshal the COM object on a special thread.

MORE INFORMATION

JACTIVEX produces Java interface source files for COM interfaces and inserts comments that tell the compiler and Java VM how to handle them. The following example of the @COM comment tells the compiler and VM that the interface is a COM interface, has a specific IID, is a dual interface, and its threading model is to be determined automatically at runtime.


/** @com.interface(iid=12345678-ABCD-12AB-A1B2-123412341234,
   thread=AUTO, type=DUAL) */ 
public interface IFoo extends IUnknown
{
...

When the thread property of the @com.interface comment equals AUTO, the Virtual Machine determines at runtime whether or not to use a special thread to marshal the call.

If the Virtual Machine creates the COM object with the new operator on a wrapper class, the Virtual Machine determines the threading model of the COM object from the registry. Then, it chooses whether or not to marshal the interfaces based on that information.

If the Virtual Machine gets a COM object from a method call or a return value of a method call, the Virtual Machine cannot determine the threading model of the object from the registry. Therefore it uses the thread property of the @com.interface comment to determine whether marshalling is needed. If the thread property is AUTO, then the Virtual Machine checks to see if the COM object aggregates the free-threaded marshaler. If so, it will not marshal the interface for that COM object. If the COM object does not aggregate the free-threaded marshaler, it will automatically marshal the interface.

There are many multithread aware COM objects that do not aggregate the free- threaded marshaler. In these cases, the VM will still marshal the thread. In order to prevent this, you must use the /X:m- switch with JActiveX. The wrapper interface will now have the following comment:


/** @com.interface(iid=12345678-ABCD-12AB-A1B2-123412341234,
   thread=NO, type=DUAL) */ 
public interface IFoo extends IUnknown
{
...

This tells the Virtual Machine to not use a marshaler thread to make calls to the COM object. Calls will directly enter the COM object from the Java code.

NOTE: It is important to make sure the COM object is truly "Free Threaded" before using this switch. If you use this switch on Apartment or Single threaded COM objects, it can cause bad behavior or crashes. Check the object's documentation or the registry to find out the object's threading model.

REFERENCES

For information about when a COM object should and shouldn't be marshaled by a custom thread, look at the Microsoft SDK for Java documentation's article "Apartment Model and Threading Issues" in the "Low-Level Java/COM Integration" section. The SDK for Java documentation can be found at the following Web site:

http://www.microsoft.com/java/

For the latest Knowledge Base articles and other support information on Visual J++ and the SDK for Java, please see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/

http://support.microsoft.com/support/java/

Additional query words:

Keywords : kbSDKJava300 kbSDKJava310 JCOM JVM kbSDKJava320
Version : WINDOWS:2.0,2.01,2.02,3.0,3.1,3.2
Platform : WINDOWS
Issue type : kbinfo