Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 28 Next »


Daniele Romagnoli



GridCoverageReader API



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.


This proposal is under construction.

Voting has not started yet:



no progress






lack mandate/funds/time


volunteer needed

  1. AA: API changed based on BEFORE / AFTER
    • GridCoverageReader
    • GridCoverage2DReader extends GridCoverageReader
    • AbstractGridCoverage2DReader
  2. AA: Update code to use the new interface instead of casting to AbstractGridCoverage2DReader (there will be a similar follow up in GeoServer)
  3. JG: Update documentation to use the new interface
    • Fix examples to use interface (rather than cast to AbstractGridCoverage2DReader) 
    • Make up an example on how to access more than one coverage




GridCoverage2DReader (new interface extending GridCoverageReader)

Default implementation changes




Code Examples



Documentation Changes

list the pages effected by this proposal

  • No labels