That Java Thing, Part 3: Eclipse Prep
Nov 4, 2015, 4:26 AM
- That Java Thing, Part 1: The Java Problem in the Community
- That Java Thing, Part 2: Intro to OSGi
- That Java Thing, Part 3: Eclipse Prep
- That Java Thing, Part 4: Creating the Plugin
- That Java Thing, Part 5: Expanding the Plugin
- That Java Thing, Part 6: Creating the Feature and Update Site
- That Java Thing, Part 7: Adding a Managed Bean to the Plugin
- That Java Thing, Part 8: Source Bundles
- That Java Thing, Part 9: Expanding the Plugin - Jars
- That Java Thing, Part 10: Expanding the Plugin - Serving Resources
- That Java Thing, Interlude: Effective Java
- That Java Thing, Part 11: Diagnostics
- That Java Thing, Part 12: Expanding the Plugin - JAX-RS
- That Java Thing, Part 13: Introduction to Maven
- That Java Thing, Part 14: Maven Environment Setup
- That Java Thing, Part 15: Converting the Projects
- That Java Thing, Part 16: Maven Fallout
- That Java Thing, Part 17: My Current XPages Plug-in Dev Environment
Before you dive into OSGi development, you'll need a proper development environment, and that usually means Eclipse. Domino Designer, being Eclipse-based, can technically do the job and has the advantage of some of the setup being done, but it's so out-of-date at this point that it's not worth it (believe me, I tried originally). Newer Eclipse versions have improved noticeably, so it's best to grab a recent version. Currently, that means Mars, or Eclipse 4.5.1.
Before Eclipse, you'll need to install Java if you haven't already. To do that, go to Oracle's site and download the latest release for your platform. Once you install it and find out how many devices run Java, you can move on to installing Eclipse.
Head to the Eclipse download page and download the "Eclipse IDE for Java EE Developers" for your platform. They've recently added an Installer at the top of the page, and that works as well, but adds some new wrinkles that haven't made it into common knowledge yet. For now, you may want to stick with the "...or download an Eclipse Package" section. The "bitness" (32 or 64) doesn't matter too much - you should generally match the bitness of your OS.
Once you have Eclipse installed and running ("installation" generally involves dragging the extracted ZIP file content somewhere), the next step is to teach Eclipse about the XPages artifacts. If you're running on Windows and have a local Domino server, the XPages SDK may be your friend, though it hasn't been fully tested for Mars. If you are running on a non-Windows OS or otherwise don't want to go the full SDK route, there's a quick route that lacks the automation and debugger integration.
Setting up the environment used to be something of a hassle, but it became much simpler ever since IBM released the Update Site for Build Management. Primarily made for Maven-development use (sort of), this Update Site also serves as a quick stop to pick up all of the dependencies you need for XPages development in one place.
To make use of the Update Site, download the file from OpenNTF, extract it, and then extract the
UpdateSite.zip file contained therein. You should end up with a folder like this:
In Eclipse, go to the preferences ("Window" → "Preferences" on Windows or "Eclipse" → "Preferences" on a Mac), then go to "Plug-in Development" → "Target Platform":
Edit the existing platform and, in the "Locations" tab of the ensuing dialog, click "Add..." → "Directory" → "Next", browse to that extracted UpdateSite folder, and click "Next" to verify that it finds a bunch of plugins, and then "Finish". Now, you'll be able to reference XPages platform plugins in your projects.
At this point, Eclipse is set up for the essentials, but it may still be a good idea to set up an appropriate JVM for Domino development to make sure you have a consistent baseline and to avoid problems where newer Java releases added classes methods not avilable in Java 6. Fortunately, on Windows (and Linux?), a Notes installation comes with a JVM that does the job nicely. To add it, go back to preferences, then "Java" → "Installed JREs" → "Add...". Choose "Standard VM" → "Next", browse to the "jvm" folder in your Notes (or Domino) installation directory, name it something appropriate, and then click Finish:
On the Mac, you can get a similar Java release from Apple, which nowadays will end up in
/Library/Java/JavaVirtualMachines (older installers put it in
Now that Eclipse is set up, the next step will be to break ground on making an actual XPages plugin.
Timothy Briley - Nov 4, 2015, 9:03 PM
I assume the answer is "No", but I fee the need to ask anyway. Can the above steps be followed without issue on a laptop that already has Designer on it?
Jesse Gallagher - Nov 5, 2015, 7:47 AM
Indeed they can! Having Designer installed is helpful, too, for the step where you add its Java 6 JVM - that lets you be more confident that you're developing on the same baseline where it'll run. The Eclipse install process is "extract this ZIP file somewhere and run it", so there's no worry about overwriting important Notes files.
Shillem Volpato - Nov 14, 2015, 6:13 PM
I would just like to comment that going the Update Site for Build Management route doesn't provide a flawless experience.
If you make a plugin that uses the com.ibm.pvc.webcontainer.application extension point the schema is missing and therefore there's no auto-completion for it (contextRoot, contentLocation).
I don't know what else might be missing but I don't feel confident in using the UpdateSite.zip.
Is including the two folders, osgi/rcp/eclipse/plugins and osgi/shared/eclipse/plugins (plus the com.ibm.notes.java.api workspace project) a valid approach?
Jesse Gallagher - Nov 15, 2015, 11:56 AM
That's definitely valid. If you use the XPages SDK, it'll set up a Target Platform with all of the appropriate plugin folders from Domino, and that's definitely the most complete. There are a few edge cases that the Update Site from OpenNTF doesn't quite cover (social/Fiesta stuff as well, for example), but I like using it when I can just to have a smaller setup.