Hassle with the new Eclipse LocationTech version of JTS (Java Topology Suite)

When some software library is bolted tightly into many other projects, refactoring is not an easy task for neither maintainers nor the users. Even a simple rename can cause some grey hair. If I would only have some hair left, I’m sure you could see that I recently upgraded some libraries and examples from the good old JTS Topology Suite to the brand new JTS Topology Suite, governed by Eclipse Foundations’s LocationTech project.

The purpose of the blog post is not to critique the refactoring (package rename) done to the JTS project. I know there are non-technical reasons to do so. The purpose is to help others on the same migration and to make developers think twice if they are planning similar rename without valid reasons.

The tail of V-Leaflet upgrade

My most significant contribution(s) to OSS GIS has been slippy map integrations to Vaadin. Recently my main efforts have gone to V-Leaflet, which has a JTS dependency to provide seamless integration to other Java GIS tooling. I got a first pull request to updated V-Leaflet to the latest LocationTech version of JTS over a year ago. I had known this issue would be on its way even before that.

It is not just V-Leaflet which depends on JTS. It has extensions that also support data binding to JTS geometries. It also has a lot of users, whose applications depend on other libraries, which also depend on JTS. There is basically no sane way to allow seamless transition so that a version of V-Leaflet could support both namespaces. Below you can see some of the modules in one of my hobby apps and their dependencies.

If you count from the image, there are eight different paths from my app to the JTS library. To upgrade any of the dependencies to a version that uses the latest JTS means I’ll have to update all the dependencies at once. The nasty thing is that many of the upgrades happen in major releases, causing potentially other major changes to my app.

At the current state, almost all of those can finally be upgraded. I have a demo application with almost similar architecture, that demonstrate the usage of Spring Boot, Spring Data JPA, spatial features of Hibernate, Vaadin UI with V-Leaflet extension for visualizing and editing features. That is now finally upgraded; this is what I did:

1. I first postponed the update as long as possible. As a partial upgrade would not be possible, I needed to wait that all dependencies I was not governing are updated. Hibernate 5.4 was the last thing I was waiting for. That now comes with spatial extensions that use the new JTS namespace. The nasty thing here is that it no more supports the old JTS. So if you want to upgrade to Hibernate 5.4 for some other reason, you’ll have to update to the new JTS as well. Some probably would have considered that to need a major version bump, but the Hibernate team decided to do that in a minor.
2. To my surprise, upgrading to Hibernate 5.4, more technically specifying property for Spring Data JPA in the pom.xml, didn’t actually blow the app. Is still compiled and some features even worked as I now had two JTS versions on the classpath. One with com.vividsolutions and one with org.locationtech namespace. But geographical features weren’t really stored as native geometries to the database but as blobs. Thus also all geographic SQL queries broke. Next step was to do a project global find-and-replace for com.vividsolutions -> org.locationtech. Then you get some actual compilation errors and you can start updating everything else.
3. Obviously, the first thing to work on was V-Leaflet add-on, indirectly referenced by v-leaflet-editable add-on, which provides editing features and UI field for your forms to edit JTS geometries. Unlike Hibernate spatial maintainers, I didn’t consider the upgrade of JTS as a backward compatible updated, so I wanted to cut a new major version. As I didn’t want to be rude for those who cannot yet upgrade to new JTS, I cut a bugfix release for the 2.x series and created a new major version (3.X) for the new JTS compatible versions. The actual upgrade was simply a change in the pom.xml and find-and-replace procedure. In the pom.xml I also needed to upgrade Geotools (which was used for some V-Leaflet tests) to 20.X series, technically to 20.2 release. As the upgrade was so easy, I can probably for a couple of years still maintain both 2.x and 3.x series side by side, with a reasonable effort. I hope nobody asks for Vaadin 7 compatible version; I’m out of numbers there with the 1.X series…
4. Upgrade of v-leaflet-editable add-on was pretty analog to the V-Leaflet upgrade. Even did the version numbers in the same way. 3.X series is now for the v-leaflet-editable that is compatible with JTS from the LocationTech project.
5. Now that the Vaadin part was done, the next big issue was QueryDSL. It is a really handy tool to write queries with Java code instead of error-prone query languages. It also has excellent spatial query support, so I had picked it up for my stack earlier. QueryDSL has some Finnish roots, but I’m not a maintainer of that project. There was already an issue about the upgrade, but no actions. The OSS person in me thought that this is my part to help. I hoped the upgrade would have been as easy as with Vaadin Leaflet integrations, but it wasn’t. There is another library in between and more headaches. QueryDSL depends on a library called Geolatte, which again depends on JTS. There is a new major version of Geolatte which depends on the new JTS, but has other big changes that at this point broke my motivations on this effort. As a workaround, which felt terrible to do, I modified the example so that it uses JPQL instead to do the spatial queries (with some Hibernate spatial extensions).
6. At this point, there was still one dependency that pointed out to the old JTS. The example app runs with any decent RDBMS, but for easy testing, it by default comes with an in-memory geodb database. As the last thing, I upgraded that to 0.9 version, which already points to the new JTS. I actually excluded the JTS from there as it was pointing to 1.5 version, while Hibernate spatial and all Vaadin Leaflet integrations expected the latest 1.6 release. Seems to work fine with the newer version as well.

Lessons learned

• If you have a popular library, especially a one that is a dependency to many other libraries, try to avoid package renames and other backward incompatible changes.
• If you have a library that depends on such a popular library, migrate early. I probably should have created the first 3.x series release for V-Leaflet a long ago. Now there is still a bunch of other libraries depending on V-Leaflet that are yet to be upgraded.
• Don’t upgrade your actual applications until you need to. There is a high chance that you’ll need to re-write something as some of your helpers are not up-to-date yet.
• When you start the upgrade, don’t expect it to be a quick task.