About com.ms.com

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 Win32 VM for Java. The Microsoft VM supports two levels of integration with 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. This overview briefly explains how COM objects can be implemented in Java, and then describes some of the most frequently used classes in the com.ms.com package.

COM Objects and Java

Every Java class automatically implements IUnknown and IDispatch. This fact makes every Java object a COM object. The dispinterface implemented by the IDispatch interface contains the public methods that are on the default interface for the class. 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 the javareg tool to register it. No IDLs, type libraries, or Wizards are required.

Frequently Used Classes

The com.ms.com.IUnknown interface is a placeholder for COM interfaces. Every Java version of a COM interface is derived from com.ms.com.IUnknown. Therefore, you never call methods on com.ms.com.IUnknown. If your Java program calls a COM method whose return type is com.ms.com.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 com.ms.com.IUnknown, you can pass any COM interface to the COM method.

The Dispatch class 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.

Three classes are used to communicate error information from a COM method to Java: com.ms.com.ComException, com.ms.com.ComFailException, and com.ms.com.ComSuccessException. 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. The ComFailException and the ComSuccessException classes are 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. 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.

The com.ms.com.Variant class 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.

Certain classes in the com.ms.com package are used by internal operations and must be installed on your host system for the com.ms.com package to work correctly. Any Java applications you create, however, never need to call these classes directly. These classes are as follows:

AnsiStringMarshaller

Converts LPCSTR (pointer to a constant null-terminated Windows character string) to java.lang.String.

CUnknown

Serves as the default class for Java-callable wrappers. These wrappers belong to COM interfaces that are marshaled to Java interfaces.

UniStringMarshaller

Converts LPWSTR (pointer to a null-terminated Unicode character string) to java.lang.String.

Classes

Class _Guid

This class represents globally unique identifiers (GUIDs), which are 128-bit integer values that are used to assign world-wide unique identifiers for COM interfaces and CoClasses.

Class ComError

This class signals errors in linking Java and Component Object Model (COM) objects.

Class ComException

This class wraps an HRESULT, the return type for most methods in the Component Object Model (COM).

Class ComFailException

This class wraps an HRESULT, the return type for most methods in the Component Object Model (COM).

Class ComLib

This class contains routines that are used during Java Component Object Model (COM) integration.

Class ComSuccessException

This class wraps an HRESULT, the return type used in most methods in the Component Object Model (COM).

Class ConnectionPointCookie

This class provides methods for creating and closing a connection between a source and a sink object.

Class Dispatch

This class enables Java programs to invoke methods and access the properties of any Microsoft® ActiveX® Automation object.

Class DispatchProxy

This class wraps a dispatchable object with a Java interface.

Class LicenseMgr

This class works with the ILicenseMgr interface to enable you to use licensed Component Object Model (COM) components or controls in your Java application.

Class SafeArray

This class wraps a Microsoft® ActiveX® Automation SAFEARRAY data structure.

Class STATSTG

This class represents an STATSTG structure, which contains statistical information about an open storage, stream or byte array object.

Class Variant

This class is used to bridge Java with Microsoft® ActiveX® components that manipulate VARIANT data types.

Class WrongThreadException

This class represents objects that are thrown when a method call cannot be made because it was called on the wrong thread.

Interfaces

Interface ComContext

This class defines constants that specify the contexts that a Component Object Model (COM) class can run in.

Interface IAccessible

This interface provides methods that enable users to request selection and focus information, perform hit tests, and navigate by using object and child identifiers.

Interface IAccessibleDefault

This interface provides methods that enable users to request selection and focus information, perform hit tests, and navigate by using object and child identifiers.

Interface IEnumVariant

This interface provides methods for enumerating a collection of variants.

Interface IExternalConnectionSink

This interface provides methods that allow Java objects exposed as Component Object Model (COM) objects to receive notifications about calls made to the IExternalConnection interface that is exposed by the Microsoft® Win32® VM for Java.

Interface ILicenseMgr

This interface supports the use of licensed Component Object Model (COM) components or controls in a Java application.

Interface IPropertyNotifySink

This interface provides methods that allow a sink object to receive notifications about property changes from another object.

Interface IServiceProvider

This interface provides a method that locates a service specified by a GUID and returns the interface pointer for a requested interface on the service.

Interface IStream

This interface provides methods for reading and writing data to stream objects.

Interface IUnknown

This interface is used as the return type for Component Object Model (COM) methods that return arbitrary COM interfaces.

Interface NoAutoScripting

When used in the implements clause of a class definition, this interface prevents the Microsoft Win32 VM for Java from including its own IDispatch implementation for the class.

Hierarchy

Object
  |
  +--_Guid
  |
  +--ComLib
  |
  +--ConnectionPointCookie
  |
  +--Dispatch
  |
  +--DispatchProxy
  |
  +--LicenseMgr (IUnknown, ILicenseMgr)
  |
  +--SafeArray
  |
  +--STATSTG
  |
  +--Variant

OutOfMemoryError
  |
  +--ComError

RuntimeException
  |
  +--ComException
  |  |
  |  +--ComFailException
  |  |
  |  +--ComSuccessException
  |
  +--WrongThreadException

ComContext
IAccessible
IUnknown
IAccessibleDefault
IEnumVariant
IExternalConnectionSink
ILicenseMgr
IPropertyNotifySink
IServiceProvider
IStream
NoAutoScripting