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

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.