5.4 Exception Classes

JDO defines a set of exception classes that a JDO runtime can throw. The exceptions are all runtime exceptions because they can occur whenever an in-memory persistent object is accessed, not just when a JDO method is invoked. The classes are divided into fatal and non-fatal exceptions. Refer to Figure 5-3 for the JDO exception class hierarchy.

A JDO exception behaves the same as a normal Java runtime exception; however, in addition to an error string, a JDO exception may also have a reference to the persistent object to which the exception relates . For operations that process more than one persistent object (a commit, for example), a JDO exception contains an array of nested exceptions, one for each persistent object that encountered a problem.

5.4.1 JDOException

This is the base class for all JDO exceptions and defines the methods common to all exception classes. In addition, the toString() and printStackTrace() methods have also been overridden to include details on any nested exceptions.

5.4.1.1 Method summary

An application can get a reference to the persistent object that the exception relates to and an array of nested exceptions where multiple problems were encountered.

 Object getFailedObject() 

This method returns the persistent object that the exception relates to or returns null if there is no specific persistent object.

 Throwable[] getNestedExceptions() 

This method returns an array of nested exceptions where multiple problems were encountered or returns null if there are no nested exceptions.

These methods were added in the JDO 1.0.1 maintenance release.

5.4.2 JDOFatalException

This is the base class for all fatal exceptions. An operation that resulted in a fatal exception cannot be retried. Typically, the only recourse is to restart a transaction or even get a new PersistenceManager instance.

5.4.3 JDOFatalUserException

This exception indicates a fatal problem with the application. It typically means that the application has called a method at an inappropriate time. This exception might be thrown in these cases:

• A method, other than isClosed() , is called on PersistenceManager after it has been closed or instances associated with a closed PersistenceManager are accessed ( Query , Extent , Transaction , and so on).

• The getPersistenceManagerFactory() method on JDOHelper cannot find the specified PersistenceManagerFactory class or unsupported options have been specified.

5.4.4 JDOFatalInternalException

This exception indicates a fatal internal problem with the JDO implementation. There is little recourse other than to report the problem to the vendor for rectification.

5.4.5 JDOFatalDataStoreException

This exception indicates a fatal problem with the datastore. Any active transaction is rolled back. This exception might be thrown in these cases:

• The current transaction has been automatically rolled back by the datastore, perhaps due to a timeout.

• The connection to the datastore has been lost, perhaps due to a network problem.

5.4.6 JDOOptimisticVerificationException

This exception indicates the completion of an optimistic transaction failed due to a conflicting update in the datastore. Any active transaction is rolled back. The only case where this exception is thrown is as a result of calling the commit() method on a Transaction instance whose Optimistic property is true .

5.4.7 JDOCanRetryException

This is the base class for non-fatal exceptions. An operation that resulted in a non-fatal exception can be retried.

5.4.8 JDOUnsupportedOptionException

This exception indicates a non-fatal application problem. The application has tried to use an optional feature that the JDO implementation does not support. This exception might be thrown in these cases:

• Invoking setOptimistic() on Transaction when optimistic transactions aren't supported by the JDO implementation.

• Trying to use collection classes not supported by the JDO implementation.

5.4.9 JDOUserException

This exception indicates a non-fatal application problem. The application can continue and potentially rectify the problem and retry the operation. This exception might be thrown in these cases:

• An instance of a non-persistence-capable class is passed to a method that expects an instance of a persistence-capable class.

• The getExtent() method is used on PersistenceManager when the class does not have a managed Extent .

5.4.10 JDODataStoreException

This exception indicates a non-fatal problem with the datastore. The application can continue and potentially rectify the problem and retry the operation.

5.4.11 JDOObjectNotFoundException

This exception indicates a non-fatal application problem. Essentially, a persistent object could not be found in the datastore. This exception might be thrown in these cases:

• Dereferencing a reference to a persistent object that has previously been deleted, perhaps by a different application.

• The getObjectById() method on PersistenceManager is unable to find a persistent object with the specified object identity.

The exception contains the persistent object that could not be found, which is returned by the getFailedObject() method. The only valid operation on the in-memory instance is to the get its JDO object identity, because anything else simply results in another exception.