Exceptions

CORBA has two types of exceptions: standard system exceptions which are fully specified by the OMG and user exceptions which are defined by the individual application programmer. CORBA exceptions are a little different from Java exception objects, but those differences are largely handled in the mapping from IDL to Java.

Topics in this section include:

• Differences Between CORBA and Java Exceptions
• System Exceptions
  • System Exception Structure
  • Minor Codes
  • Completion Status
• User Exceptions
• Minor Code Meanings

To specify an exception in IDL, the interface designer uses the raises keyword. This is similar to the throws specification in Java. When you use the exception keyword in IDL you create a user-defined exception. The standard system exceptions need not (and cannot) be specified this way.

System Exceptions

• Server-side system exceptions, such as resource exhaustion or activation failure.
• Communication system exceptions, for example, losing contact with the object, host down, or cannot talk to ORB daemon (orbd).
• Client-side system exceptions, such as invalid operand type or anything that occurs before a request is sent or after the result comes back.

All IDL operations can throw system exceptions when invoked. The interface designer need not specify anything to enable operations in the interface to throw system exceptions -- the capability is automatic.

This makes sense because no matter how trivial an operation's implementation is, the potential of an operation invocation coming from a client that is in another process, and perhaps (likely) on another machine, means that a whole range of errors is possible.

Therefore, a CORBA client should always catch CORBA system exceptions. Moreover, developers cannot rely on the Java compiler to notify them of a system exception they should catch, because CORBA system exceptions are descendants of java.lang.RuntimeException.

System Exception Structure

All CORBA system exceptions have the same structure:

exception <SystemExceptionName> { // descriptive of error
    unsigned long minor;          // more detail about error
    CompletionStatus completed;   // yes, no, maybe
}
 

System exceptions are subtypes of java.lang.RuntimeException through org.omg.CORBA.SystemException:

java.lang.Exception
 |
 +--java.lang.RuntimeException
     |
     +--org.omg.CORBA.SystemException
         |
         +--BAD_PARAM
         |
         +--//etc. 
 

All CORBA system exceptions have a minor code field, a number that provides additional information about the nature of the failure that caused the exception. Minor code meanings are not specified by the OMG; each ORB vendor specifies appropriate minor codes for that implementation. For the meaning of minor codes thrown by the Java  ORB, see Minor code meanings .

Completion Status

All CORBA system exceptions have a completion status field, indicating the status of the operation that threw the exception. The completion codes are:

COMPLETED_YES

The object implementation has completed processing prior to the exception being raised.

COMPLETED_NO

The object implementation was not invoked prior to the exception being raised.

COMPLETED_MAYBE

The status of the invocation is unknown.

CORBA user exceptions are subtypes of java.lang.Exception through org.omg.CORBA.UserException:

java.lang.Exception
 |
 +--org.omg.CORBA.UserException
      |
      +-- Stocks.BadSymbol
      |
      +--//etc. 

Each user-defined exception specified in IDL results in a generated Java exception class. These exceptions are entirely defined and implemented by the programmer

Minor Code Meanings

System exceptions all have a field minor that allows CORBA vendors to provide additional information about the cause of the exception. For a list of standard OMG minor code exceptions (OMGVMCID), refer to the OMG document at http://www.omg.org/docs/omg/03-01-04.txt.

Some of the most common Sun minor code exceptions are the following:

• COMM_FAILURE/201. vmcid: SUN minor code: 201 literally means "CONNECT_FAILURE". This may be caused by a java.net.SocketException, usually one of BindException, ConnectException, or NoRouteToHostException.

  Some things to verify are:

  • Is a naming service running? If not, start the ORBD naming service as described in the document Starting and Stopping ORBD.
  • Are the -ORBInitialHost and -ORBInitialPort values being set correctly for the naming service? If you are uncertain about what the settings should be, read the document Starting and Stopping ORBD.
  • Are the client and server applications aware of the port number (and machine name, if applicable) where the Naming Service is running? Read Starting and Stopping ORBD for more information on how to do this.

• COMM_FAILURE/208. vmcid: SUN minor code: 208 literally means "CONNECTION ABORT", which generally means the connection has been dropped.

• COMM_FAILURE/209. vmcid: SUN minor code: 209 literally means "CREATE_LISTENER_FAILED": Unable to create the listener thread on the specific port. Either the post is taken or there was an error creating the daemon thread. This generally indicates that the port on which you are trying to run the naming service is in use by another process. If you are running on Solaris, you could discover whether or not something is running on this port using the following terminal prompt command:

  netstat | grep port_number

• OBJECT_NOT_EXIST/204. vmcid: SUN minor code: 204 literally means "SERVANT_NOT_FOUND". It is only thrown in one place: corba.INSSubcontract.getINSReference.

• MARSHAL/217. vmcid: SUN minor code: 217 means that your client tried to send either a wchar or wstring in GIOP 1.0, which is not legal in the spec.

• MARSHAL/202. vmcid: SUN minor code: 202 means that the code is attempting to marshal an object that derives from org.omg.CORBA.Object, but that particular instance has never been connected to an ORB. When using the POA, you need to register the object with the POA first. If you need more information on how to register an object with the POA, refer to the POA document or the tutorial.

• BAD_PARAM/201. vmcid: SUN minor code: 201 literally means "NULL_PARAM". This exception often occurs because a Java null was given to a write method such as write_string, write_octet_array, etc. You cannot return a Java null as the result of a Java method.

• org.omg.CORBA.INTERNAL. vmcid: SUN minor code: 208 means Unable to determine local hostname using InetAddress.getLocalHost().getHostName().

  The ORB uses InetAddress.getLocalHost().getHostName() to create a reference to the name service for looking for and/or binding references. It also uses InetAddress.getLocalHost().getHostName() on the server side to create remote object references (i.e., IORs) that contain the name/port of the server (rather than a dotted-decimal/port pair).

  To avoid the call to getHostName, you can set the following properties (refer to Starting and Stopping ORBD if you are not sure how to do this):

  • Set com.sun.CORBA.ORBServerHost to the DNS name or dotted-decimal address of the server if the ORB is acting as a server.
  • Set com.sun.CORBA.ORBInitialHost to the DNS name or dotted-decimal address of the name server.

  NOTE: These properties are proprietary and are subject to deletion or change.

If none of these suggestions work for you, or if you encounter a different Sun minor code exception, email us for more information at corba-tutorial@sun.com. When requesting the meaning of a minor code please include the following information:

• The platform on which the client and server are running (e.g., Solaris, Linux, Win32)
• The version of the JDK you are using (e.g., 1.4.0_01)
• A complete stack trace
• If you are using a naming service or an ORB from a different vendor, please provide the information on the vendor and version of the product.