4.1.1. COM Memory Management in JNIWrapper

All COM resources as well as other native resources that are allocated by JNIWrapper are garbage-collected automatically by JNIWrapper's NativeResourceCollector (NRC). NRC starts automatically on the application startup and runs permanently while the application runs.

There is no need to call the addRef() and release() methods. The addRef() method is called when an object is created and the release() method is called automatically when the instance is not used any more by NRC. Also, when an instance of some COM class is created, it is automatically registered in NRC.

Alternatively, there is an ability to control the process of instance deallocation by setting its AutoDelete property to false using the setAutoDelete(false) method. The example below demonstrates how to do this:

IUnknownImpl object = getObject();
object.setAutoDelete(false);
try {
// do something with the object here
} finally {
object.release();
} 

4.1.2. Initializing COM

The initialization should be called at least once for each thread that uses the COM classes or functions. You can do this by invoking one of the following methods:

4.1.3. Performing Clean-up

The COM support should be uninitialized when the application shuts down. To uninitialize the COM integration, OleFunctions.oleUninitialize() should be called if initialization was performed by oleInitialize(); otherwise ComFunctions.coUninitialize() should be used.

Both these methods do the following:

• Close the COM library in the current thread.

• Free allocated resources.

• Release any class factories or services.

4.2.1. OleMessageLoop Class

The com.jniwrapper.win32.automation.OleMessageLoop class provides implementation for the COM dispatch thread and methods for starting and stopping the loop thread, and invoking COM functions in this thread.

4.2.2. Invoking COM Methods Without Return Values

If a COM function you intend to invoke does not return results or you are not interested in returning these results to the calling thread, you can add the Runnable action to the execution queue of the OleMessageLoop class.

...
  Runnable action = new Runnable() {
     public void run()
     {
       // working with COM here
     }
  };
  OleMessageLoop.addAction(action);
... 

The calling thread will continue its execution after the addAction() call. The action will be run after all actions already set in the queue are executed.

4.2.3. Invoking COM Methods with Return Values

Returning values to the calling thread is a bit more complicated. To do this, the following steps should be performed:

After the function call is requested, the calling thread will wait until the function returns the result. The following example demonstrates this invocation technique:

public class Test
{
  private _PropertyReaderImpl _pr = null;
  public Test()
  {
     _pr = (_PropertyReaderImpl)OleMessageLoop.invokeMethod(
      this, // caller
      "createPropertyReaderClass", // function name
      new Object[]{ // parameters
      new ClsCtx(ClsCtx.CLSCTX_INPROC_SERVER)});
  }

  public Object createPropertyReaderClass(ClsCtx dwClsContext)
  {
     final _PropertyReaderImpl prClass = PropertyReader.create(
                           dwClsContext);
     return prClass;
  }
}

4.2.4. Displaying Errors

By following the rules mentioned in the previous sections, you should achieve stable COM integration in your application. Generally, if code appears to be non-working, ComException is thrown with the error code 0x800401f0:

com.jniwrapper.win32.com.ComException: COM object method returns error code: -->
--> Unknown code(0x800401f0)

If you get such an exception, please verify that your code is written according to the COM integration guidelines described in this document.

4.2.5. Creating New OLE Message Loop Thread

The OleMessageLoop class can be used as a singleton or as an ordinary class. Every instance of OleMessageLoop reflects to its own thread.

OleMessageLoop has a static getInstance() method that allows you to access a single OleMessageLoop instance.

There are three public constructors for creating OleMessageLoop instances. When an OleMessageLoop instance is created, the message loop thread is not started yet. It should be started manually by calling the OleMessageLoop.doStart() method.

A message loop thread can be a daemon (by default) or not. Use the OleMessageLoop(boolean) constructor to specify whether the thread is a daemon:

    //Creating a daemon message loop thread
    OleMessageLoop oleMessageLoop = new OleMessageLoop(true);
    //Starting the thread
    oleMessageLoop.doStart();

4.2.6. Invoking Functions Synchronously

Use OleMessageLoop.doInvokeAndWait() (or static OleMessageLoop.invokeAndWait() for a singleton) to execute code in the message loop thread synchronously:

    Runnable runnable = new Runnable()
    {
        public void run()
        {
            _Workbook workbook = new _WorkbookImpl(oleContainer.getOleObject());
            String name = workbook.getName().getValue();
            System.out.println("Workbook name = " + name);
        }
    };
    try
    {
        oleMessageLoop.doInvokeAndWait(runnable);
    }
    catch (InterruptedException e)
    {
        e.printStackTrace();
    }
    catch (InvocationTargetException e)
    {
        e.printStackTrace();
    }

Any exceptions that are thrown in executing code are wrapped into the InvocationTargetException class. Call the InvocationTargetException.getCause() method to get the original exception.

4.2.7. Invoking Functions Asynchronously

Use OleMessageLoop.doInvokeLater() (or static OleMessageLoop.invokeLater() for a singleton) to execute code in the message loop thread asynchronously:

    Runnable runnable = new Runnable()
    {
        public void run()
        {
            OleContainer oleContainer = new OleContainer();
            oleContainer.createObject("Excel.Sheet");
            _Workbook workbook = new _WorkbookImpl(oleContainer.getOleObject());
            String name = workbook.getName().getValue();
            System.out.println("Workbook name = " + name);
        }
    };
    oleMessageLoop.doInvokeLater(runnable);

4.2.8. Binding Objects to OLE Message Loop Thread

OleMessageLoop provides the ability to invoke all methods of an object in the OLE message loop thread using the binding operation:

    //Creating a new _Workbook instance in the OLE message loop thread
    Runnable runnable = new Runnable()
    {
        public void run()
        {
            workbook = new _WorkbookImpl(oleContainer.getOleObject());
        }
    };
    try
    {
        oleMessageLoop.doInvokeAndWait(runnable);
    }
    catch (InterruptedException e)
    {
        e.printStackTrace();
    }
    catch (InvocationTargetException e)
    {
        e.printStackTrace();
    }

    //Binding the workbook object
    workbook = (_Workbook) oleMessageLoop.bindObject(workbook);
    //Invoking a workbook function in the OLE message loop thread
    String name = workbook.getName().getValue();

If the method of a bound object returns an object, the returned object is not bound to the OLE message loop thread:

    //Binding the workbook object
    workbook = (_Workbook) oleMessageLoop.bindObject(workbook);
    //Invoking a workbook function in the OLE message loop thread.
    //The sheets object is not bound
    Sheets sheets = workbook.getSheets();
    //Binding the sheets objects
    sheets = (Sheets) oleMessageLoop.bindObject(sheets);

4.3.1. Creating Server Implementation

Create a Java class that extends the IUnknownServer class and implements required COM interfaces as shown in the example below:

// COM class implementation
public static class OleClientSiteImpl extends IUnknownServer
    implements IOleClientSite,
            IOleInPlaceSite,
            IOleDocumentSite,
            IOleWindow,
            IOleInPlaceFrame
{
    ...
}

If your server-side implementation of a COM object needs to provide automation functionality via the IDispatch interface, you can derive your class from IDispatchServer that provides default implementation.

4.3.2. Creating Class Factory

Create a class factory server for a given COM class implementation:

// Creating a class factory server for our COM class
IClassFactoryServer oleClientSiteClass =
  new IClassFactoryServer(OleClientSiteImpl.class);

IClassFactoryServer will automatically register the interfaces that are implemented by the specified class and its parents. If the class (OleClientSiteImpl in the example above) extends IDispatchServer, the default interface will be automatically set to IDispatch; otherwise the default interface will be set to IUnknown.

If you need to specify a custom default interface, call the IClassFactoryServer.setDefaultInterface() method:

// register a default interface for our COM class
oleClientSiteClass.setDefaultInterface(IOleClientSite.class);

And finally, retrieve a class factory from the class factory server instance:

IClassFactoryImpl classFactory =
                      oleClientSiteClass.createIClassFactory();

4.3.3. Creating Instances

Now that you have the instance of the class factory, you can use it to create an instance of your COM class using the following example:

IOleClientSiteImpl oleClientSite = new IOleClientSiteImpl();
classFactory.createInstance(null, oleClientSite.getIID(), oleClientSite);

The null parameter above means that the object is not created as part of an aggregate. Pass a valid IUnknown instance instead of null if you work with aggregates.

4.4.1. Automation Class

You can invoke a method of a dispatchable object using the invoke() method of the com.jniwrapper.win32. automation.Automation class. Setting and getting properties is done using the setProperty() and getProperty() methods, respectively.

All calls to this "automated" class are performed in its OLE message loop thread. The following example demonstrates this.

// retrieve the dispatched interface
IUnknownImpl dispatchable = getDispatchable();
String fileName = getFileName();

// create an Automation for instance
Automation automation = new Automation(dispatchable);

// set the COM object property using automation
automation.setProperty("FileName", fileName);

// invoke the COM object method using automation
automation.invoke("LoadFile", new Object[] {fileName});

4.6.1. Displaying Java Menus over ActiveX Component

In many cases, it is necessary to display Java menus over an ActiveX component embedded into OleContainer. However, by default all Java menus are "lightweight" and cannot be displayed over the "heavyweight" ActiveX components. To solve this problem, just add the following piece of code to your program:

JPopupMenu.setDefaultLightWeightPopupEnabled(false);

CodegenForComfyJ.bat guid 00062FFF-0000-0000-C000-000000000046 9.2 src outlook

CodegenForComfyJ.bat progid shell.explorer 1.1 src explorer -disp

5.1.1. Running Code Generator in GUI Mode

Apart from the command-line version, you can work with Code Generator in GUI mode. To start a GUI-based program, run CodegenForComfyJ.bat without any parameters. The first wizard step will be as follows:

Select, for example, the "Generate for a registered COM type library" option. At the next step, you need to select a COM component:

To quickly find a needed component, just place focus in the list and start typing. Let's select Google Earth Type Library. At the next step, you need to provide the wizard with additional information: specify where to save the generated code, the package name that will be used and whether to generate wrappers for disinterfaces:

The last step allows you to select generation-related options:

That is all information required for code generation. Just click the "Generate" button and in a few seconds, the stubs will be created:

5.1.2. Detecting GUID, ProgID and Version

Normally, GUIDs are declared in documentation for COM objects. If you don't have the GUID for the COM library, you may want to search for it in Windows Registry under:

HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID

The type library can hold multiple versions of COM objects. Like with GUID, consult the documentation for the correct version number.

5.3.1. Structures, Unions, Enumerations

These data type classes are created in the root package.

5.3.2. Interfaces

Interfaces are created in the package root. The code for each interface defines methods for corresponding COM interface and the interface identifier.

5.3.3. Implementation Classes

The Java code for each generated COM interface is accompanied by the implementing classes. These classes serve as client-side code for invoking methods of corresponding COM interfaces. These classes are generated under the impl subpackage.

Each implementation class contains a constructor that takes IUnknown as a parameter. Using this constructor, you can cast one interface to another if it is implemented by the COM class you integrate with. This is similar to calling the QueryInterface() COM method.

5.3.4. CoClasses

The Microsoft COM documentation defines a class as "an implementation that allows QueryInterface between a set of interfaces" (see "Platform SDK: Microsoft Interface Definition Language (MIDL)").

Code Generator creates classes derived from com.jniwrapper.win32.com.CoClass for each coclass found in the type library. Coclasses serve as a factory for objects that implement default interfaces associated with the coclass.

Each CoClass provides methods with the following signatures:

public static DefInterface create(ClsCtx dwClsContext)
                                       throws ComException;

public static DefInterface queryInterface(IUnknown unknown)
                                       throws ComException;

where DefInterface is the default interface associated with the coclass.

The create() method creates an object implementing the default interface of the coclass. The parameter passed to the method designates the execution context for the class.

The queryInterface() method allows to get the default interface from the existing COM object passed as IUnknown.

5.3.5. VTBL Classes

JNIWrapper provides the ability to expose a Java class as a COM object, so it can be called by the native side of the integrated application. VTBL classes provide callbacks for the native side code exposing a Java class as a COM object. For more information on calling Java from native side, please see the section "Exposing COM to Java".

6.1.1. Developing Java Dispinterface

When developing Java dispinterfaces, please pay attention to the following:

• Custom interfaces should derive from the com.jniwrapper.win32.automation.IDispatch interface.

• The return values and arguments of the dispinterface methods should be of JNIWrapper types (such as DoubleFloat or BStr).

• Your Java interfaces will not be available as regular COM interfaces.

The sample dispinterface is shown below:

public interface ISample extends IDispatch
{
    public BStr getProgId();
}

For the full code sample, please see ComToJava/src/ISample.java

6.1.2. Developing Java COM Server Class

A Java COM server class should implement all the interfaces you want to provide in your COM server. When developing a Java COM server, pay attention to the following:

• This class should declare COM_SERVER_CLSID as the public static final field that describes your COM server's globally unique class identifier (CLSID). In the same way, it can also declare PROG_ID, VERSION_INDEPENDENT _PROG_ID and COM_SERVER_DESCRIPTION, but only CLSID is required.

• The return values and attributes of the methods should be of JNIWrapper types (such as DoubleFloat or BStr).

Here is the example of the COM server class:

public class JavaComServerSample extends DispatchComServer implements IPersist, ISample
{
    public static final CLSID COM_SERVER_CLSID =
         new CLSID("{A35B432E-5274-4146-9858-638313EDCEA6}");
    public static final String PROG_ID = "jniwrapper.comtojavasample.1";

    public void getClassID(CLSID pClassID) throws ComException
    {
        pClassID.setData1(COM_SERVER_CLSID.getData1());
        pClassID.setData2(COM_SERVER_CLSID.getData2());
        pClassID.setData3(COM_SERVER_CLSID.getData3());
        pClassID.setData4(COM_SERVER_CLSID.getData4());
    }

    public BStr getProgId()
    {
        return new BStr(PROG_ID);
    }
}

For the full code sample, see ComToJava/src/JavaComServerSample.java

Manifest-Version: 1.0
Class-Path: jniwrap-3.0.jar comfyj-2.0.jar winpack-3.0.jar jniwraplib.jar

6.2.1. ComfyJ ServerManager: Registering in Command-Line Mode

The ServerManager application allows you to register the Java COM server using the command line. If you run ServerManager.bat with the "/?" or "-h" paramater, you will see a quick guide to using the program in console mode:

Usage 1: Command line mode

    Registering Java COM server
    ---------------------------------
    Usage: ServerManager.bat serverClassName -classpath classpath [-jvm jvmPath]

       serverClassName    Java COM server class name.
       classpath          Classpath that will be used for running the server.
                          Make sure that classpath includes jniwrap.jar, comfyj.jar,
                          and winpack.jar libraries.
       jvmPath            Optional. Specifies the JVM (java.exe or javaw.exe) that
                          will be used for running the server. If it is not defined,
                          the default JVM will be used.

    For example: ServerManager.bat com.project.MyServer
                      -classpath "c:/MyServer/jniwrap.jar;c:/MyServer/comfyj.jar;
                            c:/MyServer/winpack.jar;c:/MyServer/myserver.jar"
                      -jvm "c:\j2sdk1.4.2_06\bin\javaw.exe"

    Unregistering Java COM server
    ---------------------------------
    Usage: ServerManager.bat -unregister {serverClassName -classpath classpath
                  or -clsid clsid}

       serverClassName    Java COM server class name to be unregistered.
       classpath          Classpath of the server.
       clsid              Class ID (CLSID) of a Java COM server to be unregistered.

    For example (by class): ServerManager.bat -unregister com.project.MyServer
                            -classpath "c:/MyServer/jniwrap.jar;c:/MyServer/comfyj.jar;
                                     c:/MyServer/winpack.jar;c:/MyServer/myserver.jar"
    For example (by clsid): ServerManager.bat -unregister
                                 -clsid {A35B432E-5274-4146-9858-638313EDCEA6}

Usage 2: To run ServerManager GUI, start without parameters.

If you want to register the Java COM server, make sure to specify the fully qualified class name and the classpath to be used for running this server. Note that the classpath should include at least the jniwrap.jar, comfyj.jar and winpack.jar libraries and the library that contains the specified COM server.

The ServerManager application allows you to unregister the server by its class name or by its globally unique class identifier (CLSID). If you unregister the COM server by its class name, you need to specify the full classpath of the server too (the -classpath parameter). Unregistering the COM server by CLSID doesn't require any additional information.

6.2.2. ComfyJ ServerManager: Registering in GUI Mode

Start the ServerManager application using the bin/ServerManager.bat file from the ComfyJ distribution. When the application is opened, follow these steps:

Also, you can remove the Java COM Server from the Windows Registry by selecting the appropriate server from the list and clicking the Unregister button.

If you need to list all Java COM servers registered in the system, click the List Registered button.

6.2.3. Registering at Run Time

You can also register the Java COM Server object at run time of the program using the registerComServer() method and the com.jniwrapper.win32.tools.RegisterDispatchComServer.ComServerDescriptor class. In this case, you need to create an instance of the ComServerDescriptor class and pass it to the registerComServer() method.

Take a look at the following code as the example of the run-time component registration and its further usage:

public class RuntimeRegistrationSample
{
    public static void main(String[] args) throws Exception
    {
        String classPath =
              "C:\\JavaComServer\\comfyj.jar;" +
              "C:\\JavaComServer\\jniwrap.jar;" +
              "C:\\JavaComServer\\winpack.jar;" +
              "C:\\JavaComServer\\classes";

        RegisterDispatchComServer.ComServerDescriptor descriptor =
                new RegisterDispatchComServer.ComServerDescriptor
                        (JavaComServerSample.class, "C:\\JavaComServer\\classes",
                                System.getProperty("jvm.path"), classPath, null, false);
        RegisterDispatchComServer.registerComServer(descriptor);

        Runnable runnable = new Runnable()
        {
            public void run()
            {

                IDispatch dispatch =
                 new IDispatchImpl(CLSID.createFromProgID
                         ("jniwrapper.comtojavasample"), ClsCtx.LOCAL_SERVER);

                IPersistImpl p = new IPersistImpl(dispatch);
                CLSID clsid = new CLSID();
                p.getClassID(clsid);
                System.out.println("ClassID = " + clsid);

            }
        };
        OleMessageLoop.invokeAndWait(runnable);
        OleMessageLoop.stop();

    }
}

6.3.1. Java Client

If you want to use the Java COM server via a standard interface (like IPersist), you can access its methods by creating the appropriate implementing object (like IPersistImpl, see the sample code below) and calling its methods.

To interact with the Java COM sever via a custom interface, you need to use the com.jniwrapper.win32.automation.Automation class. In this case, the arguments of all the custom interface's methods and their return values are of the automation-specific types, so you need to wrap all the values into com.jniwrapper.win32. automation.types.Variants.

public class JavaComClientSample
{
    public static void main(String[] args) throws Exception
    {
        Runnable runnable = new Runnable()
        {
            public void run()
            {
                IDispatch dispatch =
                 new IDispatchImpl(CLSID.createFromProgID("jniwrapper.comtojavasample"),
                 ClsCtx.LOCAL_SERVER);

                IPersistImpl p = new IPersistImpl(dispatch);
                CLSID clsid = new CLSID();
                p.getClassID(clsid);
                System.out.println("ClassID = " + clsid);

                Variant result = new Variant();
                Automation automation = new Automation(dispatch);

                result = automation.invoke("getProgId");
                System.out.println("PROG_ID = " + result.getValue());

             }
        };
        OleMessageLoop.invokeAndWait(runnable);
        OleMessageLoop.stop();
    }
}

For the full code sample, please see ComToJava/src/JavaComClientSample.java

6.3.2. C++ Client

You can use the CoCreateInstance function to create an instance of the COM server via its CLSID. If you are going to interact with the Java COM server via a standard interface, specify its IID in the CoCreateInstance function call; otherwise you should specify the IID_Dispatch constant. As a result, you will be able to work with the created object via the specified interface.

To call methods from custom interfaces, you need to call the IDispatch.Invoke() method. The first parameter for the Invoke() method is dispid of the called function that was obtained using the GetIDsOfNames() method. Here is an extract from the sample:

int _tmain(int argc, _TCHAR* argv[])
{

using namespace std;
HRESULT  hr;

//Initialize COM.
CoInitialize(NULL );

LPCOLESTR progID =  OLESTR("jniwrapper.comtojavasample");
LPCLSID clsID = new CLSID;
CLSIDFromProgID(progID , clsID);

//Working with Java COM Server via the IPersist interface
IPersist* iPersistInst;
hr = CoCreateInstance(*clsID,
                           NULL,
                           CLSCTX_LOCAL_SERVER,
                           IID_IPersist,
                           (void **)&iPersistInst);

CLSID resultClsID;
iPersistInst->GetClassID(&resultClsID);
LPOLESTR  stringClsID;
hr = StringFromCLSID(resultClsID , &stringClsID);
wprintf(L"GetClassID = %s%s", (wchar_t*)stringClsID, "\n");

//Working with Java COM Server via the IDispatch interface
IDispatch* iDispatchInst;
hr = CoCreateInstance(*clsID,
                           NULL,
                           CLSCTX_LOCAL_SERVER,
                           IID_IDispatch,
                           (void **)&iDispatchInst);

DISPID dispid;
VARIANT result;
OLECHAR* funcName;
DISPPARAMS dispparamsNoArgs = {NULL, NULL, 0, 0,};

//Calling the "getProgID" method
funcName = L"getProgId";
iDispatchInst->GetIDsOfNames(IID_NULL,&funcName,1,GetUserDefaultLCID(),&dispid);
iDispatchInst->Invoke(dispid,
      IID_NULL,
      GetUserDefaultLCID(),
      DISPATCH_METHOD,
      &dispparamsNoArgs,
      &result,
      NULL,
      NULL);
wprintf(L"ProgID = %s%s", (wchar_t*)result.bstrVal, "\n");

// Free COM resources
CoUninitialize();
}

For the full code sample, please see ComToJava/native/CppSample.cpp

6.3.3. Visual Basic Client

The Visual Basic language uses Automation technology to create the COM server object by default. So you just need to create an Object variable and use the CreateObject function with PROG_ID or CLSID as its parameter to return the COM server object instance. As a result, you will be able to call the object's methods declared in your custom interface.

In the following example, JavaServer is a COM server and we're calling its getClassID and getProgId methods.

Public Class Sample

    <STAThread()> _
    Public Shared Sub Main()
        'Creating Java Com Server object by its ProgID
        Dim JavaServer As Object
        JavaServer = CreateObject("jniwrapper.comtojavasample")
        'Calling the server's methods
        Dim myClsID As Guid
        JavaServer.getClassID(myClsID)
        Console.WriteLine("ClassID = {" + myClsID.ToString + "}")
        Console.WriteLine("ProgID = " + JavaServer.getProgId)

    End Sub 'Main

End Class

For the full code sample, please see ComToJava/native/VBSample