Unshackle Domino Designer by modernizing jvm.properties
Lars Berntrop-Bos May 1 2024 07:16:12 AM
The Notes Standard client and Domino Designer run as an Eclipse RCP application.The Eclipse RCP application, runs on a JVM, short for Java Virtual Machine.
The Java Virtual Machine utilizes memory to do its work, called a heap. There are lots of gears and knobs that go into setup and running of the machine, and key ones are configured in the file 'jvm.properties'.
That file lives in a subdirectory of the Notes client Program Directory:
These are fed into the Equinox launcher via the command-line. You can inspect said command-line using the excellent Process Explorer by Mark Russinovich. Get the suite containing this essential tool and others here: https://learn.microsoft.com/en-us/sysinternals/downloads/sysinternals-suite . You can see the command line by inspecting the properties of the notes2.exe process. It is surprisingly long
Warning!
Files in the Program directories are not writable for non-administrative users. So in R12, HCL created a way to customize this via the notes.ini, via WCT_vmarg settings. But that mechanism does not allow you to REMOVE a setting, llike I have done in the examples. The mechanism makes a copy in [DataDir]/workspace, and applies the WCT_ modifications. If you edit the jvm.properties file, after some time your changes will be overwritten. AVOID!!
Keep versions
Keep a history of versions and what you tried to accomplish and what the results were. This also enables a quick fix if an edit cripples Notes. I once managed to us a FF (0x0C) character instead of a line end, and then Notes would not start anymore
Location of jvm.properties
The jvm.properties file is located in the [Program directory]/framework/rcp/deploy
For a 32bit Client 11 - 12.0.2 on Windows, the default program directory is C:/Program Files (x86)/HCL/Notes/ => C:/Program Files (x86)/HCL/Notes/framework/rcp/deploy
For a 64bit Client, 12.0.2 64bit and 14 onwards, the default program directory is C:/Program Files/HCL/Notes/ => C:/Program Files/HCL/Notes/framework/rcp/deploy
To avoid the directory-with-a-space and ease of use, I've grown the habit of using C:/HCL/Notes. Also very handy if you want to run commandline, either offline or with the Notes client open.
If you look at the jvm.properties file, there is an IBM copyright banner, where the first year is 2006. But some of the settings have older roots. Some of these settings seem inappropiate in 2025...
I have been tinkering with jvm.properties for years, especially since I use Domino Designer a lot, and the default settings need adjusting.
Default settings
For reference the different default jvm.properties of the different versions.
Default settings for 12.0.1 FP1, 32-bit client (last client usable for developing LotusScript for 32-bit clients)
jvm_12.0.1_designer_default.properties
Default settings for 14.0, 64-bit client
jvm_14.0_designer_default.properties
Default settings for 14.5, 64-bit client (Early Access 3)
jvm_14.5_designer_default.properties
Annotated and tuned settings
Annotated and tuned jvm.properties files.
Annnotated and tuned settings for 12.0.1 FP1, 32-bit designer client (last client usable for developing LotusScript for 32-bit clients)
jvm_12.0.1.properties
Annnotated and tuned settings for 12.0.1 FP1, 32-bit multi-user client (all clients use the same shared class file)
jvm_12.0.1_multiuser.properties
Annnotated and tuned settings for 14.0, 64-bit client
jvm_14.0.properties
Annnotated and tuned settings for 14.0, 64-bit multi-user client (all clients use the same shared class file)
jvm_14.0_multiuser.properties
Annnotated and tuned settings for 14.5, 64-bit client (Early Access 3)
jvm_14.5_designer_default.properties
About the tuned settings
Shared classes cache size
All versions specify a significantly larger compiled Java shared classes cache. For this to take effect, the existing cache file needs to be DELETED for the size change to take effect. There are several settings like a change in AOT cache, storing line numbers or not and others that also need a cache delete to take effect. Lookup the settings in the documentation ( https://eclipse.dev/openj9/docs/x_jvm_commands/ ) to see which settings need a cache reset.
Shared classes cache location
By default, the cache lives in [DataDir]/workspace/.config/org.eclipse.osgi
The location is set with the jvm.properties setting jvm.shareclasses.loc=
Shared classes cache multiuser optimization
On a machine where a multi-user Notes client is installed, you can optimize disk space usage by specifying a fixed location accessible to all potential users for the client. The location needs to be accessible and writeable for all the users for the Notes client to be able to start.
For example: C:/ProgramData/HCL/Notes/org.eclipse.osgi That is what I chose in the multi-user example files.
This way only one big cache file is needed. and will save 300MB per user beyond the first one. This also works on VDI solutions like Citrix, and is the reason the singleJVM keyword was removed. Tip from Panagenda webinars about optimizing Notes on Citrix / VDI.
The shared classes cache is essential
I changed nonfatal to fatal so the Notes Client fails if an error occuurs with the shared classes instead of starting really slow. You may decide differently.
General tuning tips
I recommend documenting your changes using the # character to make comment lines, keeping the defaults but commented, and documenting WHY you set or unset a setting. Future you will thank you. Keep versions.
Turn on the heap display to see what effects this has on the heap. You can do this via preferences in Domino Designer, and via an edit of a file in the Client by adding SHOW_MEMORY_MONITOR=true to [datadir]/workspace/.metadata/.plugins/org.eclipse.core.runtime/.settings/org.eclipse.ui.prefs, tip published by Remco Angioni: https://www.angioni.nl/2020/11/15/show-heapsizes-in-your-hcl-notes-client/
Note that the text of the inserted line is case sensitive!
Some significant parameters
-Xmx maximum heap space Maximum heap space tthe JVM can use. 512m (denoting 512 megabytes) by default. Opening a simple database in Designer 14.5 puts the heaop at 777m. Opening the same db in 12.0.1 Designer puts the heap at 312m, but then that has a max heap of 768m due to 32-bit constraints.
IBM has advised to put this on 1024m, but if you live in Designer all day like I used to, 32-bit Designer would become unstable and crash after a while. If checking allocations, the actual amount of memory in use by Eclipse would slowly grow more until it hit the hard limit of 2 GB, at which point the process crashes. 768m is a limit which I arrived at through trials to allow for a stable experience.
On 64-bit Designer, you can set a 4GB or 8GB heap, allowing much breathing room, see the 14.5 jvm.properties file. Then when you open the design for a new db, it opens nearly instantaneous instead of the lengthy process caused by the cramped heap of 12.0.1 32 bit Designer.
-Xms minimum heap space Amount the heap starts with. By default 8m, which is tiny for an application the size of Notes. You might think to make it a lot bigger, nut that skips an optimization I once read about on IBM developerworks. The idea is to set a size large enough so the intial setup bumps into a limit just after most initial processing has been done. The goal is to evict objects from the heap that were only needed for setup, while the Grabage Collect (GC) does not yet have to deal with a large old heap and can quickly finish.
In my experience, 128m is a nice value for that. The HCL default of 256m is too big for an early GC to kick in.
-Xscmx maximum size of shared classes cache The old default seems way too small. And theJ9 defaults have grown significantly since Java 6. For Java 8 (12.0.1) i set this to 300m, on newer versions I disable the setting to let the J9 engine decide. A strategy also employed for other settings. Reading the J9 documentation I got the impression that a LOT of effort is poured into making the JVM really smart, so I try to take advantage of that where I can.
-Xscmaxaot maximum size of AOT part of shared classes cache The AOT part refers to those classes compiled Ahead Of time (i.e. AOT). This used to be set to 12m to not make the 64m shared class file too cramped. But since that has grown a lot, I prefer to let J9 decide.
-Xminf0.1 minimum percentage of free space after global GC The 0.1 seems a size to stem from the resource constrained past. These days, with plenty of memory, I think the better option is to let J9 do its thing.
-Xmn7m size of the nursing or eden area of the heap Found a refernce to this value in an article descibing it being needed in a fix for Websphere Liberty on Java 8 on IBM DeveloperWorks. From 2008... I think that the necessity of setting it explicitly has expired a while ago.
-Xshareclasses setup the shared classes cache Removed the singleJVM keyword to let the cache be shared. Changed nonfatal to fatal so the Eclipse launcher throws an error if there is a problem with the shared classes file, instead of launching a really slow Notes client
-Xmaxt0.6 maximum proportion of time to spend in GC as a percentage of prevoius 3 GC runs If GC takes long, expand heap, if it is really wuick, shrink heap. The J9 default is 0.13, the IBM/HCL default is 0.6. Seemed like something to constrict heap growth based on the restricted availability of 32-bit heap space. I rather have Designer use some memory than doing tryhard heap compaction. So I disable this to let J9 decide.
-Xgcpolicy:gencon which GC policy to use The default is gencon. On 64-bit there is the option to use balanced, but I have not yet experimented with that. In part because this opens a whole new can of worms to take into consideration.
Have fun tuning, and i'd love to hear from you!
- Comments [0]