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 orderIn 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

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.