The classes and interfaces in the com.ms.com package allow you to implement and use Component Object Model (COM) objects from Java. Used in conjunction with the jactivex and javareg tools, the classes in this package allow you to benefit from Java/COM integration provided by the Microsoft VM. This overview explains how COM objects can be implemented in Java and describes some of the most frequently used classes in the com.ms.com package. This discussion also covers mixing Java and native code.
This package contains the following:
The Microsoft VM supports two levels of integration with Component Object Model (COM) objects. High-level integration involves converting Microsoft® ActiveX® controls to JavaBeans components and exposing JavaBeans components as ActiveX controls. Low-level Java/COM integration refers to accessing COM objects by their vtable methods, which is useful when you need to marshal data types that are not handled by IDispatch.
Every Java class automatically implements IUnknown and IDispatch. This fact makes every Java object a COM object. The IDispatch interface implements a dispinterface that contains the public methods of the class's default interface. At runtime, the Microsoft VM automatically provides type information for this IDispatch implementation. To implement a simple Automation object in Java, you place it in the class path and run javareg to register it. No IDLs, type libraries, or Wizards are required.
The IUnknown interface is a placeholder for COM interfaces. Every Java version of a COM interface is derived from IUnknown. Therefore, you never call methods on IUnknown. If your Java program calls a COM method whose return type is IUnknown, you should cast the return value to the COM interface that you are expecting. If your program calls a COM method that takes a parameter of type IUnknown, you can pass any COM interface to the COM method.
com.ms.com.ComException communicates error information from a COM method to Java. The ComException class wraps the HRESULT error code that is returned by COM interface methods. ComException objects communicate error information from a COM method to Java when the COM method fails. This class defines a getHResult method that retrieves the error code from the ComException object.
com.ms.com.ComFailException is derived from the ComException class. Typically, you try to catch ComFailException objects so that you know when something has gone wrong during a call to a COM method. The documentation for the ComFailException class contains a list of the values of system-defined HRESULTs.
com.ms.com.ComSuccessException is derived from the ComException class. For ComSuccessException objects, the default value of the stored HRESULT is S_FALSE (0x00000001L). This value indicates the successful completion of a method that returns a Boolean value of false.
com.ms.com.Variant is used to bridge Java with ActiveX components that manipulate VARIANTs. Most of the methods found in this class belong to one of three categories:
toXXX methods
Attempt to coerce the Variant object to type XXX and return the converted value, but do not copy the result back to the Variant.
getXXX methods
Retrieve data from a Variant object of type XXX, succeeding only if the Variant object is already the correct type.
putXXX methods
Change the type of a Variant object and initialize it to a new value.
Dispatch enables Java programs to invoke methods and access the properties of any ActiveX component that supports the IDispatch interface. Each of the methods in this class performs one of the following functions:
getIDsOfNames methods
Maps methods or property names to dispids.
invokev methods
Invokes methods or accesses properties.
invokeSubv methods
Invokes subroutines.
The Microsoft virtual machine can treat COM objects as special Java classes. Java/COM integration allows any Java Bean to be an ActiveX control and any ActiveX control to be a JavaBean—all nearly automatically. COM integration is best for ActiveX controls or for calling APIs that are wrapped in COM objects. You can use COM objects in Java and use Java to write COM objects.
The ability to mix and match code written in different languages lets developers achieve the maximum benefit from the tools at their disposal.
There are many scenarios that require Java code to call code that is written in some other language. For example, a Java developer may want to do one of the following:
Almost all class libraries, including the ones from JavaSoft's JDK, call code written in other languages to exploit some of these scenarios.
In the context of Java, any code that is not written in Java is called native code. This document does not deal with the pros and cons of using native code versus Java code. Rather, it attempts to describe the options available to a Java programmer who wants to call native code from Java.
The Microsoft virtual machine (Microsoft VM) provides four ways to call non-Java code from Java code. See the Integrating Java topics in the Programmer's Guide for details.
There are Java/COM integration samples in the subdirectories of %SDKDIR%\Samples\Com. For more information, see the COM Samples Overview. For information about other samples in the SDK, see the Samples Overview.