1
Runtime and Development Exceptions

This chapter describes the TopLink exception classes. Each type of exception corresponds to a range of error code (see Chapter 2, "Error Codes and Descriptions").

TopLinkExceptions

All TopLink exceptions are descendents of RuntimeException. The TopLinkException class is the superclass of all runtime and development type exceptions.

Runtime Exceptions

Runtime exceptions indicate error conditions at runtime, and do not necessarily indicate fatal errors. Instead, they indicate that runtime conditions are invalid, such as the loss of database connection. All of these exceptions should be handled in a try-catch block.

The following exceptions can be thrown at runtime:

• DatabaseException

• OptimisticLockException

• CommunicationException

Development Exceptions

Development exceptions indicate that a certain fragment of code is invalid. All development exceptions do not depend on runtime conditions and must therefore be solved before deploying the application. For example, the DescriptorException is thrown the first time an application is executed if an erroneous descriptor or mapping property is set. Development exceptions are useful as a debugging tool to find inconsistencies in the descriptor. Because development exceptions are not normal behavior, they must not be handled in a try-catch block.

The following exceptions are not dependent on runtime conditions. If one of these exceptions is thrown, the application code being tested is invalid and must be changed. Avoid handling these types of exceptions:

• BuilderException

• ConcurrencyException

• ConversionException

• DescriptorException

• QueryException

• ValidationException

Format of Exceptions

All exceptions return the name of the exception and a message describing what caused the exception. The message given is dependent on the type of exception.

Each TopLink exception thrown has the following information:

• The name of TopLink exception

• A description of the most probable cause of the error

• A native error code

BuilderException

A development exception that is raised when the Builder file format for the descriptor is not in a proper state. If possible, the message returned gives the line number of the appropriate descriptor file that caused the exception.

The source and line number are not printed only when it is possible for TopLink to detect the actual source of problem. Internal exception is printed when BuilderException was caused due to the exception thrown by the VM.

Format

EXCEPTION [TOPLINK - error code]: Exception name
EXCEPTION DESCRIPTION: Message
INTERNAL EXCEPTION: Message
SOURCE: The source to the descriptor file that caused the error.
LINE NUMBER: The line number that caused the exception to be raised. This is the 
line number in the descriptor file.

Example 1-1 BuilderException

EXCEPTION [TOPLINK - 1038]: oracle.toplink.tools.builderreader.BuilderException
EXCEPTION DESCRIPTION: No such section token: ABC

CommunicationException

A runtime exception that wraps all RMI, CORBA, or IO exceptions that may occur.

ConcurrencyException

A development exception that is raised when a Java concurrency violation occurs. Internal Exception is shown only when the running thread was interrupted and VM threw InterruptedException.

Format

EXCEPTION [TOPLINK - error code]: Exception name
EXCEPTION DESCRIPTION: Message
INTERNAL EXCEPTION: Message

Example 1-2 ConcurrencyExcpetion

EXCEPTION [TOPLINK - 2004]: oracle.toplink.exceptions.ConcurrencyException
EXCEPTION DESCRIPTION: Signal attempted before wait on concurrency manager. 
This normally means that an attempt was made to commit or rollback a transaction 
before being started, or rolledback twice.

ConversionException

A development exception that is raised when a conversion error occurs by an incompatible type conversion. The message returned indicates which type cast caused the exception.

Format

EXCEPTION [TOPLINK - error code]: Exception name
EXCEPTION DESCRIPTION: Message
INTERNAL EXCEPTION: Message

Example 1-3 ConversionException

EXCEPTION [TOPLINK - 3006]: oracle.toplink.exceptions.ConversionException
EXCEPTION DESCRIPTION: object must be of even length to be converted to a 
ByteArray

DatabaseException

A runtime exception that is raised when data read from the database or the data that is to be written to the database is incorrect. The exception also acts as a wrapper for SQLException in which case it contains a reference to the error code and error message. This exception can occur on any database type operation.

Internal exception and error code are printed when the exception is wrapping SQLException.

Format

EXCEPTION [TOPLINK - error code]: Exception name
EXCEPTION DESCRIPTION: Message
INTERNAL EXCEPTION: Message
ERROR CODE: Error code

Example 1-4 DatabaseException

EXCEPTION [TOPLINK - 4002]: oracle.toplink.exceptions.DatabaseExceptions
EXCEPTION DESCRIPTION: java.sql.SQLException: [INTERSOLV][ODBC dBase driver] 
Incompatible datatypes in expression: >
INTERNAL EXCEPTION: java.sql.SQLException: [INTERSOLV][ODBC dBase driver] 
Incompatible datatypes in expression: >
ERROR CODE: 3924

DescriptorException

A development exception that is raised when insufficient information has been provided to the descriptor. The message returned includes the name of the descriptor or mapping that caused the exception. If a mapping within the descriptor caused the error, the name and parameters of the mapping are part of the returned message.

Internal exception, mapping and descriptor are optional. They are displayed only when TopLink has enough information about the source of the problem.

Format

EXCEPTION [TOPLINK - error code]: Exception name
EXCEPTION DESCRIPTION: Message
INTERNAL EXCEPTION: Message
MAPPING: Database mapping
DESCRIPTOR: Descriptor

Example 1-5 DescriptorException

EXCEPTION [TOPLINK - 75]: oracle.toplink.exceptions.DescriptorException
EXCEPTION DESCRIPTION: The reference class is not specified.

OptimisticLockException

A runtime exception that is raised when the row on the database matching the desired object is missing or when the value on the database does not match the registered number. It is used in conjunction with the optimistic locking feature. This applies only on update or delete operation. Refer to the Oracle9iAS TopLink: Mapping Workbench Reference Guide for more information on optimistic locking. These exceptions should be handled in a try-catch block.

Format

EXCEPTION [TOPLINK - error code]: Exception Name
EXCEPTION DESCRIPTION: Message

Example 1-6 OptimisticLockException

EXCEPTION [TOPLINK - 5003]: oracle.toplink.exceptions.OptimisticLockException
EXCEPTION DESCRIPTION: The object, object.toString() cannot be deleted because 
it has changed or been deleted since it was last read.

QueryException

A development exception that is raised when insufficient information has been provided to the query. If possible, the message indicates the query that caused the exception. Query is optional and is displayed if TopLink has a query that caused this exception.

Format

EXCEPTION [TOPLINK - error code]: Exception name
EXCEPTION DESCRIPTION: Message
QUERY:

Example 1-7 QueryException

EXCEPTION [TOPLINK - 6026]: oracle.toplink.exceptions.QueryException
EXCEPTION DESCRIPTION: Query is not defined.

TopLinkException

Superclass for all TopLink-generated exceptions. It is an abstract class.

ValidationException

A development exception that is raised when an incorrect state is detected or an API is used incorrectly.

Format

EXCEPTION [TOPLINK - error code]: Exception name
EXCEPTION DESCRIPTION: Message

Example 1-8 ValidationException

EXCEPTION [TOPLINK - 6026]: oracle.toplink.exceptions.ValidationException
EXCEPTION DESCRIPTION: Child descriptors do not have an identity map, they share 
their parent's.