DirectPosition.getCoordinates() should be singular

ISO 19111 said:

In this International Standard, a coordinate is one of n scalar values that define the position of a single point. In other contexts, the term ordinate is used for a single value and coordinate for multiple ordinates. Such usage is not part of this International Standard.

A coordinate tuple is an ordered list of n coordinates that define the position of a single point. In this International Standard, the coordinate tuple shall be composed of one, two or three spatial coordinates.

However other standards (ISO 19107, ISO 19123) seems to use "coordinate" in the sense of "coordinate tuple". The following classes are singular in ISO standards:

• TM_Coordinate in ISO 19108
• CV_GridCoordinate in ISO 19123. Note that the ISO document mixes the singular and plural forms (both in textual description and in UML diagrams), but the later seems to be a typo since the section which is precisely about CV_GridCoordinate uses the singular form.

We need to bring a little bit more consistency in GeoAPI. Using the singular form seems reasonable, but in such case we need to rename GridCoordinates as well:

• TemporalCoordinate javadoc
• GridCoordinates javadoc

In the particular case of DirectPosition.getCoordinates(), we are returning an array of double primitive type, not a single object. The singular form would be appropriate for the class name (so GridCoordinates needs to be renamed). But for this method returning an array, I think that "coordinates" is to be understood in the ISO 19111 sense (see above comment), so the plural form would be appropriate.

However I admit that this is confusing given the various interpretation given to "coordinates". A possible fix is to name this method as "getCoordinateValues()" instead. It would have the beneficial side-effect to be consistent with method names in GridCoordinate and TemporalCoordinate (see javadoc links in above comment).

If we perform such renaming, then we need to consider if we should rename get/setOrdinate(int) as get/setCoordinateValue(int) for consistency.

Yes, 19111 has a non-mathematical, sloppy use of coordinate for ordinate. The only consistency we could salvage from this mess would be to use ordinate for the single numerical value and tuple for the grouped set of coherent values, deprecating all uses of coordinate. That's probably too radical a move so we are stuck trying to be consistent across less than the whole library. At least within a particular module it's critical to be internally consistent. ISO Geometry, aka 19107, is internally perfectly consistent and matches standard mathematical language so there appears no reason to break that internal consistency to match other specs written by people closer to geodesy than to geometry.

Did you really mean getCoordinateValue*s*() ? That's getting even more confusing.

I don't really buy the "you have to have a class to have a single structure" argument. An array of data is a perfectly acceptable single data structure so getCoordinate(): double[] seems perfectly clear from that stand point.

That said, if we want to emphasize that we are always returning the data by value and not by reference, we could append "value" to all our method names. To be consistent we start having to rename all methods to get*Value()---it seems easier to state in the javadoc that data elements are passed out by value and not by reference. We need to do this anyhow since we can't really have methods getDirectPositionValue().

So far given the choices, the original modification still seems the best.

Commited as of revision 1251.