Kicking the Tires on Domino 14 and Java 17

Jun 2, 2023, 1:50 PM

Tags: domino java

As promised, HCL launched the beta program for Domino 14 the other day. There's some neat stuff in there, but I still mostly care about the JVM update.

I quickly got to downloading the container image for this to see about making sure my projects work on it, particularly the XPages JEE Support project. As expected, I had a few hoops to jump through. I did some groundwork for this a while back, but there was some more to do. Before I get to some specifics, I'll mention that I put up a beta release of 2.13.0 that gets almost everything working, minus JSP.

Now, on to the notes and tips I've found so far.

AccessController and java.policy

One of the changes in Java 17 specifically is that our old friend AccessController and the whole SecurityManager framework are marked as deprecated for removal. Not a minute too soon, in my opinion - that was an old relic of the applet days and was never useful for app servers, and has always been a thorn in the side of XPages developers.

However, though it's deprecated, it's still present and active in Java 17, so we still have to deal it. One important thing to note is that java.policy moved from the "jvm/lib/security" directory to "jvm/conf/security". A while back, I switched to putting .java.policy in the Domino user's home directory and this remains unchanged; I suggest going this route even with older versions of Domino, but editing java.policy in its new home will still work.

Extra JARs and jvm/lib/ext

Another change is that "jvm/lib/ext" is gone, as part of a general desire on Java's part to discourage installing system-wide libraries.

However, since so much Java stuff on Domino is older than dirt, having system-wide custom libraries is still necessary, so the JVM is configured to bring in everything from the "ndext" directory in the Domino program directory in the same way it used to use "jvm/lib/ext". This directory has actually always been treated this way, and so I started also using this for third-party libraries for older versions, and it'll work the same in 14. That said, you should ideally not do this too much if it's at all avoidable.

The Missing Java Compiler

I mentioned above that everything except JSP works on Domino 14, and the reason for this is that V14 as it is now doesn't ship with a Java compiler (JSP, for historical reasons, does something much like XPages in that it translates to Java and compiles, but this happens on the server).

I originally offhandedly referred to this as Domino no longer shipping with a JDK, but I think the real situation was that Domino always used a JRE, but then had tools.jar added in to provide the compiler, so it was something in between. That's why you don't see javac in the jvm/bin directory even on older releases. However, tools.jar there provided a compiler programmatically via - on a normal JRE, this API call returns null, while on a JDK (or with tools.jar present) it'd return a usable compiler. tools.jar as such doesn't exist anymore, but the same functionality is bundled into the newer-era weird runtime archives for efficiency's sake.

So this is something of a showstopper for me at the moment. JSP uses this system compiler, and so does the XPages Bazaar. The NSF ODP Tooling project uses the Bazaar to do its XSP -> Java -> bytecode compilation of XPages, and so the missing compiler will break server-based compilation (which is often the most reliable compilation currently). And actually, NSF ODP Tooling is kind of double broken, since importing non-raw Java agents via DXL is currently broken on Domino 14 for the same reason.

I'm pondering my options here. Ideally, Domino will regain its compiler - in theory, HCL could switch to a JDK and call it good. I think this is the best route both because it's the most convenient for me but also because it's fairly expected that app servers run on a JDK anyway, hence JSP relying on it in the first place.

If Domino doesn't regain a compiler, I'll have to look into something like including ECJ, Eclipse's redistributable Java compiler. I'd actually looked into using that for NSF ODP Tooling on macOS, since Mac Notes lost its Java compiler a long time ago. The trouble is that its mechanics aren't quite the same as the standard one, and it makes some more assumptions about working with the local filesystem. Still, it'd probably be possible to work around that... it might require a lot more of extracting files to temporary directories, which is always fiddly, but it should be doable.

Still, returning the built-in one would be better, since I'm sure I'm not the only one with code assuming that that exists.


Despite the compiler bit, I've found things to hold together really well so far. Admittedly, I've so far only been using the container for the integration tests in the XPages JEE project, so I haven't installed Designer or run larger apps on it - it's possible I'll hit limitations and gotchas with other libraries as I go.

For now, though, I'm mostly pleased. I'm quite excited about the possibility of making more-dramatic updates to basically all of my projects. I have a branch of the XPages JEE project where I've bumped almost everything up to their Jakarta EE 10 versions, and there are some big improvements there. Then, of course, I'm interested in all the actual language updates. It's been a very long time since Java 8, and so there's a lot to work with: better switch expression, text blocks, some pattern matching, records, the much-better HTTP client, and so forth. I'll have a lot of code improvement to do, and I'm looking forward to it

Commenter Photo

Mr. Thomas Adrian - Jun 3, 2023, 4:59 AM

we are so lucky to have you core Domino java bloggers on board. in the Microsoft world the developer of

Commenter Photo

Mr. Thomas Adrian - Jun 3, 2023, 5:01 AM

…the products are actively blogging. makes you wonder where the HCL developers are at

Commenter Photo

Elrond W - Jun 9, 2023, 1:56 PM

Jesse, good info here.

  1. Regarding the extra JARs and jvm/lib/ext. Is there an extra step to make sure your project is looking for the ndext folder (ie. add it as a library), or is it automatic? I don't see any references to that location or files from the package explorer of my projects.
  2. Do the different JAR locations (jvm/lib/ext , code/jars, etc) have a sort of precedence set up, or does the project always pull in all files from all locations simultaneously and then hash out the conflicts? I'm trying figure out how to manage different JAR versions between projects on the same server. Thx
Commenter Photo

Jesse Gallagher - Jun 10, 2023, 10:23 AM

@Thomas I would love to see more developer blogging and evangelism about this sort of thing. There's SOME, but more would go a long way.


  1. No, there's not an extra step - the JVM is configured to implicitly use ndext as part of its runtime classpath, which it also was before V14. The change in V14 here is just that jvm/lib/ext doesn't exist, but ndext is basically the same idea.

  2. Yes and no. ClassLoaders work in a tiered system, where your code runs in an "application" ClassLoader that generally gets priority over others - there are usually two or so more delegates, with the final being the system ClassLoader, which includes these filesystem directories. However, Java itself doesn't have a versioning system, so, while a class named foo.Bar inside your NSF will almost definitely take priority over one of the same name deployed to the filesystem, there are a lot of things that make it tricky. In particular, different versions will potentially have renamed classes and resources, or services provided by older versions will be loaded by the new version and break. OSGi at the XPages/DOTS layer has a true versioning system, but XPages doesn't fully embrace it (XPages libraries, for example, don't really do versioning in a useful way for this). It can be done, but it's fiddly. In general, you want to avoid mixing different versions of the same library at different tiers of the ClassLoader.

Both of those have a caveat that I didn't get into in this post, which is the distinction between the runtime classpath and the build-time classpath, i.e. what Designer sees. Those have always been disjoint - for example, though ndext has always been on the runtime classpath, it doesn't generally appear in Designer's build-time classpath. I'm going to have a followup post about my tinkering with Designer 14 that will go into this.

Commenter Photo

Don - Jul 2, 2023, 4:39 AM

We haven't got around to testing Domino 14 al lot, because we got stuck with JWT tokens in 12.0.2, but many thanks for the heads up!

Commenter Photo

D14 - Dec 7, 2023, 11:05 AM

Hi Jesse! Thank you for this post! Did you have some time tinkering with Designer 14? What's your experience so far?

New Comment