C.2 Exceptions

JDO has an exception-class hierarchy used to represent the various kinds of exceptions that may occur. The JDOException class is at the root of the hierarchy and provides all of the methods that an application calls. All of its subclasses merely provide constructors called strictly by the JDO implementation to indicate that an error has occurred. Since an application never calls these constructors, we omit them from the class descriptions.

This is the base class for errors that can be retried.

public class JDOCanRetryException extends javax.jdo.JDOException {
}

Subclasses

JDOUserException, JDODataStoreException

This class represents datastore exceptions that can be retried.

public class JDODataStoreException extends javax.jdo.JDOCanRetryException {
}

Subclasses

JDOObjectNotFoundException

This is the base class for all JDO exceptions. It is a subclass of RuntimeException, and it does not need to be declared or caught. It includes a descriptive String, an optional nested Exception array, and an optional failed Object.

This class provides methods to retrieve the nested exception array and failed object. If there are multiple nested exceptions, then each might contain one failed object. This will be the case when an operation requires multiple instances (such as commit( ), makePersistentAll( ), etc.).

If the JDO PersistenceManager is internationalized, the descriptive string will also be internationalized.

public class JDOException extends java.lang.RuntimeException {
    public Object              getFailedObject(  );
    public Throwable[]         getNestedExceptions(  );
    public void                printStackTrace(  );
    public void                printStackTrace(PrintStream s);
    public void                printStackTrace(PrintWriter s);
    public String              toString(  );
}

Subclasses

JDOCanRetryException, JDOFatalException

This is the base class for fatal datastore errors. It is derived from JDOFatalException. When this exception is thrown, the transaction has been rolled back without the user asking for it. The cause may be a connection timeout, an unrecoverable-media error, an unrecoverable-concurrency conflict, or other causes outside of the application's control.

public class JDOFatalDataStoreException extends javax.jdo.JDOFatalException {
}

Subclasses

JDOOptimisticVerificationException

This is the base class for errors that cannot be retried. It is derived from JDOException. This exception generally means that the transaction associated with the PersistenceManager has been rolled back, and the transaction should be abandoned.

public class JDOFatalException extends javax.jdo.JDOException {
}

Subclasses

JDOFatalDataStoreException, JDOFatalInternalException, JDOFatalUserException

This is the base class for JDO implementation failures. It is a derived class of JDOFatalException. This exception should be reported to the vendor for corrective action. There is no user action to recover.

public class JDOFatalInternalException extends javax.jdo.JDOFatalException {
}

This is the base class for user errors that cannot be retried. It is derived from JDOFatalException. Reasons for this exception include:

• PersistenceManager was closed. This exception is thrown after close( ) was called, when any method except isClosed( ) is executed on the PersistenceManager instance, or when any method is called on the Transaction instance or any Query instance, Extent instance, or Iterator instance created by the PersistenceManager.

• Metadata is unavailable. This exception is thrown if the implementation cannot locate metadata for a class, which occurs when the class has not been registered.

public class JDOFatalUserException extends javax.jdo.JDOFatalException {
}

This exception notifies the application that an object does not exist in the datastore. This exception is thrown when a hollow instance is used to fetch an object that does not exist in the datastore. This exception might result from a call to getObjectById( ) with the validate parameter set to true, or from navigating to an object that no longer exists in the datastore. You will never get this exception as a result of executing a query.

Throwing this exception does not change the status of any transaction in progress. The getFailedObject( ) method returns a reference to the failed instance. The failed instance is in the hollow state and has an identity that can be obtained by calling getObjectId( ) with the instance as a parameter. This can be used to determine the identity of the instance that could not be found.

public class JDOObjectNotFoundException extends javax.jdo.JDODataStoreException {
}

A verification step (described in Chapter 15) is performed on all instances that are new, modified, or deleted when you make a call to commit an optimistic transaction. If any instances fail this verification step, a JDOOptimisticVerificationException is thrown. It contains an array of nested exceptions; each nested exception contains an instance that failed verification.

public class JDOOptimisticVerificationException
                extends javax.jdo.JDOFatalDataStoreException {
}

This class is derived from JDOCanRetryException. This exception is thrown when an implementation does not implement an optional JDO feature.

public class JDOUnsupportedOptionException extends javax.jdo.JDOUserException {
}

This is the base class for user errors that can be retried. It is derived from JDOCanRetryException. Reasons for this exception include:

Instance is not of a persistent class

This exception is thrown when a method requires an instance of a persistent class and the instance passed to the method does not implement PersistenceCapable. This occurs if the class of the instance is not persistent and has not been enhanced. getFailedObject( ) returns the instance causing the exception.

Extent is not managed

This exception is thrown when you call getExtent( ) with a class that does not have a managed extent.

Object exists

For a class using application identity, the combined value of the primary key fields must be unique. This exception is thrown if the primary key fields are not unique. This can occur when a new instance, or an existing persistent instance that has had a primary key field changed, is flushed to the datastore. It might also be thrown during makePersistent( ) if an instance with the same primary key is already in the PersistenceManager cache. The failed Object has the failed instance.

Object is owned by another PersistenceManager

This exception is thrown if you call makePersistent( ), makeTransactional( ), makeTransient( ), evict( ), refresh( ), or getObjectId( ) when the instance is already persistent or transactional in a different PersistenceManager. The failed Object has the failed instance.

Nonunique identity is not valid after transaction completion

This exception is thrown if you call getObjectId( ) on an object after transaction completion and the identity is not managed by the application or datastore.

Unbound query parameter

This exception is thrown during query compilation or execution if there is an unbound query parameter.

Query filter cannot be parsed

This exception is thrown during query compilation or execution if the filter cannot be parsed.

Transaction is not active

This exception is thrown if the transaction is not active and you call makePersistent( ), deletePersistent( ), commit( ), or rollback( ).

Object deleted

This exception is thrown if you attempt to access any fields of a deleted instance (except to read a primary key field).

public class JDOUserException extends javax.jdo.JDOCanRetryException {
}

Subclasses

JDOUnsupportedOptionException