01 Nov 2001
In response to a number of programming related questions, Professor INI decided to run through all the programming related NOTES.INI variables. Last month, we looked at variables associated with LotusScript, Lotus Connectors, and the formula language. This month, we move on to variables that relate to Java and answer the question:
Q: I'm a Notes/Domino applications developer just starting to use Java. What Designer NOTES.INI variables can I use that will help me with my programming?
Java access to Domino objects (through CORBA), although not actually part of the Designer Integrated Development Environment, relies on Designer for compilation and a Domino server at runtime (for applications). This article addresses the NOTES.INI variables affecting Java/CORBA and the JVM.
Note: NOTES.INI variables related to debugging are not addressed in this article. For more information concerning NOTES.INI debug variables, see the Ask Professor INI column, Using debugging variables.
Most of the variables discussed in this article are Notes and Domino R5 NOTES.INI variables. We've included some Rnext-only variables (these are so noted), but please keep in mind that Rnext-only variables are works in progress and, therefore, are subject to change before Rnext is released.
Much of the information contained in this article can be found in Domino R5 Designer Help. However, additional details were gleaned through discussions with the developers and are not documented.
A few of the variables mentioned here are set through the client's user interface (these are so noted), but most are set by modifying the NOTES.INI file directly (for example, by using a text editor). In general, we discourage editing the NOTES.INI file directly because of the damage that can be done by modifying it incorrectly. If you find you need to edit the NOTES.INI file directly, do so with caution and great care.
Variables and Java/CORBA
Using Java to access Domino Objects requires that a few NOTES.INI variables be set. Also, see the section on Variables and the JVM for more Java-related NOTES.INI variables.
Note: Do not confuse this interface with the Lotus Domino Toolkit for Java/CORBA, which will be discussed in a subsequent article.
Allow_Notes_Package_Applets
This variable allows you to use Notes packages in your Java applications. Its syntax is:
Allow_Notes_Package_Applets=1
This variable is set in the client's NOTES.INI file.
JavaDlgSettings
To assist you in creating a Java agent, this variable, when set to 1, is used to "remember" the last set of options you used in the Edit Project dialog box. Its syntax is:
JavaDlgSettings=1
This variable is set in the client's NOTES.INI file.
JavaUserClasses
If your Java agent calls another class that has native methods, you must make sure that that class is loaded via the JVM's system loader. To ensure this, set this variable to the file name of the class file that contains the native methods. The variable's syntax is:
JavaUserClasses=< directory/filename >
By setting this variable, you override a security restriction contained in the agent class loader that does not allow classes with native methods to be loaded. This variable may be set in either or both the client and the server NOTES.INI file.
Note that you should not enter more than one JavaUserClasses entry in a NOTES.INI file. If you have more than one, only the first will be used; all others will be ignored. If you have multiple uses for JavaUserClasses, enter all the parameters on the same line. For example:
JavaUserClasses=< directory1 >;< directory2\jarfile >;< zipfile1 >;…
Keep in mind that there is a 256-byte limit for NOTES.INI entries. Use JavaUserClasses sparingly.
EnableJavaApplets
This variable enables Java applets if set to 1 or disables them if set to 0. You set this variable to 1 by selecting the Enable Java applets option in the Additional Options section of the Basics panel of the User Preferences dialog box. Deselecting Enable Java applets sets the variable to 0.
LaunchDIIOPOnPreview
DIIOP (Domino Internet Inter-ORB Protocol) is a server task that works with the Domino Object Request Broker. When set to 1, this variable launches the DIIOP server task when Preview In a Browser is selected from Domino Designer.
You set this variable to 1 by selecting "Launch the CORBA (DIIOP) server on Preview in a web browser" option in the Additional Options section of the Basics panel of the User Preferences dialog box. Deselecting "Launch the CORBA (DIIOP) server on Preview in a web browser" causes this variable to be removed from the NOTES.INI file.
ServerTasks
In general, this variable must be set for anything to run on the server. Setting it to http and diiop ensures that the server tasks HTTP and DIIOP are running. Java/CORBA requires that these server tasks be running. Its syntax is:
ServerTasks=< any other tasks >, http, diiop
where < any other tasks > are any other needed server tasks. This variable is set in the server NOTES.INI file.
Environment variables
Java/CORBA classes include the following NOTES.INI variable-related functionality:
The getEnvironmentString (for strings and numeric values) and getEnvironmentValue (for numeric values) methods of the Session class retrieve the value of an environment variable from the current user's NOTES.INI file.
The setEnvironmentVar method of the Session class sets the value of a string or numeric environment variable.
Back to top
Variables and the JVM
There are several variables used to control the behavior of the Java Virtual Machine (JVM). All of these variables can be set in either or both the client and server NOTES.INI file. The client's NOTES.INI values rule the JVM executing on the client, such as local Java agents and applets. The server's NOTES.INI values rule all the JVM's running on the server-one each in http, amgr, server, router, runjava, and so on, or in some combination. It is unlikely, however, that you will ever need to set any of these variables (except for perhaps JavaUserClasses). As ever, proceed with caution when editing a NOTES.INI file.
JavaEnableJIT
By default, Notes disables the JVM default JIT (Just-In-Time) functionality because of its instability (see the caution below). Setting this variable to 1 turns on the default JIT functionality, if one is provided; so the JVM will allow normal loading of the default JIT. The variable's syntax is:
JavaEnableJIT=1
Caution: JIT functionality can be unstable and lead to unexpected crashes.
JavaJITName
Setting this variable turns on the JIT specified in the parameter. Its syntax is:
JavaJITName=< jit_name >
where < jit_name > is the specific JIT to use. You must provide the named JIT or an error is reported by the JVM, although execution of the application or agent will continue without it.
You can specify the default JIT name here, such as symcjit on Win32 or jitcompiler on alpha; that is equivalent to using JavaEnableJIT=1.
Note: The name of the JIT on Win32 differs depending on what version of Notes you are referring to. On 5.0.x, the JIT name is symcjit. On Rnext, its name is jitc.
JavaMaxHeapSize
Use this variable to specify the maximum size the Java heap can grow to in bytes. Its syntax is:
JavaMaxHeapSize=< number_of_bytes >
The default number of bytes is 67,108,864 (64MB). Note that this is the maximum size, not the initial size. (Currently, there is no way to set the initial size.) The JVM starts out at 1MB of heap space, most of it uncommitted. If the JVM needs more heap space than it currently has, it expands the heap in increments, although it will not exceed the maximum. An exception like java.lang.OutOfMemoryError is an indication of maxed-out heap space.
JavaNoClassGC
Use this variable to turn off the garbage collection (GC) of unreferenced classes. Its syntax is:
JavaNoClassGC=1
For example, you might turn garbage collection of classes off to protect static fields. If a class has static fields that are used by others, and garbage collection is performed on that class, it could lead to potential unintended changes in the static fields.
You can use this variable to stop failures due to poorly written code, for instance, code that relies on static fields with no continuity of class referencing. Properly designed code will work properly regardless of the state of this variable.
JavaStackSize
You can use this variable to specify the size of each Java thread's execution stack. Its syntax is:
JavaStackSize=< number_of_bytes >
The default size of a Java thread's execution stack is 409,600 (or 400K), which is fine for most purposes. However, if you need to use deeply nested call stacks (such as recursion), then you may need to increase the stack size.
JavaUserClasses
The variable is set to a list of directories or JAR or ZIP files that are added to the CLASSPATH at JVM startup so that classes can be found via the system loader rather than attached to the agent or applet. This allows code sharing across databases. The variable's syntax is:
JavaUserClasses=< directory1>;
;;...
The list is semicolon ( ; ) delimited on Win32 and OS/2 system and colon ( : ) delimited on Unix systems. For example, the following is a valid list on a Win32 system:
JavaUserClasses=c:\classes;d:\appxyz\stuff.jar
Be aware that one drawback to using this variable is that, because it is in the NOTES.INI file, it doesn't replicate. If you have an agent, applet, or servlet that relies on JavaUserClasses, and the database that contains that item replicates somewhere, you have to manually add JavaUserClasses to the NOTES.INI file on the target system or the agent, applet, or servlet won't run. Another drawback is that the variable requires that the user have access to the file system on the server.
Note that you should not enter more than one JavaUserClasses entry in a NOTES.INI file. If you have more than one, only the first will be used; all others will be ignored. If you have multiple uses for JavaUserClasses, enter all the parameters on the same line, as shown in the syntax above.
Keep in mind that there is a 256-byte limit for NOTES.INI entries. Use JavaUserClasses sparingly.
JavaVerbose
Use this variable to turn on the verbose setting of the JVM. Its syntax is:
JavaVerbose=1
This causes numerous messages to be issued by the JVM during its execution, which can be helpful in narrowing down runtime problems.
JavaVerboseGC
Use this variable to turn on extra messages from the GC mechanism in the JVM. Its syntax is:
JavaVerboseGC=1
During garbage collection, the JVM issues many informational messages about memory use. These can be helpful for debugging heap allocation problems, such as the unbounded growth of the heap leading to OutOfMemoryErrors.
JavaVerboseJNI
This is a new variable in Rnext. Use this variable to turn on extra messages from the Java Native Interface mechanism in the JVM. Its syntax is:
JavaVerboseJNI=1
During calls to JNI functions, the JVM issues many informational messages about what is happening. These can be helpful for debugging native code and for getting extended JNI-related information out of the JVM at runtime.
Variables related to the JVM verifier
The verifier is a piece of the JVM that inspects a given piece of bytecode to make sure it complies with the spec and doesn't do anything that code shouldn't do. The default behavior of the JVM is to verify just bytecode that is loaded remotely. These next three variables control verifier behavior.
JavaVerify
Use this variable to tell the JVM to verify all bytecode it loads, not just the bytecode loaded remotely. Its syntax is:
JavaVerify=1
Because this verification of non-remotely loaded code results in a performance hit, it is not the default behavior.
JavaNoVerify
Use this variable to turn off all bytecode verification. Its syntax is:
JavaNoVerify=1
Caution: The verifier is an essential part of Java's security mechanism. Turning it off will improve performance, but it will also leave you with a gaping security hole and no protection against code inadvertently getting corrupted in transfer. Although available and supported, this variable should seldom, if ever, be used.
JavaVerifyRemote
Use this variable to tell the JVM to run verification on classes that are loaded remotely, for example, via a classloader. Its syntax is:
JavaVerifyRemote=1
Although the current default for the JVM is to have verification of remotely loaded bytecode on, this variable has been included to ensure that this option can be enabled if the default setting ever changes.
Conclusion
This concludes the second part of our exploration of NOTES.INI variables and programmability. In a future column, we will discuss NOTES.INI variables and the Notes & Domino programming toolkits.
Do you have a NOTES.INI question? Send it in to Professor INI. We'll answer as many questions as we can in future "Ask Professor INI" columns. Keep in mind, however, that we may not be able to answer every question, nor can we quickly respond to requests that require immediate attention. If you need an immediate response to a question, we recommend you post it in the Iris Cafe Notes/Domino Gold Release Forum where someone from the general Notes community might be able to help, or contact Lotus Customer Support.
