The IDL-Java bridge must be configured before Java objects can be created and used within IDL. IDL initializes the bridge when it first attempts to create an instance of IDLjavaObject. Initializing the bridge involves starting the Java Virtual Machine and creating any internal Java bridge objects (both C++ and Java) including the internal IDLJavaBridgeSession object.
When an IDLjavaObject is created, the IDL-Java bridge loads configuration information from a file named
- .idljavabrc on UNIX and Mac systems
- idljavabrc on Windows systems
Note: The IDL-Java bridge only reads the configuration file once during an IDL session.
The file is read when the first instance of the IDLjavaObject class is created in the session. If you change the configuration after the first instance is created, you must exit and restart IDL to update the IDL-Java bridge with the changes.
The following sections discuss the location, contents, and use of the configuration file:
Location of the Bridge Configuration File
The IDL-Java bridge looks for the configuration file in the following order:
- If the environment variable IDLJAVAB_CONFIG is set, IDL uses the file it specifies.
Note: This environment variable must include both the path and the file name of the configuration file.
- If the IDLJAVAB_CONFIG environment variable is not set or the file indicated by that variable is not found, the path specified in the HOME environment variable is used to try to locate the configuration file.
- On Windows systems, if the HOME environment variable is not set or the IDL- Java bridge configuration file is not found in the specified location, the path specified in the USERPROFILE environment variable is used to try to locate the configuration file.
- If the file is not found in the above-listed locations, IDL looks in the <IDL_DEFAULT>/resource/bridges/import/java directory to locate the default configuration file.
Note: The IDL installer attempts to create a valid default configuration file based on IDL location. The default file should be verified before trying to create and use Java objects within IDL.
Contents of the Bridge Configuration File
The configuration file contains the following settings. With a text editor, open your configuration file to verify these settings are correct for your system.
JVM Classpath
The JVM Classpath setting specifies additional locations for user classes. It must point to the location of any class files to be used by the bridge. On Windows, paths should be separated by semi-colons. On UNIX, colons should separate paths.
This path may contain folders that contain class files or specific jar files. It follows the same rules for specifying ’-classpath’ when running java or javac. You can also include the CLASSPATH environment variable in the JVM Classpath:
JVM Classpath = $CLASSPATH:/home/johnd/myClasses.jar
which allows any class defined in the CLASSPATH environment variable to be used in the IDL-Java bridge.
On Windows, an example of a typical JVM Classpath setting is:
JVM Classpath = E:\myClasses.jar
On UNIX, an example of a typical JVM Classpath setting is:
JVM Classpath = /home/johnd/myClasses.jar:$CLASSPATH
JVM LibLocation
The JVM LibLocation setting tells the IDL-Java bridge which JVM shared library to use. Various versions of Java ship with different types of JVM libraries. For example, some Java installations include a “classic” JVM, a “hotspot” JVM, and a “server” JVM. Other Java versions have different JVM types.
Beginning with IDL 7.1, IDL’s default behavior is to use the JVM installed along with IDL when creating IDL-Java bridge sessions. You can select a different JVM by modifying the value of the JVM LibLocation setting or by setting the IDLJAVAB_LIB_LOCATION environment variable.
Windows
On Windows platforms, you can specify the location of the JVM shared library either by specifying the JVM LibLocation setting in the idljavabrc configuration file or by setting the IDLJAVAB_LIB_LOCATION environment variable.
The default JVM LibLocation setting looks like:
JVM LibLocation = C:\Program Files\ITT\idl71\idlde\jre\bin\server
where the server directory contains the jvm.dll library file.
Mac
On Mac platforms, IDL uses the JVM provided by the operating system, and ignores the value of the IDLJAVAB_LIB_LOCATION environment variable.
JVM Options
The JVM Option# (where # is any whole number) setting allows you to send additional parameters to the Java Virtual machine upon initialization. These settings must be specified as string values. When these settings are encountered in the initialization, the options are added to the end of the options that the bridge sets by default.
Log Location
The Log Location setting indicates the directory where IDL-Java bridge log files will be created. The default location provided by the IDL installer is /tmp on Unix and C:\temp on Windows.
Bridge Logging
The Bridge Logging setting indicates the type of bridge debug logging to be sent to a file called jb_log<pid>.txt (where <pid> is a process ID number) located in the directory specified by the Log Location setting.
Acceptable values (from least verbose to most verbose) are SEVERE, CONFIG, CONFIGFINE. The default value is SEVERE, which specifies that bridge errors are logged. The CONFIG value indicates the configuration settings are also logged. The CONFIGFINE value is the same as CONFIG, but provides more detail.
No log file is created if this setting is set to OFF.
Bridge Reset
By default, the IDL-Java bridge persists for the duration of the IDL session in which it was created. This means that modifications to items in the Java Classpath are not loaded until a new IDL session is started. The IDL-Java Bridge Reset Policy allows the IDL-Java bridge to be configured to reset when the IDL executive command .FULL_RESET_SESSION is executed.
Set the Restart Bridge setting to True to enable the recreation of the IDL-Java bridge when the .FULL_RESET_SESSION executive command is executed.
Overriding the Default Configuration
If you have multiple IDL-Java bridge applications, chances are good that you will need a different configuration for each application. In many cases, you will need to alter the CLASSPATH to load different jar files. In other cases you may even need to use different Java virtual machines. While you could manually modify the default configuration file before running different applications, it is probably easier and more convenient to maintain separate configurations for the different applications. This section describes two options for managing multiple configurations.
Option 1: Multiple Configuration Files
If you can maintain a separate configuration file for each application, your IDL application can set the IDLJAVAB_CONFIG environment variable to refer to the appropriate configuration file. Use the IDL SETENV procedure to set the value before creating the first IDLjavaObject:
SETENV, 'IDLJAVAB_CONFIG=C:\myJavaApp\idljavabrc'
oJava = OBJ_NEW(IDLjavaObject$JAVACLASSNAME, JavaClassName)
Note: On UNIX systems, you cannot specify the location of the Java virtual machine in the bridge configuration file. If you need to modify the location of the Java virtual machine, you must also set the IDLJAVAB_LIB_LOCATION environment variable.
Option 2: Overriding Individual Environment Variables
If all of your IDL-Java bridge applications use similar configuration settings, but use different values for CLASSPATH or for the Java virtual machine, you can use a single bridge configuration file and re-set the IDLJAVAB_LIB_LOCATION and CLASSPATH environment variables individually. Again, use the IDL SETENV procedure to set the value before creating the first IDLjavaObject:
SETENV, 'CLASSPATH=C:\myJavaApp\myJavaApp.jar'
SETENV, 'IDLJAVAB_LIB_LOCATION=C:\Java\jre1.5.0_12\bin\client'
oJava = OBJ_NEW(IDLjavaObject$JAVACLASSNAME, JavaClassName)
Tip: Environment variables are specified using all upper-case letters.
Note that if you change the value of the CLASSPATH environment variable, the bridge configuration file must contain a “JVM Classpath” line, and that line must include the token $CLASSPATH:
JVM Classpath = $CLASSPATH
The $CLASSPATH token can be in any position in the path specification, but it must be present or the value of the environment variable will not be included in the classpath used by the IDL-Java bridge.