GeoAPI
  1. GeoAPI
  2. GEO-51

Revisit the collection type choosen for some properties

    Details

    • Type: Bug Bug
    • Status: Closed Closed
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: 2.0
    • Fix Version/s: 2.0
    • Component/s: metadata
    • Labels:
      None
    • Number of attachments :
      0

      Description

      When a method in 'org.opengis.metadata' need to returns a collection, almost all of them returns java.util.Set. It was assumed that all those collections should not contains duplicated values.

      While a Set is often considered as unordered, it doesn't have too. For example java.util.TreeSet and java.util.LinkedHashSet are two Set implementations that preserve some ordering semantic.

      However, for some properties, it has been reported that ordering may be more important than uniqueness. For example in Address.getDeliveryPoints(), the order of delivery points is important for human readability.

      We could changes the return type from Set to List for this particular property. However, it would be a little bit odd to have only one List and Set everywhere else... There is probably other properties for which ordering is more important than uniqueness.

      I suggest to report in this JIRA task some other properties that may benefict from a collection type change.

        Issue Links

          Activity

          Hide
          Martin Desruisseaux added a comment -

          For now there is three votes in favor of java.util.List (Stephane, Jody, Frederic), and 0.5 vote in favor of java.util.Set (weakly me; I don't have a strong feeling about that). If there is no additional comments, I will replace Set by List next week before GeoAPI 1.1 release.

          Show
          Martin Desruisseaux added a comment - For now there is three votes in favor of java.util.List (Stephane, Jody, Frederic), and 0.5 vote in favor of java.util.Set (weakly me; I don't have a strong feeling about that). If there is no additional comments, I will replace Set by List next week before GeoAPI 1.1 release.
          Hide
          Martin Desruisseaux added a comment -

          We may have an issue with java.util.List in the context of databases. For example, in Geotools, there is an implementation of metadata interfaces that fetch the values directly from a database. If there is no "ORDER BY" clause in the "SELECT" statement, then the database may returns the results in any order. It even doesn't need to be consistent between two queries of the same attribute. Using a java.util.List return type instead of java.util.Set will force all database-backed implementations to add an "ORDER BY" clause in their "SELECT" statement. Is it a desirable constraint? Is the performance cost significant?

          On a related note: what are the use cases for accessing an element by index? For example in Citation.getAlternateTitles(), why a user would wants to ask for a title at a particular index? Those use cases need to be put in balance with the above-cited possible constraints on database-backed implementations.

          Show
          Martin Desruisseaux added a comment - We may have an issue with java.util.List in the context of databases. For example, in Geotools, there is an implementation of metadata interfaces that fetch the values directly from a database. If there is no "ORDER BY" clause in the "SELECT" statement, then the database may returns the results in any order. It even doesn't need to be consistent between two queries of the same attribute. Using a java.util.List return type instead of java.util.Set will force all database-backed implementations to add an "ORDER BY" clause in their "SELECT" statement. Is it a desirable constraint? Is the performance cost significant? On a related note: what are the use cases for accessing an element by index? For example in Citation.getAlternateTitles(), why a user would wants to ask for a title at a particular index? Those use cases need to be put in balance with the above-cited possible constraints on database-backed implementations.
          Hide
          Martin Desruisseaux added a comment -

          ISO 19115 make a clear distinction between "set" and "sequence". Quoting section B.4.7 at page 78:

          — begin quote —

          Set: finite collection of objects, where each object appears in the collection only once. A set shall not contain any duplicated instances. The order of the elements of the set is not specified. This class is documented in full in ISO TS 19103.

          Sequence: A sequence refers to a collection of sequential ordering between its elements. Sequences can be repeated, and may be used as a list or an array. This class is documented in full in ISO TS 19103.

          — end quote —

          Unfortunately, ISO 19115 provides very few hints about the expected collection type for attributes. The only explicit indications I have found are:

          • MD_GridSpatialRepresentation.axisDimensionProperties : Sequence<MD_Identifier>
          • MD_Georectified.cornerPoints : Sequence<GM_Point>
          • ScopeDescription.attributes : Set<GF_AttributeType>
          • ScopeDescription.features : Set<GF_FeatureType>
          • ScopeDescription.featureInstances : Set<GF_FeatureType>

          For all other attributes, I have done a search on "set" and "sequence" keywords and found no hint at all. It is worth to point out that in the above list, all element types except MD_Identifier are external to ISO 19115. The MD_GridSpatialRepresentation.axisDimensionProperties attribute is treated especially since it seems to be the only association to an other ISO 19115 object in which the collection type is explicitly specified. Clearly, axis order matter since it is an essential information for understanding coordinate tuples (e.g. (latitude, longitude) vs (longitude, latitude)). For all other associations, Set may be a default collection type. Sequence could be a default collection type too. None of them seem to violate the specification...

          My bet is that Set is the default collection type, because it is consistent with 1) the collection type of non-ISO 19115 objects (namely GF_AttributeType and GF_FeatureType), assuming that the collection appears explicitly as an attribute in ISO 19115 because there is no association to non-ISO 19115 objects and 2) the only place where the type of a collection of ISO 19115 objects is explicitly specified is for Sequence<MD_Identifier>.

          It doesn't means that GeoAPI can't use List, since ISO 19115 seems quite open on this issue. The question still open...

          Show
          Martin Desruisseaux added a comment - ISO 19115 make a clear distinction between "set" and "sequence". Quoting section B.4.7 at page 78: — begin quote — Set: finite collection of objects, where each object appears in the collection only once. A set shall not contain any duplicated instances. The order of the elements of the set is not specified. This class is documented in full in ISO TS 19103. Sequence: A sequence refers to a collection of sequential ordering between its elements. Sequences can be repeated, and may be used as a list or an array. This class is documented in full in ISO TS 19103. — end quote — Unfortunately, ISO 19115 provides very few hints about the expected collection type for attributes. The only explicit indications I have found are: MD_GridSpatialRepresentation.axisDimensionProperties : Sequence<MD_Identifier> MD_Georectified.cornerPoints : Sequence<GM_Point> ScopeDescription.attributes : Set<GF_AttributeType> ScopeDescription.features : Set<GF_FeatureType> ScopeDescription.featureInstances : Set<GF_FeatureType> For all other attributes, I have done a search on "set" and "sequence" keywords and found no hint at all. It is worth to point out that in the above list, all element types except MD_Identifier are external to ISO 19115. The MD_GridSpatialRepresentation.axisDimensionProperties attribute is treated especially since it seems to be the only association to an other ISO 19115 object in which the collection type is explicitly specified. Clearly, axis order matter since it is an essential information for understanding coordinate tuples (e.g. (latitude, longitude) vs (longitude, latitude)). For all other associations, Set may be a default collection type. Sequence could be a default collection type too. None of them seem to violate the specification... My bet is that Set is the default collection type, because it is consistent with 1) the collection type of non-ISO 19115 objects (namely GF_AttributeType and GF_FeatureType), assuming that the collection appears explicitly as an attribute in ISO 19115 because there is no association to non-ISO 19115 objects and 2) the only place where the type of a collection of ISO 19115 objects is explicitly specified is for Sequence<MD_Identifier>. It doesn't means that GeoAPI can't use List, since ISO 19115 seems quite open on this issue. The question still open...
          Hide
          Martin Desruisseaux added a comment -

          Since ISO 19115 seems very carefull for giving no clue between "Set" and "Sequence" (List), it has been suggested that the intend is to lets the choice to implementor. Concequently, java.util.Collection may be the most appropriate choice.

          Show
          Martin Desruisseaux added a comment - Since ISO 19115 seems very carefull for giving no clue between "Set" and "Sequence" (List), it has been suggested that the intend is to lets the choice to implementor. Concequently, java.util.Collection may be the most appropriate choice.
          Hide
          Martin Desruisseaux added a comment -

          Replaced all Set and List in metadata packages by Collection, except in the very few places where the collection type is explicitly defined by ISO 19115.

          Show
          Martin Desruisseaux added a comment - Replaced all Set and List in metadata packages by Collection, except in the very few places where the collection type is explicitly defined by ISO 19115.
          Hide
          Martin Desruisseaux added a comment -

          GeoAPI 2.0 has been released. Consequently the choosen type (namely Collection) should not change anymore.

          Show
          Martin Desruisseaux added a comment - GeoAPI 2.0 has been released. Consequently the choosen type (namely Collection) should not change anymore.

            People

            • Assignee:
              Martin Desruisseaux
              Reporter:
              Martin Desruisseaux
            • Votes:
              0 Vote for this issue
              Watchers:
              0 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved: