Coverage IWUG 1: Coverage Core

This proposal, like ISO 19123 itself, relies on the 19107 geometry objects. However, I do not currently know of any 19107 Java implementations. This is not a problem for the interface-only implementation, I guess, but it does make the new interfaces effectively useles until implementations for all the dependant parts are created.

I worked on this today--primarily moved Martin's related work to a org.opengis.coverage.core package in pending and changed a few return/parameter types as per the diagram. I can make a commit as soon as I figure out my svn priviledge issues.

I wonder; should we move the org.opengis.coverage to (idem).core? No other GeoAPI interfaces has a "core" package, and it doesn't seem a common usage in J2SE neither. I understand that this is clash with the legacy org.opengis.coverage.Coverage interface, but as far as I know this is the only problematic interface; all other ones have different names.

Actually, the "clash" with the legacy Coverage interface is somewhat wanted. We will probably need a migration path from the old to the new interface. My intend was to copy all methods from the legacy Coverage interface to the new one, as deprecated methods (so we will remove them in a future version). This means that a Coverage implementation would actually implements both the legacy and the new Coverage interface, until we remove the deprecated methods. This has the good side effect of allowing a transition as smooth as we can.

So (unless there is an other reason than the clash between the old and the new Coverage interface), I would suggest to not move org.opengis.coverage to org.opengis.coverage.core. Instead:

• Copy all interfaces from 'stable' to 'pending' except the Coverage interface. All those interfaces should appears as deprecated interface in 'pending'.
• Copy all methods from the stable Coverage interface to the pending Coverage interface. Marks all those methods as deprecated in 'pending'.

Would it make sense?

ISO 19123 defines seven packages, one of which is "Coverage Core". Making a GeoAPI org.opengis.coverage.core package merely preserves this arrangement. See the proposed package structure in the "Administrative Details" section of : http://docs.codehaus.org/download/attachments/31212/Coverage+Framework+Design.pdf

Any consensus on this? Would be nice to have an agreement before things are committed.

Note about figure 2 (OpenGisCoverageCore.png). Yellow box for ContinuousCoverage said "Current GeoAPI proposal overrides select, evaluate and evaluateInverse to no apparent purpose". The only purpose is documentation. The javadoc is not the same and contains some precisions that do not apply to the method in the parent interface.

The UML proposed in figure 1 and 2 sound fine.

Note about package organisation in "Coverage Framework Design".

Suggested changes (I realize that the first one is the most controversial. Discussion below):

I believe that a common practice in Java is to use the parent package as "core". For example javax.imageio is core, javax.imageio.stream, javax.imageio.metadata, etc. are specialisations. Same apply to javax.swing (core), javax.swing.table, javax.swing.tree, etc. I realize that it pose an apparent conflict with legacy coverage interfaces, but I actually believe that this is not really a problem. "Coverage Framework Design" said:

No determination of the fate of these packages has yet been made. Presumably, they will be deprecated in the first

release which contains the ISO 19123 coverage implementation, and removed in the following release. In any case, there will be a period of time during which the two implementations are required to coexist in the same namespace.

I suggest to amend the text with something like: "ISO 19123 implementation will extends the existing grid coverage implementation. All methods specific to the legacy OGC 01-004 specification, as well as some 01-001 specific interfaces, will be deprecated and removed in a future version."

The rational is that even if the specification change, I believe that a large amount of Geotools implementation would actually stay the same. At the very least, our current GridCoverage2D implementation could continue to exists as a special case of Coverage backed by a RenderedImage. I don't think that there is a need for creating a new implementation and deprecates the old one. Just add the new ISO 19123 methods in the existing implementation and remove (in a future version) the old OGC 01-004 methods. The internal mechanism wrapping a java.awt.image.RenderedImage would stay the same (with possible improvement).

Would it be possible to commit everything to SVN except the move to the core subpackage? After this commit, I would like to commit the legacy coverage interfaces to pending (we will need to do that anyway) and send my proposal for the Coverage interface transition. We could make the move to the core subpackage after that if peoples feel that it is the best thing to do after we take in account the legacy interfaces (right now, they are not taken in account in our discussion).

I committed to SVN the proposed work, along with the changes proposed by Martin (see his comment from Mar 05). There is no core subpackage, and I also moved the coverage interfaces from stable to pending and deprecated them. Also added the methods from Coverage in stable and deprecated them.

The Coverage interface was altered to accomodate methods from the OGC coverage spec. Those methods are labeled as deprecated, as seen on the outline for the Coverage interface.