Skip to end of metadata
Go to start of metadata

Contact:

Daniele Romagnoli

Tracker:

http://jira.codehaus.org/browse/GEOT-4424

Tagline:

GridCoverageReader API

Children:

Description

The current implementation status of the GridCoveargeReader normally associates a single reader with a single coverage (e.g., TIFF, GTOPO30, and so on). The intention of this proposal is to break the 1-1 association and allow GridCoverageReader to expose multiple covearges in an efficient way, in order to properly deal with sources storing multiple coverages with different structures and features (e.g., not mosaics, which can deal with multiple coverages having some degree of uniformity).

The current GridCoverageReader interface already allows to expose multiple coverages, but in an inefficient and thread unsafe way, as it is intended to read GridCoverages from the input stream in a sequential order  In order to access different coverages, once the reader is open, one needs to check if more coverages are available by checking hasMoreGridCoverages and then skip to the desired coverage, and get the name of current coverage through the getCurrentSubname method.  Thus, there are two issues:

  • Need to open a new reader for each different coverage read, which is rather inefficient as normally the opening of a reader requires parsing the raster data header, or gathering network or database connections, something that is better done only once instead 
  • Need to linearly scan the contents of the reader to reach the desired coverage, with no form of random access, hampering the usage of the current API in storages that contain a large amount of coverages
The idea is to deprecate this methods in favor of methods which allow explicitly specifying the coverage to be accessed, thus allowing random access to the various coverages and their descriptive information from a single reader instance. In order to preserve backwards compatibility the methods to get the coverage metadata will be maintained, and new methods taking the coverage name as an extra parameter will be added to allow clients selection of a specific coverage provided by the reader.
Finally, a simple observation of the code using reader will show that nowadays pretty much all code casts reader to AbstractGridCoverage2DReader in order to gain access to more meta information about coverages, in particular the grid coverage locacation and grid structure. In order to promote programming against interfaces a new GridCoverage2DReader interface will be created sporting the same common methods AbstractGridCoverage2DReader provides, along with variants that take the coverage name as a parameter.

Additional notes on base implementation changes:

Base class implementing GridCoverageReader is AbstractGridCoverage2DReader. The implementation of AbstractGridCoverage2DReader will be changed so that implementors of the current API won't be affected by the change, but allowing new multi-coverage readers to get full benefit from the new API

An outlook into the future

This work is meant as a stepping stone to allow a smooth transition between old style coverage APIs (based on current GridCoverageReader which doesn't have proper logic to deal with time/elevation domains) and new coverage-api currently living on unsupported/coverage-experiment, and loosely based on the DataAccess paradigm, as well as the WCS protocol, which allows for

  • proper geospatial dimensions management (time domain, vertical domain, custom domains) without having to deal with lists of strings
  • a single coverageAccess to deal with multiple underlying coverage sources
The idea is that bridges will be built so that implementations using the new coverage API can be wrapped in the GridCoverage2DReader one, and that similarly old implementations can be wrapped into the new one, allowing for a period of transition between the two programming styles.

Status

This proposal is under construction.

Voting has not started yet:

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

 

no progress

(tick)

done

(error)

impeded

(warning)

lack mandate/funds/time

(question)

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

GridCoverageReader

BEFORE:

AFTER:

GridCoverage2DReader (new interface extending GridCoverageReader)

Default implementation changes

AbstractGridCoverage2DReader

BEFORE:

AFTER:

Code Examples

BEFORE:

AFTER:

Documentation Changes

list the pages effected by this proposal

Labels
  • None