Handling exceptions

The methods of the ODK API can throw exceptions to indicate certain predefined conditions. This section provides the following information about how to handle exceptions in a Java connector:

Note:
You can also use error logging and message logging to handle error conditions and messages in your connector. For more information, see Handling trace and error messages.

What is an ODK exception?

When a method of the ODK API throws an exception, this exception object is of the ODKException class or one of its subclasses, which is an extension of the Java Exception class. To create an ODK exception, use the ODKException() constructor. Table 62 shows the accessor methods that the ODKException class provides to obtain information in the exception object.

Table 62.

Information in the exception object
Member Accessor method
Message text getMsg()

Note:
For more information on the methods in the ODKException class, see ODKException class.

The ODKException class provides some subclasses to indicate specific error conditions, as Table 103 shows.

Exceptions from the ODK API library

When you write code for an ODA, you can include Java try and catch statements to handle specific exceptions thrown by the methods of the ODK API. The reference description for most ODK API methods has a section entitled Exceptions, which lists the exceptions thrown by that method.

Figure 79 shows a code fragment from sample Roman Army ODA (in the ArmyAgent4 class) that catches the exceptions that the getClientFile() method throws.

Figure 79. Catching exceptions from getClientFile()

try
   {
   remotefile = ODKUtility.getODKUtility().getClientFile(filePath, this);
   }
catch (IOException ex)            //file was not found
   {
    return null;
   }
//agent doesn't implement IGeneratesBinFiles, so "getClientFile" failed.
catch (UnsupportedContentException ex)   
   {                              //We'll return a random Son instance for now.
    return new Son("X" + ("" + new Date().hashCode()).substring(1), 
       new Date().hashCode() % 10  + 2);
   }

When an ODK API method throws an exception, it does not usually provide message and status information in the exception object. However, you can choose to fill the exception object with a message as needed.

Copyright IBM Corp. 1997, 2003