Skip to content

Remove OpenGIS

Jump to bottom Edit New page
Jody Garnett edited this page Aug 14, 2023 · 26 revisions

Description

This proposal is to refactor the geotools library to remove the dependencies on org.opengis interfaces.

Our original GeoAPI project was not successful as an outreach activity to other teams (indeed we got one meeting on geometry with degree project and that was about it). While we donated GeoTools interfaces as a starting point - the activity has not attracted interest (funding or volunteers) to upgrade to the latest org.opengis and maintain this relationship.

Having a clean break will allow GeoTools to exist in the same classloader as apache projects that make use of a newer version of these interfaces. It also would allow wrapper(s) to be created if anyone wants to bridge between systems.

Phase 1: Perform the change

  1. Introduce an org.geotools.api packages as a drop-in replacement for org.opengis packages where there is no clear GeoTools interface in place.

    This approach is recommended for org.opengis.metadata where no clear GeoTools interfaces exist.

  2. Pull methods down into existing GeoTools interface and extends relationship.

    This approach is good for interfaces like org.opengis.style.StyleFactory that can be folded into org.geotools.style.StyleFactory.

  3. Produce linux or ant script to migrate client code (to be provided with update instructions).

    Recommend code-sprint working on this script, when it is able to do the "automatic" conversion of GeoWebCache and GeoServer it is ready.

Phase 2: Clean up the mess

  1. Can we remove annotations? No we could not they are used via reflection apparently.

  2. Remove interfaces that have no implementations, such as org.opengis.geometry interfaces.

    This should have the knock on effect of simplifying Feature API to return JTS Geometry directly making the library easier to use.

  3. Stretch goal: Consistent handling of mutable vs immutable data structures. This addresses a design change that was introduced to take part in the GeoAPI project.

    To prevent having two API disruptions for our community of downstream projects this topic should be addressed in conjunction with the removal of org.opengis package use.

    Mutable vs immutable data structures

References:

Assigned to Release

Pending resources, GeoTools 30.x.

Status

Choose one of:

  • Under Discussion
  • In Progress
  • Completed
  • Rejected,
  • Deferred

Voting:

  • Andrea Aime: +1
  • Ian Turton: +1
  • Jody Garnett: +1
  • Nuno Oliveira: +0
  • Simone Giannecchini: +1
  • Torben Barsballe: +1

Tasks

The following outlines the technical tasks required for the change; however this activity requires resources (funding and people) to proceed.

  1. ✅ Request funding from OSGeo and Sponsors for a breaking change effecting downstream projects.

    Presented as an cross-project OSGeo initiative with target of $20,000. See OSGeo [todo#142] for background.

    This activity is not worth starting without both communication and resources to support downstream projects.

  2. IDE refactor responsible for updating library and test cases; resulting in stand-alone commit:

  3. Make a decision on a package by package basis

    • Interface refactor to org.geotools.api package.

      This can be used if there is not a good existing geotools package, or if we need to define concepts in the same module to avoid split-package across module boundaries.

    • Method pulldown to existing GeoTools interface.

      This is preferred to restore the original GeoTools naming convention of Interface, InterfaceFactory, InterfaceImpl, or DefaultInterface alongside each other in the same package.

    • Interface refactor to existing GeoTools package.

      If there is not an existing GeoTools interface, refactor org.opengis interface to operate alongside it's implementation.

  4. Ant script to update client projects (concurrent with steps 1-3 above).

    Test against geotools doc examples, geowebcache, and geoserver.

Communication (using issues to communicate with affected projects):

API Change

Method pulldown to existing GeoTools interface

Where an existing GeoTools interface extends an org.opengis interface the methods can be pulled back down into GeoTools. Client code can then use the GeoTools interface directly (if they were not already doing so).

Before:

import org.opengis.style.StyleFactory;

public void exampleMethod( DataStore store, Filter filter){
    StyleFactory sf = CommonFactoryFinder.getStyleFactory();
}

After:

import org.geotools.styling.StyleFactory;

public void exampleMethod( DataStore store, Filter filter){
    StyleFactory sf = CommonFactoryFinder.getStyleFactory();
}

Upgrade:

    <replace dir="${update}">
      <include name="**/*.java"/> <!-- source-code -->
      <include name="**/*.rst"/> <!-- documentation -->
      <include name="**/*.txt"/> <!-- documentation -->
      <include name="**/*.md"/> <!-- documentation -->
      <include name="**/*.html"/> <!-- package.html -->
      <replacefilter token="org.opengis.style.StyleFactory" value="org.geotools.styling.StyleFactory"/>
    </replace>

Interface refactor to existing GeoTools package

For org.opengis interfaces with no GeoTools equivalent - remove or refactor to existing org.geotools package along side their implementation. Care should be taken to preserve GeoTools naming conventions.

  • org.opengis.coverage.grid can move to org.geotools.coverage.grid

    • Format! → just move it!
    • GridCoordinate → just move it
    • GridCoverage → just move it
    • GridCoverageReader → move it
    • GridCoverageWriter → move it
    • GridEnvelope → safe to move
    • GridGeometry → safe
    • GridNotEditableException → remove
    • InvalidRangeException → remove

Interface refactor to org.geotools.api package

For org.opengis interfaces with no GeoTools equivalent and no suitable GeoTools package - either remove or refactor to org.opengis.api.

BEFORE

package org.opengis.annotation;

...

@Documented
@Target(METHOD)
@Retention(SOURCE)
public @interface Association {
    /**
     * Association name.
     *
     * @return The association name.
     */
    String value();
}

AFTER

package org.geotools.api.annotation;

...

@Documented
@Target(METHOD)
@Retention(SOURCE)
public @interface Association {
    /**
     * Association name.
     *
     * @return The association name.
     */
    String value();
}

Upgrade

    <replacefilter token="org.opengis.coverage.grid" value="org.geotools.coverage.grid"/>
Add a custom footer
Add a custom sidebar
Clone this wiki locally