That Java Thing, Part 17: My Current XPages Plug-in Dev Environment
Feb 26, 2017, 11:23 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
It's been a while since I started this series on Java development, but I've been meaning for a bit now to crack it back open to discuss my current development setup for plug-ins, since it's changed a bit.
The biggest change is that, thanks to Serdar's work on the latest XPages SDK release, I now have Domino running plug-ins from my OS X Eclipse workspace. Previously, I switched between either running on the Mac and doing manual builds or slumming it in Eclipse in Windows. Having just the main Eclipse environment on the Mac is a surprising boost in developer happiness.
The other main change I've made is to rationalize my target platform configuration a bit. In the early parts of this series, I talked about adding the Update Site for Build Management to the active Target Platform and going from there. I still basically do this, but I'm a little more deliberate about it now. Instead of adding to the running platform, I now tend to create another platform just to avoid the temptation to use plug-ins that are from the surrounding modern Eclipse environment (this only really applies in my workspaces where I don't also have actual-Eclipse plug-in projects).
The fullest form of this occurs in one of my projects that has a private-only repo, which allows me to stash the artifacts I can't distribute publicly. In that case, I have a number of library dependencies beyond just the core XPages site, and I took the approach of writing a target platform definition file and storing it in the root project, with relative references to the packaged dependencies. With this route, I or another developer can just open the platform file and set it as the target platform - that will tell Eclipse about everything it needs. To do this, I right-clicked on the project, chose "New" → "Other..." and then "Target Definition" under "Plug-in Development":
Within that file, I used Eclipse variable references to point to the packaged dependencies. In this repo, there is a folder named "osgi-deps" next to the root Maven project, so I wanted to tell Eclipse to start at the root project, go up one level, and then delve down into there for each folder. I added "directory" type entries for each one:
The reference syntax is ${workspace_loc:some-project-name}../osgi-deps/Whatever
. workspace_loc
resolves the absolute filesystem path of the named project within the workspace - since I don't know where the workspace will be, but I DO know the name of the project, this gets me a useful starting point. Each of those entries points to the root of a p2-format update site for the project. This setup will tell Eclipse everything it needs.
Unfortunately, this is a spot where Maven (or, more specifically, Tycho) adds a couple caveats: not only does Tycho not allow the use of "directory" type entries in a target platform file like this (meaning it can't be simply re-used), but it also expects repositories it points to to have p2 metadata and not just "plugins" and "features" folders or even a site.xml
. So there's a bit of conversion involved. The good news is that Eclipse comes with a tool that will upgrade old-style update sites to p2 in-place; the bad news is that it's completely non-obvious. I have a script that I run to convert each new release of the Extension Library to this format, and I adapt it for each dependency I add:
java -jar /Applications/Eclipse/Eclipse.app/Contents/Eclipse/plugins/org.eclipse.equinox.launcher_1.3.100.v20150511-1540.jar -application org.eclipse.equinox.p2.publisher.UpdateSitePublisher -metadataRepository file:///full/path/to/osgi-deps/ExtLib -artifactRepository file:///full/path/to/osgi-deps/ExtLib -source /full/path/to/osgi-deps/ExtLib/ -compress -publishArtifacts
Running this for each directory will create the artifacts.jar
and content.jar
files Tycho needs to read the directories as repositories. The next step is to add these repositories to the root project pom so they can be resolved at build time. To start with, I create a <properties>
entry in the pom to contain the base path for each folder:
<osgi-deps-path>${project.baseUri}../../../osgi-deps</osgi-deps-path>
There may be a better way to do this, but the extra "../.." in there is because this property is re-resolved for each project, and so "project.baseUri" becomes relative to each plugin, not the root project. Following the sort of best practice approach to Tycho layouts, the sub-modules in this project are in "bundles", "features", "releng", and "tests" folders, so the path needs to hop up an extra layer. With that, I add <repositories>
entries for each in the same root pom:
<repositories> <repository> <id>notes</id> <layout>p2</layout> <url>${osgi-deps-path}/XPages</url> </repository> <repository> <id>oda</id> <layout>p2</layout> <url>${osgi-deps-path}/ODA</url> </repository> <repository> <id>extlib</id> <layout>p2</layout> <url>${osgi-deps-path}/ExtLib</url> </repository> <repository> <id>junit-xsp</id> <layout>p2</layout> <url>${osgi-deps-path}/org.openntf.junit.xsp.updatesite</url> </repository> <repository> <id>bazaar</id> <layout>p2</layout> <url>${osgi-deps-path}/XPagesBazaar</url> </repository> <repository> <id>eclipse-platform</id> <url>http://download.eclipse.org/releases/neon/</url> <layout>p2</layout> </repository> </repositories>
The last entry is only needed if you have extra build-time dependencies to resolve - I use it to resolve JUnit 4.x, which for Eclipse I just tossed unstructured into a "plugins" folder in the "Misc" folder, without p2 metadata.
Though parts of this are annoyingly fiddly, it falls under the category of "worth it in the end" - after some initial trial and error, my target platform is more consistent and easier to share among multiple developers and automated build servers.