idldepend - an ANT CORBA task

• Description
• License and download
• Version and CORBA compliance:1.10 version delivered the 12th December 2006
• Attributes
• Nested elements
• Example
• Behaviour
  • Using the preprocessor
  • Using package and translate
  • Invoking the idl compiler
  • Translation of compiler arguments
    • JDK / IBM
    • Orbacus
    • Jacorb
    • OpenORB
    • Orbix
  • Additional notes
• Troubleshooting
• History changes
• Bugs and limitations

Description

idldepend is an ant task verifying the dependencies of a CORBA/IDL file.

It parses the file, verifying the Java files that must be generated, taking in account the modifications that can happen due to command line parameters. If any of the Java files is missing or is older than the source IDL specification, it launches the specified compiler, being correctly supported those coming with Orbacus, Orbix, Jacorb, OpenORB, IBM and Sun'JDK distributions.

To speed up the process and avoid parsing unnecesarily the same files continuously, it keeps the dependencies into intermediate files.

This task does not launch the Java compiler, that is, its output are Java files and not directly the final bytecode.

License and download

idldepend is delivered as it, without any responsabilities on the author. It is open source, it can be used or modified without any limitations.

This task has been on use since September 2001, and its first public release was in December 2002, with 24 public deliveries before reaching version 1.0. As idldepend is a wrapper around several IDL compilers, it needs to continuosly evolve, following the changes that those compilers implement.

If some bug is found or the behaviour is not exactly the shown by the compiler, please send me a mail (java_lmp@yahoo.co.uk) and I will promptly introduce the modifications. In any case, the task is distributed with source, and therefore you can make by your own any changes.

Following are the downloadable files.

• Version 1.10. Latest version, (12/12/06).
  • Source code (.zip format, 140.098 bytes), to be built using ant: idldepend-1-1-0.zip
  • Binary code (.jar file, 226.714 bytes): idldepend-1-1-0.jar

Previous available versions:

• Version 1.00 (09/11/06). idldepend-1-0-0.zip and idldepend-1-0-0.jar
• Version 0.81 (28/09/05). idldepend-0-8-1.zip and idldepend-0-8-1.jar

In case of using the source code, you need to have Ant (to build the task) and JavaCC (only if modifying the grammars, to parse them). Please modify the ant script to define your own JavaCC home directory, and compile it just entering 'ant'.

Version and CORBA compliance

Current version, since the 12th December 2006, is 1.10. Initially built using Ant 1.4, the current version has been tested against Ant 1.6.5; please note that I do not regularly check if it works under other Ant versions (but I would be surprised if not).

idldepend is compliant with the IDL to Java mapping defined for CORBA 2.4. Support for the mapping 1.2 -CORBA 3.0 compliant- is not immediately foreseen: it will be introduced when a CORBA distribution with Java mapping finally supports it.

In particular, the following keywords are not supported:

• component
• consumes
• finder
• home
• emits
• eventtype
• getraises
• import
• multiple
• primarykey
• provides
• publishes
• setraises
• typeid
• typeprefix
• uses

Note that all these keywords have been added with CORBA 3.0, and, by now, I have not knowledge of any ORB with Java mapping supporting them.

idldepend supports the grammar defined by the OMG; it raises no warnings or errors even if the used compiler does not support some used features. For example, a valid IDL file could contain proper local interface definitions, which are not supported by the JDK compiler. idldepend will only warn about incorrect IDL constructs.

Task's Attributes

Nested Elements

Example

Behaviour

Using the preprocessor

idldepend can store the preprocessed file (the IDL file after the C preprocessor parses it), and even use it to generate the Java files. This feature is very valuable for those IDL compilers that lack a full-featured preprocessor (Jacorb has problems with basic macros, and the jdk compiler has as well problems with basic preprocessing functionality, like macros defined across several lines).

This functionality is specified with the attribute preprocess, which can have the following values:

• dismiss:
  • The preprocessed file is not stored.
• store:
  • The preprocessed file is stored, in the same directory as the dependencies (specified with the attribute dependsdir).
  • This file has the same name as the original, plus a 4-digits hexadecimal number, plus '.idl'. The number is the same as used for the dependencies, and it is unique for each file.
  • This file is not fully expanded: the #include directives are kept (but with the files to be included written with its absolute path).
  • If the attribute force is set to true, no preprocessed file is generated.
• storeFull:
  • The preprocessed file is stored, like it is done in case of store
  • This file is fully expanded: the #include directives are handled, including therefore the related file into the preprocessed file, like any C preprocessor would do.
  • If the attribute force is set to true, no preprocessed file is generated.
• use:
  • The preprocessed file is stored, like it is done in case of store
  • This file is not fully expanded, like it is explained for store
  • The preprocessed file is used as input for the IDL compiler; hereby the need to avoid a full expansion, as the IDL compiler would generate otherwise the Java files for all the encountered types.
  • If the attribute force is set to true, the preprocessed file is still generated.
• useFull:
  • The preprocessed file is stored, like it is done in case of store
  • This file is fully expanded, like it is explained for storeFull
  • The preprocessed file is used as input for the IDL compiler; note that in this case, the compiler will generate Java code for all the types found in the included files. Therefore, the attribute checkAll looses his meaning if this value is used.
  • If the attribute force is set to true, the preprocessed file is still generated.

Using package and translate

These modifiers affect to the packages under which the final Java files are generated. For example: package moduleA prefixA.prefixB converts the file moduleA/moduleB/file.java into prefixA/prefixB/moduleB/file.java The result of these modifications is not fully specified. idldepend just performs the translations made by the specific compiler, and each compiler behaves quite different.

For example, when translate is used on the jdk compiler, it only affects to top-level modules, while under jacorb it modifies any given module; and this modifier is not applicable for orbacus.

Following is a brief description of its behaviour. In case of doubt, check directly the compiler:

• Package
  • jdk
    • equivalent to modifier -pkgPrefix.
    • module and prefix are mandatory, and auto is not supported.
    • module affects only to the top level module
    • prefix can be compound. I.e, it's possible to specify packageA.packageB
    • It is applied before any translate modification.
  • orbacus
    • equivalent to modifiers --package, --prefix-package and auto-package.
    • if auto is specified, no other attribute can be present. It is equivalent to --auto-package
    • if only prefix is specified, it is equivalent to --package, with priority over any auto modifier
    • if module is specified, prefix must be specified as well, being in this case equivalent to --prefix-package: it has priority over --package
  • jacorb
    • In version 1.x, it is equivalent to modifier -p
    • In version 2.x, it is equivalent to modifier -i2jpackage :prefix. To handle the difference with version 1.x, the compiler attribute must be set as jacorb2 instead of jacorb
    • it only supports the prefix modifier.
    • it's applied after any translate modification
  • openorb
    • equivalent to modifier -package
    • Important:if package is used when compiling more than one idl files, openORB will behave differently if these files are passed once by once than when they are passed all at once! For this reason, when the combination openORB + package modifier is used, it is convenient to pass the parameter callCompiler=onceWithAll
  • orbix
    • The prefix is always required, while module is optional and the auto modifier not supported.
    • if no module is specified, it is equivalent to the Orbix parameter -P prefix
    • if the module is specified, it is equivalent to the Orbix parameter -Pmodule=prefix
    • If several matching packages are specified, it is only used the last one.
• Translate
  • jdk
    • equivalent to modifier -pkgTranslate.
    • module and package are mandatory
    • module affects only to the top level modules
    • prefix can be compound. I.e, it's possible to specify packageA.packageB
    • It is applied after any package modification.
    • If two translates are specified affecting the same module:
      • If both translates have the same module name, only the second one remains.
      • Otherwise, the translate with a more specific module name will be applied first.
  • orbacus
    • Not supported
  • jacorb
    • equivalent to modifier -i2jpackage.
    • module and package are mandatory
    • module affects to any module in the type. It must be simple, i.e, moduleA.moduleB is not valid
    • prefix can be compound. I.e, it's possible to specify packageA.packageB
    • It is applied before any package modification.
  • openorb
    • Not supported
  • orbix
    • Not supported

Invoking the IDL compiler

A number of attributes and nested elements control how the IDL compiler will be invoked from idldepend. Of course, every single attribute or element modifies the way the IDL compiler is called, adding or modifying the parameters passed to it; this section refers to which compiler is invoked and how the idl files are passed.

Which compiler is invoked is specified via the attributes compiler and compilerPath, and nested elements classpath and path. How the idl files are passed to the compiler is handled via the callCompiler attribute. From these, only this last attribute requires a deeper explanation:

• If callCompiler is set to foreach, each idl file is compiled separately. This is the default behaviour for two reasons:
  • It was the only mode existing before version 0.53
  • Some compilers only supports this mode (like JDK or IBM)
• If callCompiler is set to once, the compiler is only invoked once, passing all the idl files that require compilation.
  • It should increase the performance, on those compilers that support it.
  • It is mandatory in some cases. In special, for the OpenORB compiler, it behaves differently compiling two files sequentially or at once, when the package elements are used.
• If callCompiler is set to onceWithAll, the compiler is only invoked once. The main difference with once is that, if idldepend identifies that at least once idl file must be compiled, the compiler will be invoked with ALL the idl files, not only those requiring compilation.
  • Obviously the performance will be worse.
  • It is mandatory in some cases. In special, for the OpenORB compiler, as it behaves differently compiling files sequentially or at once, it can be required to pass all the files on every compilation.

The callCompiler functionality has been introduced to deal with the OpenORB compiler, though it could be useful with other compilers as well. The OpenORB compiler contains currently a bug: if file a.idl includes the file b.idl and both are passed at once to the idl compiler, OpenORB will not generate the code for the types found in b.idl if it is passed in the command line after a.idl.
To work around this bug, idldepend will reorder the idl files, passing first those without dependencies to the others (currently, there are no mechanisms to disable this reordering)

Translation of compiler arguments

Below is listed the translation of compiler arguments into the task parameters for the supported compilers.

The lists are given following the compiler order. When a parameter is not supported, is explicitely writen. Note that the args parameter in the task allows to specify any other parameter, but in that case the task can become useless. When a parameter is not directly supported but it can still be specified using the args parameter without any problem, it is as well explicitely writen.

JDK (as to 1.4.0) and IBM JDK (3.0)

Orbacus (as to 4.1.0)

Jacorb (as to 1.4.1 and 2.3)

OpenORB (as to 1.3 and 1.4)

Orbix (2000)

Please note that for this compiler, only the directly supported arguments are specified.
If no present in the table but still required, the args task attribute can be used.

In addition, if an argument is added via arg and this argument must be embedded in jbase or jpoa, like is the case for arguments starting by -P, -O, -G, -M, -J, -V, -F, the addition is handled automatically by idldepend, i.e., it is not required to add explicitely jbase or jpoa.

Additional notes

• The idldepend grammar supports empty module definitions. The OMG specification declares that an empty module -that is, containing no nested definitions- is invalid; however, compilers like JDK allow it, and there is no reason for IdlDepend to stop the compilation.
• idldepend supports empty files (IDL files not defining types). In this case, IDLdepend will not fail, and it depends on the IDL compiler to handle them or fail, as the OMG IDL grammar does not allow those files.
• idldepend supports the non-standard pseudo keyword.
  This keyword is used to define a pseudo object in the JacORB compiler; it is not standard OMG/IDL at all, and it is not supported in the other compilers (JDK / IBM / OpenORB).
  In the JacORB compiler, it generates a simple abstract class for the given interface (pseudo interface Example {} will generate the class Example.java at current scope, without added helpers or holders).
• idldepend defines in the same way the constructs: "#ifdef __FOO__", "#if defined(__FOO__)", and "#if defined __FOO__ "
  Note that the IDL compiler can still handle them in different form; in special, the JDK compiler treats the second one as a macro to be expanded.
• Handling circular dependencies, idldepend fixes a limit on the recursion: if a file is included 400 times (without being completed its inclusion), it reports an error. This is usually due to a wrong circular dependency.

Troubleshooting

In case of errors, the fastest way to verify what is happening is to make idldepend verbose, using the attribute verbose=debug.

• idldepend does not report obvious IDL errors.
  idldepend performs exclusively a grammar check, and some errors cannot be verified. For example, an operation void foo(in short long) is an obvious error, but under a syntax check it just means the use of a variable called long
• idldepend reports as erroneous an IDL file that is perfectly parsed by the ORB.
  Please send me the file to check the error.
• idldepend launches always the IDL compiler, even when no new files must be generated
  Please verify that dependency files are generated (attribute force=yes not defined). These files are generated in the directory given by the dependsdir attribute.
  In the directory with the dependencies, idldepend stores a file for each parsed IDL file; this file has the same name as the IDL file, adding a 4-digits hexadecimal number, and the extension .depends In this file, each line but the last one is prependend with:
  • <: the rest of the line contains the name of a file referenced by the current file.
    If the referenced file changes (its timestamp changes), this IDL file must be re-parsed.
  • >: the rest of the line contains the name of a file generated from the current IDL file.
    If this file is older that the current IDL file or does not exist, it is needed to parse again the IDL file to re-generate any depending files.
  By checking the content of this file, you can verify why idldepend is re-launching the idl compiler; in most of the cases, because some file-to-be-generated is missing. If this is not the case, please send me the idl file to verify its behaviour.

History changes

Bugs and Limitations

• CORBA compliance support
  Please look to the section above, to check the current compliance.
• JDK
  If the JDK IDL compiler fails, idldepend will not fail, and the ant task using idldepend will show: BUILD SUCCESSFUL. Unfortunately, this is a limitation on the JDK IDL compiler: when it fails, does not return a error code.
• Performance
  The main limitation of idldepend is currently its performance: it must duplicate most of the work that the compiler does to generate the files and therefore it can be expected it to require double the time that the compiler needs.
  In fact, using the JDK compiler, it requires for long files with deep and recursive includes up to six times more. This time is only required for the first time, as the following times that idldepend is executed, it uses the created dependency files and then it is faster than the compiler (it doubles it speed).
  That is, on its first execution, idldepend is much slower than using directly the IDL compiler, but following executions are faster than using the compiler. (and if there are no changes, it avoids of course the compilation of the generated .java files!).
  This performance is due to the little experience I have with parsers. If you feel more confortable with it, feel free to improve it!
• ORBs support
  I included support initially for JDK, Jacorb, OpenORB and Orbacus ORBs. The support for Orbix was included afterwards by Jeff Downs.
  Since then, most of the changes in idldepend have been the result of added functionality -like the preprocessor-, or to solve reported bugs. In special, I have not tracked the IDL compilers to verify new command line options. As a result, it is possible that the ORB version you are using it is not perfectly supported by idldepend. If this is the case, please report me the change(s) to enhance this program.