Chapter 2
Compilation of IDL and Java

2.1 Using the IDL Compiler
2.2 Compiling OrbixWeb Programs

This chapter explains how to run the OrbixWeb IDL compiler and discusses the compilation of:

IDL source code.
OrbixWeb programs (applications and applets).

2.1 Using the IDL Compiler

The OrbixWeb IDL compiler checks the validity of IDL specifications and maps those specifications to the Java programming language. The following sections describe the steps needed to configure and run the IDL compiler.

2.1.1 Configuration

Before running the IDL compiler you must ensure that OrbixWeb can find its configuration file, Orbix.cfg. On UNIX systems, this file will be automatically located if it has been installed in the /etc directory. If however it is not installed there, or the compiler is running on Windows 95 or Windows NT, then you must set the environment variable IT_CONFIG_PATH to point to it. By default, Orbix.cfg is placed in the OrbixWeb installation directory.

The OrbixWeb configuration file is usually configured during installation. The contents of the file are described in Chapter 3, "OrbixWeb Configuration".

2.1.2 Running the IDL Compiler

The OrbixWeb IDL compiler is invoked by the command idl. It takes one parameter–the name of the IDL file. The extension for this file must be .idl. However, when compiling it is not necessary to specify the .idl extension.

For example, an input file BANK.idl could be compiled with the following command:

 idl BANK

or as follows:

 idl BANK.idl

The IDL compiler maps the IDL definition to Java source code as described in Chapter 5, "IDL to Java Mapping" of the OrbixWeb Programming Guide. The IDL compiler output is structured in accordance with Java conventions for mapping public classes to individual source files and mapping packages to a directory structure.

By default, the IDL compiler maps global IDL definitions to Java definitions in the global package. Also by default, the compiler output is redirected to a local directory named java_output. Both these functional characteristics can be configured (with the -jP and -jO switch, respectively), but we will examine the default case first.

Consider the following simple IDL file:

 // IDL
 // in file Cust.idl
 interface Customer {
 	void setCustomerName (in string name);
 	void getCustomerName (out string name);
 };

This file could be compiled as follows:

 idl Cust

This would result in the generation of the file structure shown in Figure 2.1.

Figure 2.1: Default file structure output by IDL compiler

Of course, the generation of Java class definitions directly into the global package has the potential to cause naming clashes. Therefore, when compiling IDL it is often desirable to specify a package name into which all generated Java definitions are placed. The IDL compiler -jP switch supports this functionality.

For example, if we want the definitions generated from Cust.idl to be scoped within the package COM.Company.internal, we can use the following command:

 idl -jP COM.Company.internal Cust

As a result of this command, the IDL compiler will generate the file structure illustrated in Figure 2.2.

Figure 2.2: File structure resulting from use of -jP switch

The IDL command line can accept a series of -jP switches of the following form:

 idl -jP <package> -jP <IDL module>=<package>
 	<IDL module=package> ...

A command line of this format indicates that IDL types defined in the target IDL file should be mapped to the main -jP package, but that the specified modules, which are only referenced in the target IDL file are actually located in other, existing Java packages.

For example, take the following IDL file:

 // IDL
 // In file CustomerTypes.idl
 module CustomerTypes {
 	interface Customer {
 		...
 	};
 };

Now, assume that this definition is compiled with the following command:

 idl -jP CustomerPackage CustomerTypes.idl

All generated types for this IDL file will be scoped by the package CustomerPackage. Now, a second IDL file is written as follows:

 // IDL
 // In file BankTypes.idl
 # include "CustomerTypes.idl"
 
 module BankTypes {
 	interface Bank {
 		CustomerTypes::Customer getCustomer ();
 	};
 };

If this file were compiled with a single -jP switch, then the target Java package name would need to be CustomerPackage, to satisfy the IDL generated references to the Java types for interface Customer. To avoid this restriction, the -jP switch can be used with an alternative package value for module CustomerTypes, as follows:

 idl -jP BankPackage 
 	-jP CustomerTypes=CustomerPackage BankTypes.idl

Another issue associated with IDL output is the top level target directory for generated files. The local directory java_output is not always the desired target for the IDL output file structure, so the IDL compiler allows an alternative to be specified. This can be done by invoking the compiler with the -jO switch, followed by the new output directory name.

2.1.4 IDL Compiler Switches

The IDL compiler supports the following command line switches:

`-A`	Required if the IDL file contains the definition of a `struct`, `union`, `sequence`, or object reference, an instance of which may be passed to a parameter of type `any`. By default, the IDL compiler will not produce code required for the correct insertion / extraction of an `any` value of such user-defined types. (The structs defined by the Interface Repository can be passed as a component of a parameter of type `any` without specifying the `-A` switch.)
`-C`	Specify to the OrbixWeb IDL pre-processor that it should not filter out comments; comments are filtered out by default. This switch is often used with `-E`.
`-D <name>`	Predefine the macro `name` to be `1` within the IDL file.
`-D <name>=`<definition>	Predefine the macro `name` to be `definition`.
`-E`	Only run the OrbixWeb IDL pre-processor. Do not pass the output of the pre-processor to the OrbixWeb IDL compiler, but output the pre-processed file to the standard output. By default, the output of the OrbixWeb IDL pre-processor is sent to the OrbixWeb IDL compiler.
`-I <directory>`	Specify an include file directory for use with IDL include directives of the form `#include<filename>`. More than one `-I` switch can be given.
`-N`	Specifies that the IDL compiler is to compile and produce code for included files (files included using the `#include` directive). Without the `-N` switch, included files are compiled but no code is output. The use of the `-N` flag is not encouraged as it complicates the use of the Interface Repository. (It also has the restriction that the compilation must be invoked from the same directory as the root IDL file in order to retain compatibility with the Interface Repository server.) Care must also be taken when using this switch with the `-d` switch. Otherwise, a source tree may not fit entirely into the Interface Repository directory (specified by `IT_INT_REP_PATH`) and may overwrite existing IDL (and shadow) files.
`-jO <directory>`	Specifies a target directory for the file structure output by the IDL compiler. The directory path may be absolute or relative.
`-jc`	Generates support for client-side functionality only. By default, the IDL compiler generates both client-side and server-side support, which involves the creation of several server-specific source files which are not required by client programmers. This switch suppresses the generation of such files.
`-jP [<package> \|` <module>=<package>]	Specifies a Java package name within which all IDL generated Java code is placed, or an IDL module which should be mapped to a specific package name. By default, generated code is placed within the global package, so the use of this switch is generally recommended in order to avoid naming clashes.
`-jQ`	Generates support for the `equals()` method in all IDL produced Java classes.
`-R`	Generates support for use of the Interface Repository. The Interface Repository takes a copy of the IDL file, using the same file name, into its own directory (either directly into that directory, or into a sub-directory if the `-d` switch is specified). The Interface Repository's directory is specified by `IT_INT_REP_PATH`. If used in conjunction with the `-N` switch, included files are also copied into the Interface Repository. Currently, the operating system's normal file deletion commands must be used to remove the files created within the Interface Repository's directory and subdirectories.
`-U <name>`	Undefine the macro `name`. If `-U` is specified for a macro name then that macro name will not be defined even if `-D` is used to define it.
`-d <dir>`	Used in conjunction with the `-R` flag to specify the sub-directory of the Interface Repository directory (specified by `IT_INT_REP_PATH`) in which the copy of the IDL file is to be stored. The pathname `dir` must be a relative pathname; it is created if necessary. The default is to store the IDL file in the root directory of the Interface Repository. Users should use the `-d` switch to avoid overriding copies of other IDL files having the same name. When used in conjunction with the `-N` flag, users should be warned that if the IDL source file includes files using absolute rather than relative pathnames, then the files cannot be copied. In general, use of the `-N` switch is discouraged.
`-f`	Do not suppress code generation for `sequence<octet>` and `sequence<string>` types. These are normally suppressed because their implementation code is included in the `IE.Iona.Orbix2.CORBA` package. This switch is rarely needed.
`-m <protocol>`	Generates marshalling code which uses the marshalling protocol specified in `protocol`. Acceptable protocol values are `IIOPOnly`, `orbixOnly` and `interOp`. The value `IIOPOnly` generates marshalling code for the CORBA Internet Inter-ORB Protocol (IIOP) only, `orbixOnly` generates marshalling code for the Orbix communications protocol only and `interOp` generates support for both. The default protocol setting is `IIOPOnly`.
`-v`	Output version information for the IDL compiler.