Handling COM Errors in Java

This section tells you what HRESULTs are and how they are wrapped in ComFailException objects. Then try-catch blocks are explained, and an example with error handling is presented.

HRESULTs

The primary way that COM methods communicate failure information back to their callers is through the HRESULT, which every COM interface method returns. COM methods return this value, which is a 32-bit error code, to indicate success or failure of a method call. In almost all cases, only one success code is defined (S_OK), but many failure codes are defined. For a list of the values of common system-defined HRESULTs, see the ComFailException class. For domain-specific errors, consult the documentation for the component you are using.

The documentation for many components describes errors in terms of Visual Basic Err.Number values rather than HRESULTs. However, some components use a convention where there is a correspondence between the HRESULT returned and the Err.Number value. For example, if you are using Data Access Objects (DAO) or Remote Data Objects (RDO), you can call the getHResult method on the ComFailException object, take the lower 16 bits of the returned HRESULT, convert that value to decimal, and check it against the errors described in the DAO or RDO documentation.

The Microsoft VM defines a class called com.ms.com.ComException. This class wraps the HRESULT error code, and is used to communicate error information from COM back to Java whenever a COM method fails. The ComException class defines a getHResult method that returns the error code, in the form of a Java int, describing the specific error. You can also use the getMessage method (defined by the Java class Throwable) to retrieve the detail message.

Try-Catch Blocks

The Microsoft VM throws an exception when a call to a COM interface method returns an HRESULT containing a failure code. To find out about errors that occur during method calls, Java programmers use try-catch blocks to catch exceptions thrown by the virtual machine. Because the ComException class is derived from the Java class RuntimeException, the compiler does not strictly require a throws clause in the method declaration. Nor does the compiler require try-catch blocks. Since runtime exceptions are unchecked by the compiler, you can use try-catch blocks when you decide they are needed.

Because ComException is an abstract class, a ComException object cannot be constructed directly. However, a ComFailException object or a ComSuccessException object can be constructed. Typically, you try to catch ComFailException objects so that you know when something has gone wrong during a call to a COM method. The following example demonstrates the use of a try-catch block:

try
{
    // Call COM method.
}
catch (com.ms.com.ComFailException e)
{
    System.out.println( "COM Exception:" );
    System.out.println( e.getHResult() );
    System.out.println( e.getMessage() );
}

An Error Handling Example

The following Java code is similar to the code we saw in the Implementing COM Objects section; however, error handling has been added.

import robocorp.bots.*;
...
try
{
	Robot robbie = new Robot();
	robbie.GoForward(10);
	robbie.Turn(-90);
}
catch(Throwable e)
{
	System.out.println("Something bad happened!");
}