Mapping IDL to Java

This chapter contains the following topics:

• IDL to Java Overview

• Package Comments on Holder Classes

• Exceptions. This section includes the following topics:

  • Differences Between CORBA and Java Exceptions

  • System Exceptions

  • User Exceptions

  • Minor Code Meanings

    Note: This chapter contains excerpts from the Java IDL document published by Sun Microsystems, Inc. and distributed with the JDK 1.2.

IDL to Java Overview

The idltojava and m3idltojava tools read an OMG IDL interface and translate it, or map it, to a Java interface. The m3idltojava tool also creates stub, skeleton, helper, holder, and other files as necessary. While the idltojava tool creates stub, skeleton, helper, holder, and other files, the skeleton files it produces cannot be used with the WebLogic Enterprise system. When compiling the OMG IDL files to build server skeletons to be used with the WebLogic Enterprise system, be sure to use the m3idltojava tool.

These .java files are generated from the OMG IDL file according to the mapping specified in the OMG document IDL/Java Language Mapping (available from the OMG Web site at http://www.omg.org). We cross-reference the following four chapters of that document here for your convenience:

• Chapter 5, "Mapping IDL to Java"

• Chapter 6, "Mapping Pseudo-Objects to Java"

• Chapter 7, "Server-Side Mapping"

• Chapter 8, "Java ORB Portability Interfaces"

A summary of the IDL to Java language mapping follows.

CORBA objects are defined in OMG IDL. Before they can be used by a Java programmer, their interfaces must be mapped to Java classes and interfaces. Sun Microsystems, Inc. provides the idltojava tool, and the WebLogic Enterprise system includes the m3idltojava tool, which performs this mapping automatically.

This overview shows the correspondence between OMG IDL constructs and Java constructs. Note that OMG IDL, as its name implies, defines interfaces. Like Java interfaces, IDL interfaces contain no implementations for their operations (methods in Java). In other words, IDL interfaces define only the signature for an operation (the name of the operation, the datatype of its return value, the datatypes of the parameters that it takes, and any exceptions that it raises). The implementations for these operations need to be supplied in Java classes written by a Java programmer.

The following table lists the main constructs of IDL and the corresponding constructs in Java.

IDL Construct	Java Construct
module	package
interface	interface, helper class, holder class
constant	public static final
boolean	boolean
char, wchar	char
octet	byte
string, wstring	java.lang.String
short, unsigned short	short
long, unsigned long	int
long long, unsigned long long	long
float	float
double	double
enum, struct, union	class
sequence, array	array
exception	class
readonly attribute	method for accessing value of attribute
readwrite attribute	methods for accessing and setting value of attribute
operation	method

Note: When a CORBA operation takes a type that corresponds to a Java object type (a String, for example), it is illegal to pass a Java null as the parameter value. Instead, pass an empty version of the designated object type (for example, an empty String or an empty array). A Java null can be passed as a parameter only when the type of the parameter is a CORBA object reference, in which case the null is interpreted as a nil CORBA object reference.

Package Comments on Holder Classes

Operations in an IDL interface may take out or inout parameters, as well as in parameters. The Java programming language only passes parameters by value and thus does not have out or inout parameters; therefore, these are mapped to what are called Holder classes. In place of the IDL out parameter, the Java programming language method will take an instance of the Holder class of the appropriate type. The result that was assigned to the out or inout parameter in the IDL interface is assigned to the value field of the Holder class.

The package org.omg.CORBA contains a Holder class for each of the basic types (BooleanHolder, LongHolder, StringHolder, and so on). It also has Holder classes for each generated class (such as TypeCodeHolder), but these are used transparently by the ORB, and the programmer usually does not see them.

The Holder classes defined in the package org.omg.CORBA are:

AnyHolder
BooleanHolder
ByteHolder
CharHolder
DoubleHolder
FloatHolder
IntHolder
LongHolder
ObjectHolder
PrincipalHolder
ShortHolder
StringHolder
TypeCodeHolder

CORBA has two types of exceptions: standard system exceptions, which are fully specified by 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, which includes the following subtopics:

  • System Exception Structure

  • Minor Codes

  • Completion Status

• User Exceptions

• Minor Code Meanings

Differences Between CORBA and Java Exceptions

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 cannot be specified this way.

System Exceptions

CORBA defines a set of standard system exceptions, which are generally raised by the ORB libraries to signal systemic error conditions like:

• Server-side system exceptions, such as resource exhaustion or activation failure

• Communication system exceptions, such as 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, which contains 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 the section "Minor Code Meanings."

Completion Status

All CORBA system exceptions have a completion status field, which indicates 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.

User Exceptions

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. As stated in the CORBA 2.2 specification (13.4.2 Reply Message), the high order 20 bits of minor code value contain a 20-bit "vendor minor codeset ID" (VMCID); the low order 12 bits contain a minor code. BEA's VMCID is 0x54555000. Further, Sun defines single or double digit minor codes for its Java IDL ORB and BEA defines its minor code starting from 1,000. Thus, a condition common to either ORB uses the Java IDL minor code (and VMCID 0), and the BEA ORB unique minor code is 1,000 or greater.

For Sun Microsystems, Inc. minor codes, see the Java IDL documentation. For BEA's minor codes, see the Release Notes.

Table 12-1 ORB Minor Codes and Their Meanings

Table 12-2 Name Server Minor Codes and Their Meanings