Using idltojava (Early Access Beta)

DESCRIPTION

The tool idltojava generates Java source code files from an IDL file. For example, if you run idltojava on the following hello.idl file 

module HelloApp
{
	interface hello
	{
		//...operation and exception declarations....	
	}
};
with the command, 
	> idltojava hello.idl
the following .java files will be generated in a HelloApp directory:

IDL statements are translated to Java code according to the Object Management Group (OMG) specification IDL Java Mapping 1.0.

In order to use the files generated by idltojava, you need to run javac on them and include the generated .class files in your CLASSPATH.

SYNTAX

 
idltojava [ options | flags ] filename.idl . . .
 
 

You can give idltojava two types of command line arguments, options and flags, both of which are optional. The order of flags and options does not matter with respect to each other, but they must go before the file to which they apply. Note that the following examples illustrate what is possible and are not necessarily what is recommended.

For instance, the first example below demonstrates turning the flag write-files off for the file hello.idl and then turning it back on for the file port.idl. If you were to call idltojava the two files in separate commands, there would be no need to turn the flag write-files on for the file port.idl because flags are reset to the defaults each time idltojava is invoked, and the default is for it to be on. Or, if you supplied port.idl as the first argument to idltojava, you would likewise not need to turn on the write-files flag since it would already be on by default. The following shows three different ways to write the same thing: 

	> idltojava -fno-write-files hello.idl -fwrite-files port.idl

	> idltojava -fno-write-files hello.idl
	> idltojava  port.idl

	> idltojava port.idl -fno-write-files hello.idl

The following examples show using more than one flag and combining options and flags: 

	> idltojava -fno-cpp -fcaseless hello.idl -fverbose -fcpp port.idl


	> idltojava -I/usr/local/lib -fno-write-files hello.idl -fwritefiles port.idl

	> idltojava -I/usr/local/lib -fno-write-files -Dminimum=128 hello.idl \
		-Ustandard -fwritefiles port.idl

OPTIONS

Options are used to pass some environment-specific information to idltojava. Three of the options deal with preprocessor directives:

All three tell idltojava to pass on information to the preprocessor.

These are the options you can use with idltojava:

-j javaDirectory
Specifies that generated Java files should be written to the given javaDirectory. Note that there must be a space between -j and the directory name. Also, you must create the directory before specifying it in this option.

Example usage: 

	> idltojava -j myApps filename.idl
-I directoryName
Tells idltojava to pass on to the preprocessor the information that the directory directoryName is the place to search for the files in #include directives contained in the IDL file.

Example usage: (The preprocessor is told to look in the directory /usr/dist/lib to find the files in #include statements in filename.idl.) 

	> idltojava -I/usr/dist/lib filename.idl
-D symbol
Specifies that symbol be defined during preprocessing of the IDL file(s).

Example usage: 

	> idltojava -Dmaximum=256 filename.idl
-U symbol
Specifies that symbol be undefined during preprocessing of the IDL files.

Example usage: 

	> idltojava -Umaximum filename.idl

FLAGS

Flags give instructions to idltojava and can be turned on or off.

To turn on a flag, use: 

	> idltojava -fflag-name

For example, the following directs idltojava to print a list giving the current state of each flag: 

	> idltojava -flist-flags hello.idl

To turn off a flag, use: 

	> idltojava -fno-flag-name

The following line directs idltojava not to use the C/C++ preprocessor before compiling the IDL file hello.idl 

	> idltojava -fno-cpp hello.idl

Each flag is set to a default value. Turning a flag off when it is already off does nothing; similarly, turning a flag on when it is already turned on does nothing.

The following flags are ON by default:

The following flags are OFF by default:

If you run idltojava on an IDL file and supply no flags, idltojava will run the C/C++ preprocessor on the IDL file, will produce a portable client stub file, will produce a portable server skeleton file, will consider case when comparing identifiers, and will write out the .java files it produces.

These are the flags you can use with idltojava:

-f caseless
When ON, requests that capitalization NOT be considered in the comparison of identifiers. Default: OFF. In other words, the default behavior of the idltojava compiler is to consider case when comparing identifiers. To tell idltojava not to consider uppercase and lowercase, use -fno-caseless, as in the following example: 
	> idltojava -fno-caseless hello.idl

-f client
When ON, requests the generation of the client side of the IDL files supplied. Default: ON

-f cpp
When ON, runs the C/C++ preprocessor on the IDL file supplied. Default: ON

Note:

idltojava is hard-coded to use a default preprocessor. On Solaris machines, it uses the path /usr/ccs/lib/cpp when looking for the preprocessor. On Wintel machines, it is hard-coded to use the MS Visual C++ preprocessor. You can change the preprocessor that idltojava uses by setting two environment variables:

  • CPP --set this environment variable to the full path name of the preprocessor executable you want to use.
  • CPPARGS --set this environment variable to the complete list of arguments to be passed to the preprocessor. The preprocessor needs to write to standard output, so if it does not do so by default, you should include the argument appropriate to your preprocessor to accomplish that.

Examples for Wintel users:

Windows 95 --in your autoexec.bat file, type something like the following: 

	> set CPP=\usr\share\lib\cpp
	> set CPPARGS=\nologo

NT --go to Control Panel-->System and click on the Environment tab; then set the environment variables

Examples for Solaris users:

C shell --in your .cshrc file, type something like 

   	> setenv CPP /usr/ccs/lib/cpp
	> setenv CPPARGS -BCY
Bourne or Korn shells --in your .profile file, type something like 
	> CPP=/usr/ccs/lib/cpp
	> export CPP
	> CPPARGS=-BCY
	> export CPPARGS

In the example above, B tells the preprocessor to support C++ style comments (// to indicate that the rest of the line is a comment), C tells the preprocessor to leave comments in the preprocessed file, and Y tells the preprocessor not to bother looking at standard input files (such as /usr/include) since they are mostly C header files.

When you run idltojava with these two environment variables set, and the flag -fcpp is ON, idltojava will automatically use the preprocessor you specified in CPP and pass it the arguments you put in CPPARGS.

-f list-flags
When ON, requests that the current state of all the -f flags be printed. Default: OFF

-f list-options
When ON, requests a list of command line options. Default: OFF

-f map-included-files
When ON, requests that Java code be generated for the IDL file and also for all the files listed in #include directives in the IDL file. Default: OFF

-f portable
When ON, requests the generation of portable stubs and skeletons. Default: ON

-f server
When ON, requests the generation of the server side of the IDL files supplied. Default: ON

-f tie
When ON, requests the generation of the Operations interface and Tie class, which are required for the implementation of a delegation-based skeleton. For the file hello.idl, idltojava will create the files _helloTie.java and _helloOperations.java. Note that this flag does nothing if the -fserver flag is turned off. Default: OFF

-f verbose
When ON, requests that idltojava print comments on the progress of the compilation. Default: OFF

-f version
When ON, requests that idltojava print its version and timestamp. Default: OFF

-f write-files
When ON, requests that the Java files that are generated be written out. idltojava will create a directory named after the module for the .idl file and put the .java files in it. This new directory will be in the same directory as the .idl file. Turning the flag off allows the programmer to validate the IDL code before writing out the generated Java files. Default: ON

USING #pragma

  Java IDL supports #pragma as shown below. Note that a #pragma directive must appear at the beginning of an IDL file so that it has global scope.
  • To request a repository prefix.

    	> #pragma prefix "requested_prefix_name"
  • To wrap the default package in one called "package". 
    	> #pragma javaPackage "package"

    For example, compiling an IDL module "M" normally creates a Java package "M". If the module declaration is preceded by the directive 

    	> #pragma javaPackage "browser"

    the compiler creates the package "M" inside package "browser". This pragma is useful when the definitions in one IDL module are used in multiple products.

Copyright © 1996, 1997 Sun Microsystems, Inc., 2550 Garcia Ave., Mtn. View, CA. 94043-1100 USA., All rights reserved.