How to Run Java Clients in Native Mode (COM Component In-process or Out-of-process)

In order to let a Java client access a COM object using native mode, run the 'com2java' tool on the COM object's type library, and generate the Java proxies as you would when using J-Integra® in DCOM mode. If you are not familiar with this, then please run through a couple of the standard examples (such as the Excel example)..

When running the JVM, define the JINTEGRA_NATIVE_MODE property to enable native mode:

• From the command line:
  java -DJINTEGRA_NATIVE_MODE ExcelExample
• In your Java code:
  System.setProperty("JINTEGRA_NATIVE_MODE", "");

Pass a host name to the COM object's constructor to create a remote COM component.

The J-Integra® runtime first attempts a CoCreateInstanceEx with flags set to CLSCTX_ALL. If this fails, it retries with flags set to CLSCTX_SERVER.

Threading Models

By default the J-Integra® runtime initializes COM using the COINIT_MULTITHREADED flag. If you wish to have COM initialized using a different flag, set the JINTEGRA_COINIT_VALUE property.

For example to have COM initialized using the APARTMENTTHREADED (Apartment-threaded model, also called Single Threaded Apartment - STA):

• From the command line:
  java -DJINTEGRA_NATIVE_MODE -DJINTEGRA_COINIT_VALUE=2 JavaClient
• In your Java code:
  System.setProperty("JINTEGRA_NATIVE_MODE", "");
  System.setProperty("JINTEGRA_COINIT_VALUE", "2");

To set back to MULTITHREADED (Multi-threaded model, also called Free Threads or Multi-threaded Apartment - MTA):

• From the command line:
  java -DJINTEGRA_NATIVE_MODE -DJINTEGRA_COINIT_VALUE=0 JavaClient
• In your Java code:
  System.setProperty("JINTEGRA_NATIVE_MODE", "");
  System.setProperty("JINTEGRA_COINIT_VALUE", "0");

If you get a Class Not Registered Message when using native mode and trying to talk to a COM component hosted in a DLL, try setting the JINTEGRA_COINIT_VALUE to 2 as above.

Some COM components can only be accessed from a specific threading model. For example, you must set JINTEGRA_COINIT_VALUE=2 (Apartment-threaded) when using Java to access Internet Explorer (mshtml.dll), as mentioned in Microsoft Knowledge Base Article - 183413. Setting JINTEGRA_COINIT_VALUE in a wrong threading model may throw AutomationException: 0x80004002 - No Such Interface Supported.

The J-Integra® runtime attempts to put all COM object references into a special COM table called the Global Interface Table (GIT). Whenever a call is made from Java to COM the object reference is retrieved from the GIT, which ensures that the call can be made from the current thread.

Unfortunately some COM object references (such as the Frames collection in MSHTML) can not be placed in the GIT, and so J-Integra® stores a direct pointer reference. In this situation you may have to ensure that only the creating thread makes calls onto that object. This situation is very rare, and a message is logged to the J-Integra® log (if logging is enabled) to let you know that it has happened.