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.
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
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
4) Mixing SSJS and JS
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.