GeoTools : Naming policy for GeoAPI implementation classes


Make GeoAPI implementation class names consistent


Martin Desruisseaux





Implementation of GeoAPI classes have different naming pattern in different modules. In the referencing module, they are prefixed with Default or Abstract. In the metadata module, they are suffixed with Impl. This proposal is about a more consistent pattern to be applied at least accross the metadata, referencing and coverage modules. More specifically we suggest to adopt the Default/Abstract prefix scheme used in referencing, and rename all metadata implementation classes accordingly.

Why Default/Abstract prefix instead of Impl suffix

  • Prefix allow us to see at a first glance which classes are GeoAPI implementations and which ones are GeoTools specific. The argument for Impl suffix was to preserve alphabetical order. However experience suggests that it is not so convenient, since it is often more useful to distinguish between GeoAPI implementations and GeoTools specific classes. The GeoAPI implementation could be hiden from the "beginer" javadoc (make is visible only to "advanced" users). Most users could be encouraged to read the GeoAPI javadoc instead.
  • Distinguish between abstract and concrete ISO classes. Classes that are abstract according ISO are not necessarly abstract in GeoTools implementation. For example AbstractCS (the base class for DefaultCartesianCS, DefaultVerticalCS, etc.) is abstract according ISO, but not in the Java sense since it can be instantiated. Actually AbstractCS is really instantiated in a few cases by the WKT parser, meaning "I really don't know what this coordinate system is; I just know its axes" (this case occurs because of limitations in WKT syntax).
  • Make abstract classes to appear before concrete ones in alphabetical order.
  • Consistency with usage in the JDK collection framework.

Example: The CRS package has the following classes. We can see immediately that CRS, SingleCRS and DerivedCRS are abstract (in ISO sense), and that UnprefixedMap has nothing to do with GeoAPI classes. We would like the same advantages for metadata.


Proposed action

  • Rename all metadata implementation classes, replacing the Impl suffix by Default or Abstract depending on whatever the class is abstract or not according ISO.
  • Refactor the old Impl classes as extending the new renamed classes, and deprecate them for GeoTools 2.5 release.
  • Delete the deprecated Impl classes on trunk after GeoTools 2.5 release.

No other classes than metadata would be renamed at this stage; current class names in referencing and coverage are considered okay.

Note that a few referencing and coverage classes use other prefix than Abstract or Default. For example "General" in GeneralEnvelope to stress-out its n-dimensionsl aspect compared to Envelope2D, or "Grid" in GridSampleDimension to stress-out that they apply to GridCoverage rather than arbitrary Coverage. This is okay and don't need to be forced into a Default/Abstract naming scheme. The above is just a proposed rule of thumbs, not a strict rule.

Voting is open:

Community support:


Hi Martin two things - on a procedure side:

  • show us what you mean to change with a before and after API section
  • list the documentation pages that you mean to change (there are docs on metadata and they would need to be updated)

And on the content side - I am sorry this is the first proposal I need to vote -1 on ... we need to transition this code to use a Factory. There is no reason for any code to know the names of our metadata implementation; change the code to use a Factory and make these implementations private. So does GeoAPI provide a Factory? If not it is time to ask for one...

Sorry to give feedback as a comment; I am away from email right now.

Posted by jive at Jun 23, 2008 06:28

An open question that is not yet resolved for a metadata factory is whatever we should create a large set of methods (approximatively 100), some of them having lot of paremeters (e.g. 20) which would leads to what I call "the monster factory", or if we should create a single simple methods relying on Java reflection. The former is big, unconvenient and hard to make evoluate but type safe, while the later is small, more flexible and adaptable to future changes but without type safety.

An third approach would have been to create mutable metadata. But we have choosed to disalow that (at least partially) after some debate, through the declaration of return types in the form of Collection<? extends Foo> rather than Collection<Foo>. I was in favor of the later, but the former win in order to accomodate Hibernate implementation. At that time I was unable to check if they were really no way to make Hibernete works with Collection<Foo>. Later we got experience with JAXB, which work with annotations in a similar way. We realized that JAXB doesn't work with Collection<Foo> out of the box (it asks for Collection<? extends Foo> as well), but we can make it work through the use of adapters. I would expect Hibernate to have a similar adapter mechanism, so (if this is true) we could consider reverting to the Collection<Foo> form and allow metadata to be mutable.

Posted by desruisseaux at Jul 18, 2008 02:39