Tuesday, July 11, 2023

Construction Ahead: Refactoring org.opengis to org.geotools.api

In the next release of GeoTools 30.0 there are some breaking API changes to look forward to:
  • org.opengis package is renamed to org.geotools.api package
  • This release will include update instructions, and a migration script, to fix your code.
This is a breaking change, the formal change control proposal is here.

Why is this changing

The GeoAPI Implementation Specification is a Java standard (Interfaces and Classes) provided by the Open Geospatial Consortium for interoperability between Java projects and libraries.

GeoTools worked on a pre-release of these interfaces in the hopes of collaborating with other projects. In GeoTools 2.7 these interfaces were folded back into the gt-opengis module due to lack of collaboration opportunities and funding.

The GeoTools library use of the org.opengis package has caused disruption for the OGC and Apache software foundations and they have asked the Open Source GeoSpatial Foundation for this matter to be addressed (see osgeo/todo#142).

Cross-project initiative and timeframe

A cross-project OpenGIS Harmonization initiative has been setup at, to collaboration between the above software foundations, and the affected projects from all walks of life.

The GeoTools library is coordinating our activities with a change proposal covering the following timeline:
  • 2023 April: Open Standards and Open Source Software Code Sprint: initiatve promotion
  • 2023 June: FOSS4G Code Sprint: Design and Planning
  • 2023 August: Bolsena Code Sprint: GeoTools Refactor and API Change
  • 2023 September: GeoTools 30-RC: Public release-candidate for testing and feedback
  • 2023 October: GeoTools 30.0: Public release of API Change
  • 2023 Q4: Last Friday of the month drop-in sprint to assist downstream projects with migration

What you can expect

You can expect to run a script and recompile / re-release your code:

ant -f remove-opengis.xml

At the end of this process you may need to re-run code formatted, or clean up unused imports.

For projects that have not yet made the upgrade to Java 11 additional work will be required to establishing a supported build environment.

Participation and Support

This activity is disruptive, and the best way to control the risk for you and your project team is to participate both in the upcoming Bolsena Code Sprint, and in testing the GeoTools 30.0-RC release candidate in early September.

To be successful this transition requires your participation and support, both with GeoTools, and also the downstream projects that will be disrupted.
If you are in position to offer financial assistance, this activity is covered by OSGeo sponsorship program. Your support is visible not only here but on the OSGeo website and marketting materials also.

OSGeo identified this activity as a priority in their 2023 budget. The OGC asked us to create a ticket (opengeospaital/ideas#120) for their June board meeting but have not reported back. Apache Software Foundation as a policy does not financially support activities.