• Contact: jodygarnett
• Interested Parties: George Percivall (OGC), Stephane Fellah (Image Matters LLC), Kirk Jensen (Image Matters LLC)
• Tracker: N/A
• TLDR: Upgrade to GeoAPI 3.0.0 interfaces
• Branch: N/A

Description

We expect proposals to be used to bounce ideas off the community before you have secured budget for the work. This is your chance to ask for a sanity check, confirm the technical approach and see if you forgot anything (such as documentation or QA requirements). Please present this proposal requirement to your management or customer as a way to reduce risk.

GeoTools makes use of the org.opengis packages to define common data structures for interoperability. These interfaces were defined in collaboration with the GeoAPI project - sadly we are not using the latest stable GeoAPI 3.0.0 release.

GeoAPI 2.3-M3 is the last version used by the GeoTools project:

• GeoTools has made some changes to org.opengis interfaces since that time, for example the Filter interfaces have been upgraded for compatibility with Filter 2.0 multi value use
• GeoAPI has split into the geoapi and geoapi-pending to isolate stable data structures for the 3.0.0 release

This proposal only covers the overlap with geoapi 3.0.0.

I am providing this proposal to determine the amount of work required to upgrade to GeoAPI 3.0.0 interfaces, and determine if any parties are interested in doing the work.

Discussion:

• geotools-gt2-users

References:

• source code: ( GeoTools gt-opengis|GeoAPI 3.0.0 tag )

• javadocs: (GeoTools Latest | GeoAPI Latest )

• GeoAPI 2.3 - excellent resource covering changes made between GeoAPI 2.3-M3 and GeoAPI 3.0.0.

• gt-opengis github commits - record of changes made to geotools in that timeframe

• End of GeoAPI involvement

• Refactor OpenGIS

Proposal: Migrate to GeoAPI 3.0.0

Proposal is to depend on GeoAPI 3.0.0 for stable api (annotation,geometry,metadata,parameter,referencing, util packages). GeoTools will continue to maintain feature, filter and other interfaces that do not conflict with the GeoAPI 3.0.0 release.

In cases where interfaces have been modified introduce an extension allowing client applications a chance to migrate:

interace CompoundCRS2 extends CompoundCRS,CoordinateReferenceSystem {
    /**
     * @deprecated Please use CompoundCRS.getComponents()
     */
    List<CoordinateReferenceSystem> getCoordinateReferenceSystems();
}

In cases where interfaces have been renamed maintain a deprecated extension allowing client applications a clear migration path:

/**
 * @deprecated See Metadata
 */
interface MetaData extends Metadata {
   ...
}

This section can be filled in with details based on a code audit. To start the discussion I am making use of:

• this page describing the changes made between GeoAPI 2.3 M3 and 2.3-M6.
• org.opengis github 3.0.0 tag

:no_entry: conflict, :warning: upgrade, :white_check_mark: no change.

annotation package

• ComplianceLevel
• Obligation
• Profile
• Specification
• UML

Changes to annotation (such as the removal of Extension) should not effect compatibility with downstream applications.

geometry package

• coordinate/Position
• DirectPosition
• Envelope
• MismatchedDimensionException

GeoTools includes considerable "pending" geometry api, which we do not use in our core library. It may be possible to remove the gt-jts-wrapper to gt-geometry modules out and proceed with the minimal interfaces represented above.

Expect only minor changes; although we may wish to propose some "expandToInclude" methods for GeoAPI 3.1.0.

metadata package

• MetaData renamed to Metadata
• CitationFactory removed
• OnLineResource renamed to onlineResource - used as an example below
• Conversion - api changed
• Tranform - api changed
• Operation removed
• RecordType - api changed
• ComplianceLevel - several fields removed
• MetadataExtensionInformation api changed - used as example below
• many small interface changes

Many small interface changes (and new interfaces) so an audit will be required here.

parameter package

Many small changes noted, audit will be required here.

referencing package

Many small changes noted, audit will be required here:

• OperationMethod api change from InternationalString to Formula, int to Integer etc...
• CompoundCRS method removed - used as an example below

util package

• CodeList - api change
• NameFactory - api change
• Record - api change
• RecordSchema - api change
• RecordType - api change

Alternative: GeoAPI 3.1

It may be worth targeting GeoAPI 3.1 currently available as a SNAPSHOT:

• As long as the standard is not fixed there may be room to resolve any differences that have occurred.
• This would require an OGC member to participate with the GeoAPI project an iron out any differences.

Alternative: Classloaders

Effected applications can use seperate classloaders to load both geoapi-3.0.0 and gt-opengis concurrently.

• This approach represents fairly advanced use of Java.
• Stephane Fellah (Image Matters LLC) indicates this inconvenient for downstream developers

Alternative: Migrate Interfaces to org.geotools

What would it take to migrating interfaces to org.geotools and avoiding the use of org.opengis packages?

• While this would only take weeks to do in GeoTools it would necisitate hundreds of hours in downstream applications.
• Method level incompatibilities would prevent an an object implementing both interfaces concurrently - requiring the use of wrappers for interoperability
• Significantly this would preclude further involvement in the GeoAPI project for both GeoTools and downstream projects

Status

Choose one of:

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

Voting:

• Andrea Aime
• Ben Caradoc-Davies
• Christian Mueller
• Ian Turton
• Justin Deoliveira
• Jody Garnett
• Simone Giannecchini

Tasks

This section is used to make sure your proposal is complete (did you remember documentation?) and has enough paid or volunteer time lined up to be a success. Use initials to indicate volunteer, or :warning: where volunteer is neededs. Proposals that lack resources to be successful are unlikely to be approved.

1. Code Audit of changes between gt-opengis and geoapi 3.0.0:

   We need to determine what has changed prior to planning the upgrade. It may be easier to do this on a branch by changing the dependency and seeing what has broken.

2. Change dependency:

   • Add dependency on geoapi 3.0.0
   • Remove duplicated interfaces from opengis module
   • Extend interfaces as required for compatibility or clarification (see code example below for an example)

3. Migrate implementations to changed interfaces.

   • This task will need to be filled in based on the result of the code audit above.

4. Migrate GeoTools documentation and code examples to changed interfaces

5. Provide update instructions for geotools user manual

   • upgrading page.

6. Coordinate migration with effected downstream projects:

   • GeoServer:
   • GeoGig:
   • GeoMesa:
   • GeoScript
   • uDig

7. Issue a milestone release for early feedback.

API Change

This section will need to be fill in after a comparison between gt-opengis interfaces and geoapi 3.0.0.

Handling a modified Interface

Before contents of gt-opengis include:

interface CompoundCRS {
    List<CoordinateReferenceSystem> getComponents();
}

After:

interface CompoundCRS2 extends CompoundCRS {
    /**
     * @deprecated Please use CompoundCRS.getComponents()
     */
    List<CoordinateReferenceSystem> getCoordinateReferenceSystems();
}

Client code inside GeoTools should be updated to reference the getComponents() method.

Downstream projects will no longer compile:

• Where possible interfaces such as CompoundCRS2 will be introduced providing the expected method signature
• This will allow client code to blinding replace CompoundCRS with CompoundCRS2 to get their application to compile

Handling a renamed Interface

Before contents of gt-opengis include:

interface OnLineResource {
   ...   
}

interface MetadataExtensionInformation {
   ...
   OnLineResource getExtensionOnLineResource();
   ...
}

After:

/**
 * @deprecated The interface MetaData has been renamed as Metadata
 */
interface OnLineResource extends OnLineResource {
   ...
}

/**
 * @deprecated See MetadataExtensionInformation
 */
interface MetadataExtensionInformation2 extends MetadataExtensionInformation {
   ...
   OnLineResource getExtensionOnLineResource();
   ...
}

Client code inside GeoTools should be updated to reference the renamed OnlineResource interface.

Downstream projects will no longer compile:

• Client code will be advised of the rename with deprecation warnings
• Where possible interfaces such as MetadataExtensionInformation2 will be provided - making use of type narrowing to explicitly return the expected type