A common request seems to be how do I use XXXX Java or JavaScript project in XPages. One of the strengths of XPages was that it made the approaches more standard. So the answer is often less an XPages question, and more a generic web development question. There are a few caveats, but many of those are standard for web development.


1) Java Version

Java needs compiling against a certain version, and the code you are using needs to work with the relevant Java runtime. For Domino 9.0.1 FP7 and lower, that's Java 6. For 9.0.1 FP8 and above that's Java 8. There is a big difference and if you're starting to use more and more third-party Java, you need to consider ensuring your Domino server is up-to-date.

2) Servlet Version

For something like Apache POI, this is unlikely to be a problem. If it's a full Java framework, like Vaadin, it may depend on a specific Java servlet version. I covered this a few years ago in my blog series on XPages and Vaadin (https://www.intec.co.uk/from-xpages-to-web-app-part-thirteen-application-structure/). Even then, using @Annotations required servlet specification 3.0.

3) Build Path

Adding a JAR file or JAR files to an NSF is best done by using the WebContent\WEB-INF\lib folder. Why? Because that's the standard approach for web applications. You can use the JAR design element, but if you're using Java, you're already down the road of best practice and standardisation. Why learn a non-standard approach when you can get used to the approach you can use for any web application, inside or outside of Domino.

Once copied into there (you can drag from the file system), you need to right-click and add to the build path.

Again, adding a JAR file to the build path for a Java web application is standard. This "moves" them to the Referenced Libraries area. Again, this is standard Eclipse.

In older versions of Domino, JAR files got lost from the build path. As a web developer, you should get used to knowing where the JAR files should appear in the IDE, and it's an easy resolution - just repeat the right-click and add to build path, or update in the Project > Properties and going to the Build Path section.

4) Security

Again, you're into standard web development. And security is a standard Java java.policy file in <Domino>\jvm\lib\security. The Java security policy on Domino (inherited from Websphere) is particularly Draconian and restrictive. The most common area you'll have problems is Java reflection, where the Java code in your NSF tries to interrogate a different Java class to find its properties and methods. A good example where this is the case is in Jackson or Gson, for converting JSON to Java objects - and so the code needs to look at those Java classes to work out what property names to extract from the JSON. You'll get a java.lang.SecurityException.
Changing the java.policy or adding a java.pol file may be one way. Moving the code to a plugin is probably the better. It's another learning curve, but one standard for OSGi plugin development beyond Domino.

4) ClassNotFoundException / NoClassDefFoundError

This is a scenario often encountered with third party jars that depend on other jars. The jars are only loaded at runtime, and if there's a problem loading one, it will fail. This can happen:

  • if a Java class's constructor has no error handling in it, and an error occurs (yes, I've encountered that).
  • if you've copied in a dependent jar that's also on the server either as a jar or in an OSGi plugin. If it doesn't know which one to use, or there's a conflict in the versions available, it will fail. This can happen with logging frameworks or things like Apache Axis.

Again, this is not specific to XPages, it's a problem of combining different Java frameworks.


1) AMD Module Loading

AMD (Asynchronous Module Definition) is how Dojo loads all the various Dojo modules. This conflicts with the way some other JavaScript works, most notably jQuery plugins. Again, this is not an XPages-specific issue and it's not an XPages-specific solution. You need to disable AMD loading, load your jQuery or other script, then re-enable AMD loading. And there's an XSnippet for that https://openntf.org/XSnippets.nsf/snippet.xsp?id=hack-to-use-jquery-amd-widgets-and-dojo-together.

2) Resource Aggregation

This can often cause problems and is an XPages-specific issue. It's basically a solution to multiple HTTP calls to load resources, by bundling them all together. Beyond Domino, that problem is typically now solved by HTTP/2. But that requires an update to the HTTP server. In the meantime, there may be occasions where you need to disable resource aggregation, particularly with Domino 10 where it can fail if any of the resources you're trying to load is not available.

3) Location / Editing

There are various places to add JavaScript, CSS and images. My preferred location is WebContent. Why? Again, it's standard for a Java web application.

The JavaScript and CSS editors in Domino-specific design elements are not as modern as they could be. And this is another reason heavy JavaScript developers will develop those files outside of Domino Designer. Again, if you use standard web development locations, it will likely go through more standard round-tripping for an ODP. And if you're looking to develop your applications in something other than Domino Designer long-term (Eclipse, VS Code, Eclipse Theia), standardisation will stand you in good stead.

4) Mixing SSJS and JS

A common problem occurs when trying to run SSJS on the browser or JavaScript on the server (e.g. using window or document and trying DOM manipulation). This is not helped by SSJS having a JavaScript syntax and having some objects that look like JavaScript, e.g. I18n. There's no getting around it, you need to understand where your code is running, what's available at the time, what the current state is etc. This is not an XPages issue, you'll hit it wherever you're coding front-end and back-end alongside one another - XPages, Vaadin, Spring, React.

Of course it's a lot easier if you use Java for your business logic.


At the end of the day, XPages brings a lot more standardisation and prepared developers much more for standard web development. I realised this as I started developing standard web applications on Websphere Liberty: the structure, the location, the deployment had a lot of similarities. Taking a standard approach may be more work, but it's preferable in the long run, whether XPages gets a resurgence or whether you move to other web frameworks.

Leave a Comment

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Scroll to Top