gridenvelope subclasses replacing deprecated gridrange subclasses

• Motivation: being sick of deprecated and/or duplicated classes

• Tracker: https://osgeo-org.atlassian.net/browse/GEOT-2481

Description

During summer 2008 some changes happened inside the coverage module of GeoTools, specifically GridRange and its implementations where deprecated in favor of GridEnvelope and its implementations since the latter is used in ISO 19123 while the former was introduce by the defunct Grid Coverage Implementation Specification (notice that there was NO discussion about whether or not to apply this change but it was just done overnight, see http://n2.nabble.com/GeneralGridEnvelope-vs-GeneralGridRange-tt1958466.html).

Now the result is that all the modules/plugins/projects using the GridRange sublcasses woke up and found out that they were using a deprecated class, this means that all the coverage plugins, as well as GeoServer code was injected with even more deprecation warnings. In this proposal I am going to assume that we still try to follow GeoApi but the fact mentioned above clearly demands some thinking over the role of GeoApi and how it evolves outside our control. On the other side the goal of this proposal is to remove the deprecated classes from GeoTools trunk and fix all the errors that will pop up. I will volunteer to fix also GeoServer trunk.

The change is small but triky. GridRange from GC IS lists upper coordinates as exclusive, much like JAVA2D does for Rectangle2D and its subclasses, Raster and its subclasses and also RenderedImage and its subclasses. On the other side, GridEnvelope lists its upper coordinates in inclusive mode (this is dictated by ISO 19123). Now beside the fact that this GeoApi change opens up a lot of room for confusion since it works the opposite way with respect to what a Java developer would expect, since we have a strong dependency on GeoApi the fact that right now we have 2 similar classes that have different behavior worries me a bit, therefore I'd like to clean u the deprecated ones, replacing them with the newest ones and writing some doc for the new behavior (see upgrade to 2.6.

Status

This proposal is ready the work has been done.

Voting has not started yet:

• Andrea Aime
• Ben Caradoc-Davies: +1
• Ian Turton
• Justin Deoliveira: +1
• Jody Garnett +1
• Simone Giannecchini
• Michael Bedward +1

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

        | :white_check_mark: | :no_entry: | :warning:               | :negative_squared_cross_mark: |

------------|--------------------|------------|-------------------------|-------------------------------| no progress | done | impeded | lack mandate/funds/time | volunteer needed |

1. API changed based on BEFORE / AFTER
2. Update default implementation
3. Update wiki (both module matrix and upgrade to to 2.5 pages) |
4. Remove deprecated code from GeoTools project
5. Update the user guide
6. Update or provided sample code in demo
7. review user documentation

API Changes

BEFORE

1. Use getSpan where getLength was used
2. Be EXTREMELY careful with the convetions for the inclusion/exclusion of the maximum coordinates
3. GridRange2D IS a Ractangle and is mutable now!

import org.geotools.coverage.grid.GeneralGridRange;
final Rectangle actualDim = new Rectangle(0, 0, hrWidth, hrHeight);
final GeneralGridRange originalGridRange = new GeneralGridRange(actualDim);
final int w = originalGridRange.getLength(0);
final int maxx = originalGridRange.getUpper(0);
 
...
import org.geotools.coverage.grid.GridRange2D;
final Rectangle actualDim = new Rectangle(0, 0, hrWidth, hrHeight);
final GridRange2D originalGridRange2D = new GridRange2D(actualDim);
final int w = originalGridRange2D.getLength(0);
final int maxx = originalGridRange2D.getUpper(0);
final Rectangle rect = (Rectangle)originalGridRange2D.clone();

AFTER

import org.geotools.coverage.grid.GeneralGridEnvelope;
final Rectangle actualDim = new Rectangle(0, 0, hrWidth, hrHeight);
final GeneralGridEnvelope originalGridRange=new GeneralGridEnvelope (actualDim,2);
final int w = originalGridRange.getSpan(0);
final int maxx = originalGridRange.getHigh(0)+1;


import org.geotools.coverage.grid.GridEnvelope2D;
final Rectangle actualDim = new Rectangle(0, 0, hrWidth, hrHeight);
final GridEnvelope2D originalGridRange2D = new GridEnvelope2D(actualDim);
final int w = originalGridRange2D.getSpan(0);
final int maxx = originalGridRange2D.getHigh(0)+1;
final Rectangle rect = (Rectangle)originalGridRange2D.clone();

Documentation Changes

list the pages effected by this proposal

• Upgrade to 2.6