The Interface Definition Language (IDL)

CORBA provides language independence. CORBA objects written in one language can send requests to objects implemented in a different language. Objects implemented in an object-oriented language such as Java or Smalltalk can talk to objects written in C or COBOL, and the converse.

Language independence is achieved through the use of a specification meta-language that defines the interfaces that an object--or a piece of legacy code wrappered to look like an object--presents to the outside world. As in any object-oriented system, a CORBA object can have its own private data and its own private methods. The specification of the public data and methods is the interface that the object presents to the outside world.

IDL is the language that CORBA uses to specify its objects. You do not write procedural code in IDL--its only use is to specify data, methods, and exceptions.

Each CORBA vendor supplies a compiler that translates IDL specifications into a specific language. Oracle8i JServer uses the idl2java compiler from Inprise. The idl2java compiler translates your IDL interface specifications into Java classes. See the Oracle8i Java Tools Reference for more information on this tool.

Note: The idl2java compiler accepts only ASCII characters. Do not use ISO Latin-1 or other non-ASCII NLS characters in IDL files.

Using IDL

The following example demonstrates the IDL for the HelloWorld example. See "Basic Example" for the complete example.

module hello {
  interface Hello {
    wstring helloWorld();
  };
};

IDL consists of a module, which contains a group of related object interfaces. The IDL compiler uses the module name to name a directory where the Java classes are placed after generation. Also, the module name is used to name the Java package for the resulting classes.

This module defines a single interface: Hello. The Hello interface defines a single operation: helloWorld, which takes no parameters and returns a wstring (a wide string, which is mapped to a Java String).

Note: IDL data and exception types, such the wstring shown in the preceding example, are not specified in this guide. Although some of the IDL to Java bindings are listed in this guide (for example see "IDL Types"), CORBA developers should refer to the OMG specification for complete information about IDL and IDL types. See "For More Information".

The module and interface names must be valid Java identifiers and valid file names for your operating system. When naming interfaces and modules, remember that both Java and CORBA objects are portable, and that some operating systems are case sensitive and some are not, so be sure to keep names distinct in your project.

Nested Modules

You can nest modules. For example, an IDL file that specifies the following modules maps to the Java package hierarchy package org.omg.CORBA.

module org {
  module omg {
     module CORBA {
       ...
     };
    ...
  };
   ...
};

Running the IDL Compiler

Assume that the HelloWorld IDL is saved in a file called hello.idl. When you run idl2java to compile the hello module, eight Java class files are generated and are placed in a subdirectory named hello in the same directory as the IDL file:

% idl2java hello.idl
Traversing hello.idl
Creating: hello/Hello.java
Creating: hello/HelloHolder.java
Creating: hello/HelloHelper.java
Creating: hello/_st_Hello.java
Creating: hello/_HelloImplBase.java
Creating: hello/HelloOperations.java
Creating: hello/_tie_Hello.java
Creating: hello/_example_Hello.java

The ORB uses these Java classes to invoke a remote object, pass and return parameters, and perform various other things. You can control the files generated, where they are put, and other aspects of IDL compiling--such as whether the IDL compiler generates comments in the Java files. See the complete description of the idl2java compiler in the Oracle8i Java Tools Reference.

Each of the files generated is described below.

Hello	This specifies, in Java, what the interface to a Hello object looks like. In this case, the interface is: package hello; public interface Hello extends org.omg.CORBA.Object { public java.lang.String helloWorld(); } Because the file is put in a hello directory, it takes the package spec from that name. All CORBA basic interface classes subclass, directly or indirectly, the following: org.omg.CORBA.Object. You must implement the methods in the interface. It is recommended that the implementation class for the hello.java interface be named helloImpl, but this naming convention is not a requirement.
HelloHolder	The application uses the holder class when parameters in the interface operation are of types out or inout. Because the ORB passes Java parameters by value, special holder classes are necessary to provide for parameter return values.
HelloHelper	The helper classes contain methods that read and write the object to a stream, and cast the object to and from the type of the base class. For example, the helper class has a narrow() method that is used to cast an object to the appropriate type, as in the following code: LoginServer lserver = LoginServerHelper.narrow (orb.string_to_object (loginIOR)); Note that when you get an object reference using the JNDI InitialContext lookup() method, you do not have to call the helper narrow() method. The ORB calls it automatically for you.
_st_Hello	The generated files that have _st_ prefixed to the interface name are the stub files or client proxy objects. (_st_ is a VisiBroker-specific prefix.) These classes are installed on the client that calls the remote object. In effect, when a client calls a method on the remote object, it is really calling into the stub, which then performs the operations necessary to perform a remote method invocation. For example, it must marshall parameter data for transport to the remote host.
_HelloImplBase	Generated source files of the form _<interfaceName>ImplBase are the skeleton files. A skeleton file is installed on the server and communicates with the stub file on the client, in that it receives the message on the ORB from the client and upcalls to the server. The skeleton file also returns parameters and return values to the client.
HelloOperations _tie_Hello	The server uses these two classes for Tie implementations of server objects. See "Using the CORBA Tie Mechanism" for information about Tie classes.
_example_Hello	The _example_<interfaceName> class provides you with a template for your server object implementation. You can copy the example code to the directory where you will implement the Hello server object, rename it, (HelloImpl.java is used in the examples in this Guide), and implement the methods.

IDL Interface Body

An IDL interface body contains the following kinds of declarations:

types	Type definitions.
exceptions	Exception structures that the interface exports.
attributes	Any associated attributes exported by the interface.
operations	Operations are the methods that the interface supports.

IDL Types

This section gives a brief description of IDL datatypes and their mapping to Java datatypes. For more information about IDL types not covered here, see the CORBA specifications and the books cited in "For More Information".

Basic Types

Mapping between IDL basic types and Java primitive types is straightforward. Table 2-1 shows the mappings, as well as possible CORBA exceptions that can be raised on conversion.

Table 2-1 IDL to Java Datatype Mappings

CORBA IDL Datatype	Java Datatype	Exception
boolean	boolean
char	char	CORBA::DATA_CONVERSION
wchar	char
octet	byte
string	java.lang.String	CORBA::MARSHAL
		CORBA::DATA_CONVERSION
wstring	java.lang.String	CORBA::MARSHAL
short	short
unsigned short	short
long	int
unsigned long	int
long long	long
unsigned long long	long
float	float
double	double

The IDL character type char is an 8-bit type, representing an ISO Latin-1 character that maps to the Java char type, which is a 16-bit unsigned element representing a Unicode character. On parameter marshalling, if a Java char cannot be mapped to an IDL char, a CORBA DATA_CONVERSION exception is thrown.

The IDL string type contains IDL chars. On conversion between Java String, and IDL string, a CORBA DATA_CONVERSION can be thrown. Conversions between Java strings and bounded IDL string and wstring can throw a CORBA MARSHALS exception if the Java String is too large to fit in the IDL string.

Constructed Types

Perhaps the most useful IDL constructed (aggregate) type for the Java developer is the struct. The IDL compiler converts IDL structs to Java classes. For example, the IDL specification:

module employee {
  struct EmployeeInfo {
    long empno;
    wstring ename;
    double sal; 
  };
  ...

causes the IDL compiler to generate a separate Java source file for an EmployeeInfo class. It looks like this:

package employee;
final public class EmployeeInfo {
  public int empno;
  public java.lang.String ename;
  public double sal;
  public EmployeeInfo() {
  }
  public EmployeeInfo(
    int empno,
    java.lang.String ename,
    double sal
  ) {
    this.empno = empno;
    this.ename = ename;
    this.sal = sal;
  }
 ...

The class contains a public constructor with parameters for each of the fields in the struct. The field values are saved in instance variables when the object is constructed. Typically, these are passed by value to CORBA objects.

Collections

The two types of ordered collections in CORBA are sequences and arrays. An IDL sequence maps to a Java array with the same name. An IDL array is a multidimensional aggregate whose size in each dimension must be established at compile time.

The ORB throws a CORBA MARSHAL exception at runtime if sequence or array bounds are exceeded when Java data is converted to sequences or arrays.

IDL also generates a holder class for a sequence. The holder class name is the sequence's mapped Java class name with Holder appended to it.

The following IDL code shows how you can use a sequence of structs to represent information about employees within a department:

module employee {
  struct EmployeeInfo {
    long empno;
    wstring ename;
    double sal; 
  };

  typedef sequence <EmployeeInfo> employeeInfos;

  struct DepartmentInfo {
    long deptno;
    wstring dname;
    wstring loc;
    EmployeeInfos employees;
  };

The Java class code that the IDL compiler generates for the DepartmentInfo class is:

package employee;
final public class DepartmentInfo {
  public int deptno;
  public java.lang.String dname;
  public java.lang.String loc;
  public employee.EmployeeInfo[] employees;
  public DepartmentInfo() {
  }
  public DepartmentInfo(
    int deptno,
    java.lang.String dname,
    java.lang.String loc,
    employee.EmployeeInfo[] employees
  ) {
    this.deptno = deptno;
    this.dname = dname;
    this.loc = loc;
    this.employees = employees;
  }

Notice that the sequence employeeInfos is generated as a Java array EmployeeInfo[].

Specify an array in IDL as follows:

const long ArrayBound = 12;
typedef long larray[ArrayBound];

The IDL compiler generates this as:

public int[] larray;

When you use IDL constructed and aggregate types in your application, you must make sure to compile the generated .java files and load them into the Oracle8i database when the class is a server object. You should scan the generated .java files, and make sure that all required files are compiled and loaded. Study the Makefile (UNIX) or the makeit.bat batch file (Windows NT) of CORBA examples that define these types to see how the set of IDL-generated classes is compiled and loaded into the data server.

Exceptions

You can create new user exception classes in IDL with the exception key word. For example:

  exception SQLError {
    wstring message;
  };

The IDL can declare that operations raise user-defined exceptions. For example:

interface employee {
  attribute name;
  exception invalidID {
    wstring reason;
  };
  ...
  wstring getEmp(long ID)
    raises(invalidID);
  };
};

CORBA System Exceptions

Mapping between OMG CORBA system exceptions and their Java form is also quite straightforward. These mappings are shown in Table 2-2.

Table 2-2 CORBA and Java Exceptions

OMG CORBA Exception	Java Exception
CORBA::PERSIST_STORE	org.omg.CORBA.PERSIST_STORE
CORBA::BAD_INV_ORDER	org.omg.CORBA.BAD_INV_ORDER
CORBA::TRANSIENT	org.omg.CORBA.TRANSIENT
CORBA::FREE_MEM	org.omg.CORBA.FREE_MEM
CORBA::INV_IDENT	org.omg.CORBA.INV_IDENT
CORBA::INV_FLAG	org.omg.CORBA.INV_FLAG
CORBA::INTF_REPOS	org.omg.CORBA.INTF_REPOS
CORBA::BAD_CONTEXT	org.omg.CORBA.BAD_CONTEXT
CORBA::OBJ_ADAPTER	org.omg.CORBA.OBJ_ADAPTER
CORBA::DATA_CONVERSION	org.omg.CORBA.DATA_CONVERSION
CORBA::OBJECT_NOT_EXIST	org.omg.CORBA.OBJECT_NOT_EXIST
CORBA::TRANSACTIONREQUIRED	org.omg.CORBA.TRANSACTIONREQUIRED
CORBA::TRANSACTIONROLLEDBACK	org.omg.CORBA.TRANSACTIONROLLEDBACK
CORBA::INVALIDTRANSACTION	org.omg.CORBA.INVALIDTRANSACTION

Getting by Without IDL

The Oracle8i JVM development environment offers the Inprise Caffeine tools, which enable development of pure Java distributed applications that follow the CORBA model. You can write your interface specifications in Java and use the java2iiop tool to generate CORBA-compatible Java stubs and skeletons.

Developers can also use the java2idl tool to code in pure Java, yet still have IDL available that can be shipped to customers who are using a CORBA server that does not support Java. This tool generates IDL from Java interface specifications.

See the Oracle8i Java Tools Reference, for more information about java2iiop and java2idl.

---