Exceptions (Java Enterprise in a Nutshell)

10.8. Exceptions

You can define exceptions in IDL that signal errors or other unusual circumstances that may occur during a remote method call. Exceptions are declared with a unique name and an optional set of data attributes:

// IDL
exception identifier { data-member; data-member; ...};

Each data member on the exception type is simply a type specification followed by a unique identifier for the data member. The data provides the caller with additional information about what went wrong during the remote method call.

Using our geometric examples from earlier, we might define an exception that is thrown when a MultiCoord with unexpected dimensions is passed into a method:

// IDL
exception BadDimension {
	short expected;
	short passed;
};

A server object that raises one of these exceptions can set these data values, and the client making the request can read these values and interpret what went wrong.

Exceptions can be declared within any module or interface scope in your IDL file.

10.8.1. Standard Exceptions

In addition to user-defined exceptions, there is a set of standard exceptions defined within the CORBA module. These standard exceptions can be raised by any method, even though they are not listed explicitly in the method definition. These exceptions can be referenced in IDL using the CORBA:: scope (e.g., CORBA::BAD_PARAM). The standard CORBA exceptions are listed in Table 10-4. Every standard CORBA exception includes two data members: an unsigned long minor error code that can further specify the type of error that occurred, and a completion_statusenum that can be either COMPLETED_YES, COMPLETED_NO, or COMPLETED_MAYBE. These status values indicate that before the exception was raised, the method was either completed, never initiated, or in an unknown state, respectively. A more complete description of the standard exceptions (in their Java form) can be found in Chapter 28, "The javax.transaction Package".

Table 10-4. Standard CORBA Exceptions

Exception Name	Meaning
`BAD_CONTEXT`	Failure while accessing the context object.
`BAD_INV_ORDER`	Some methods were called out of their expected order.
`BAD_OPERATION`	An invalid method was called.
`BAD_PARAM`	An invalid argument was passed into a method.
`BAD_TYPECODE`	A bad typecode was used.
`COMM_FAILURE`	A communication failure occurred.
`DATA_CONVERSION`	Error while converting data.
`FREE_MEM`	Failed to free some memory.
`IMP_LIMIT`	Some implementation limit was exceeded.
`INITIALIZE`	The ORB initialization failed.
`INTERNAL`	An internal ORB error occurred.
`INTF_REPOS`	Error attempting to access interface repository.
`INV_FLAG`	An invalid flag was given.
`INV_IDENT`	Invalid identifier syntax was encountered.
`INV_OBJREF`	An invalid object reference was encountered.
`INVALID_TRANSACTION`	An invalid transaction was used.
`MARSHAL`	An error occurred while marshalling method arguments or results.
`NO_IMPLEMENT`	The implementation for the method is not available.
`NO_MEMORY`	Failed to allocate dynamic memory needed to execute the request.
`NO_PERMISSION`	Not allowed to execute the method.
`NO_RESOURCES`	There were insufficient resources for the request.
`NO_RESPONSE`	No response received for request.
`OBJ_ADAPTER`	The object adapter encountered an error.
`OBJECT_NOT_EXIST`	The referenced object does not exist on the server.
`PERSIST_STORE`	An error occurred while accessing persistent storage.
`TRANSACTION_REQUIRED`	An operation requiring a transaction was called without one.
`TRANSACTION_ROLLEDBACK`	A transactional operation didn't complete because its transaction was rolled back.
`TRANSIENT`	A transient error occurred, but the method can be tried again.
`UNKNOWN`	An error occurred that the ORB could not interpret.

10.8.2. Mapping Exceptions to Java

Standard exceptions are mapped to exception classes in org.omg.CORBA that extend the org.omg.CORBA.SystemException class. User-defined exceptions are mapped to public final Java classes that extend org.omg.CORBA.UserException, which is derived directly from java.lang.Exception. Otherwise, the exception is mapped to Java the same way as a struct, as described earlier. Each data member is mapped to a public data member of the corresponding type, and a set of constructors are defined for the exception class.