The NetCDF-Java Library is undergoing extensive development to bring it up to current standards of software engineering, and to make it compatible with ongoing changes and improvements in the JVM and Java platform.
Like all such libraries, NetCDF-Java is part of an interconnected web of library dependencies used by the open source and open science communities. We will be following the guidance in the Google Best Practices for Java Libraries document as best we can. In particular, we will follow Semantic Versioning, where our versioning will follow MAJOR.MINOR.PATCH:
- MAJOR version changes on incompatible API changes
- MINOR version changes when functionality is added in a backwards compatible manner
- PATCH version changes on backwards compatible bug fixes
The first step in the process is to clarify the NetCDF-Java public API. NetCDF-Java began its life around Java version 0.8, that is, before Java itself had a stable release in 1996. Over the years the priority was to deliver functionality, and the API has developed without a clear delineation between public API and private implementation. In order for NetCDF-Java to remain useful for another generation, we are doing extensive refactoring to define the public API going forward.
Currently, development is on version 5, and is hosted on Github. Following JLBP-7, netCDF-Java version 5 will have both the old API (marked deprecated) and the new API, to allow incremental upgrading. Version 6 will remove the deprecated API. These versions will stay compatible with Java 8. In version 7 we will drop Java 8 compatibility and target Java 11.
The public API is still being defined. We are looking for actively developed Java projects that use the NetCDF-Java library who are interested in giving us feedback. These projects will try compiling against the new API and report on difficulties and incompatibilities. Note that version 6 will not be backwards compatible with version 5. Upgrading to version 6 will require changing your code to use only the public API. Upgrading to future major versions may likewise require changes to your code. So only actively maintained projects intending to move forward as the Java platform evolves would be candidates for API testing.
Please let us know if you are interested in being one of our API testers by emailing support-netcdf-java@unidata.ucar.edu.
I'm all for modernizing code according to industry best practices, but I hope you'll be careful to preserve the usability of the API. For what it's worth... on more than one occasion, I've looked at the internal code to get ideas for good ways of doing things
Posted by Gary Lucas on April 13, 2020 at 12:09 PM MDT #
Gary, thank you for your comment! Indeed, usability is critical. The fact that you have had to look into the internal code to find ideas is for sure a failure on our part documentation-wise, and I think to some degree the lack of a clear API makes that kind of digging unavoidable. I'd be interested in learning more about your usage of the library, and whether or not you'd be willing to kick the tires as things progress. Feel free to reach out at the address in the post!
Posted by Sean Arms on April 13, 2020 at 01:12 PM MDT #
For metadata and reference systems parts of the API, what about using GeoAPI (https://www.geoapi.org/)? GeoAPI is a translation of OGC/ISO abstract models to Java interfaces. They may look complex at first, but I think ISO 19111 is a good balance; simpler models tend to miss important parts (e.g. CF-conventions omitting datum or PROJ.4 using WGS84 as a hub). PROJ 6 fixed PROJ.4 issues by following ISO 19111 model, which made its C++ API very similar to GeoAPI.
I created GeoAPI wrappers for netCDF projection classes years ago and would be happy to donate them if desired. The benefit would be interoperability between netCDF, Apache SIS and PROJ 6. For example it allows to use SIS Well Known Text (WKT) parser for instantiating UCAR projections from a WKT string.
GeoAPI could be at the hearth of netCDF new API or live as wrappers in a separated module. Both approaches have pros and cons. Please let me know if you would like to explore those possibilities further.
Posted by Martin Desruisseaux on April 13, 2020 at 04:16 PM MDT #
Been trying to keep with all the ongoing changes in 5.3 and 5.4 and the deprecations are a burr under the saddle. The cases where there is "@deprecated Do not use" but no indication of whether there is an approved alternative, if any, are a poke in the eye. It seems to read-between-the-lines that this might be fixed in 6.0, but due to ongoing major changes to my own code, I'm not willing at this point to fork my code into uses-NJ5 and uses-NJ6 branches.
Posted by Robert Schmunk on April 13, 2020 at 05:37 PM MDT #
Hello Martin! Thank you for the information on GeoAPI, and I think it would indeed be good to explore. Would it be possible for you to open an issue over at https://github.com/unidata/netcdf-java so that we can pickup over there?
Posted by Sean Arms on April 14, 2020 at 05:00 PM MDT #
Greetings Robert! Indeed, the deprecations without a clear indication of an alternative are not good. Those exists because we're still shuffling some things around, but it's getting closer. The idea is that version 5 will have the new API available, so you would not need to have to fork your code to have a version using 5 and a version using 6. Ideally, we could get your code working with the new API while still on version 5 of netCDF-java since it has both the old and (work in progress) new. At that point, even simple testing of swapping out the version 5 netcdf-java jars with version 6 to see how things compile and generally behave would be very helpful. As someone who really exercises the library, we really want to make sure the new API will work for your needs and usages.
Posted by Sean Arms on April 14, 2020 at 05:15 PM MDT #
Hello Sean. Thanks for reply. As proposed, I wrote a more detailed description on https://github.com/Unidata/netcdf-java/issues/256
Posted by Martin Desruisseaux on April 15, 2020 at 01:24 PM MDT #