Q/A: CodeList and UML

[paulushub]

Please, I just need information on CodeList, maybe you can enable the discussion forum for this type of "issues".

1. All the implementations of the CodeList<E> so far in the repository seem to be final. Is there any current case of an implementation of the CodeList being further extended in the repository?
2. How much practical value is there to the use of UML annotations, and need to have UML identifier in the CodeList?

It seems the basic idea of enumerations being lightweight objects is completely gone in the CodeList implementations.

[desruisseaux]

Hello

I thought that GitHub discussions were already enabled, aren't they?

All the implementations of the CodeList so far in the repository seem to be final. Is there any current case of an implementation of the CodeList being further extended in the repository?

There are cases where the set of values of a CodeList needs to be extended (i.e., custom values added), but I'm not aware of cases where a CodeList subclass itself needs to be extended. For example, in order to create a new AxisDirection, the following code can be used:

public static final AxisDirection MY_CUSTOM_DIRECTION = AxisDirection.valueOf("MyCustomDirection");

The fact that valueOf(String) creates a new value when there is no match for the given string is the most important difference between CodeList and Enum. The rest is pretty much inspired by Enum, including the fact that the subclasses are final. Do you have a case where the above is not sufficient and there is a need to extend a subclass?

How much practical value is there to the use of UML annotations, and need to have UML identifier in the CodeList?

UML annotations are not mandatory. They should be provided only when the code list value is derived from an OGC / ISO standard. If the code list value is a custom value, then it should not have UML annotation.

The UML annotation purpose is documentation (point back to the international standard definition), but also for reflection. For example, the names used in Java may differ from the names used in OGC / ISO standard because GeoAPI adapts the API to Java conventions (e.g. constants in upper-case letters), while XML and JSON schemas use the names as defined by OGC / ISO standards. The UML annotations do the mapping between the two. A little bit like @XmlElement annotations in JAXB, which establish a mapping between Java and XML. @UML annotations establish the mapping between GeoAPI and OGC/ISO abstract standards.

It seems the basic idea of enumerations being lightweight objects is completely gone in the CodeList implementations.

CodeList are not enumerations. Actually, OGC/ISO standards and GeoAPI use both of them: Enum and CodeList. The difference between the two is explained in ISO 19103. But in brief, Enum are used when we intentionally want to forbid any extension (closed universe), while CodeList are used when we want to allow users to add their own values (open universe).

[paulushub]

I thought that GitHub discussions were already enabled, aren't they?

It is now enabled and showing in the tabs, thanks.

The UML annotation purpose is documentation

That is what I got so far, and felt it could simply be part of the JavaDoc - as usual simple is best!

Do you have a case where the above is not sufficient and there is a need to extend a subclass?

No, I just felt this and some of the classes should not be part of an API, giving the developer the free hand to make choices.
Some of these classes use other Java classes making the API "too Java" in nature.
Some code-list types like GeometryType could simply be normal enum type (or where necessary, for a C# developer, a value-type could be used instead of the classes).

CodeList are not enumerations.

Understood, and as I have said, my thought is the CodeList class may not be of much value to the developer.
An interface could be sufficient here, and since much of the GeoAPI is autogenerated, the enumerations could be autogenerated with no need for the CodeList class and all the reflection procedures implemented, which I think adds some overheads to rather simple objects.

Providing too much in an API, restricts implementation choices that could make the GeoAPI less attractive.
The original OGC specifications for Simple Features was provided in OLE/COM and CORBA, making it simple and easy to port to any language.

Thanks so much for the reply and for providing the information - I really appreciate it.
NOTE: Please can you transfer this thread to the discussion forum? I do not have the right to do that.

[desruisseaux]

The UML annotation purpose is documentation

That is what I got so far, and felt it could simply be part of the JavaDoc - as usual simple is best!

There is also a "but also for reflection" part. The need to map Java names to OGC/ISO standard names is important. It happens during parsing of XML or JSON documents, or even in URLs. Example:

<cit:CI_RoleCode
    codeList="http://standards.iso.org/iso/19115/resources/Codelist/cat/codelists.xml#CI_RoleCode"
    codeListValue="originator"/>

When an application receives such URL, it needs to know that originator in CI_RoleCode in ISO standard maps to RoleCode.ORIGINATOR in GeoAPI, and conversely. This is not always only a matter of lower case versus upper case.

Some of these classes use other Java classes making the API "too Java" in nature

GeoAPI defines a set of classes for each language, witch each set adapted to the target language. We have Java (above discussion) and also a set of Python abstract classes under development, which sometime makes different choices. If we had a volunteer for deriving a set of C# interfaces, they would probably be slightly different than the Java ones.

Some code-list types like GeometryType could simply be normal enum type

It is not our choice. Whether a type is an Enum or a CodeList is defined by the ISO standard, and GeoAPI simply follows what the standard decided. As said above, the Enum versus CodeList concept come from OGC/ISO standards, this is not something that GeoAPI invented. In that particular case, ISO 19115-2:2019 decided that GeometryType is a code list.

An interface could be sufficient here

We indeed use interfaces everywhere it is possible. But in the particular case of code lists, we cannot provide the code list values defined by OGC/ISO standards without a concrete class.

[paulushub]

When an application receives such URL, it needs to know that originator in CI_RoleCode in ISO standard maps to
RoleCode.ORIGINATOR in GeoAPI, and conversely. This is not always only a matter of lower case versus upper case.

Do I need a reflection to implement that? No, not necessarily. So it is an implementation decision that an API should not be enforcing.

It is not our choice. Whether a type is an Enum or a CodeList is defined by the ISO standard

I understand you, but enum is language specific: a Java enum is a special class and not the same as a C/C++ or C# enum.
Java interfaces have every field public, static and final:

public enum Country {
    USA(38.8951, –77.0364, “Washington D.C.”),
    GERMANY(52.5200, 13.4050, “Berlin”);
 
    private final double latitude;
    private final double longitude;
    private final String capital; 

    Country(double latitude, double longitude, String capital) {
        this.latitude = latitude;
        this.longitude = longitude;
        this.capital = capital;
    } 

    public double getLatitude() { return latitude; }

    public double getLongitude() { return longitude; }

    public String getCapital() { return capital; }
}

In C# for instance, I have a choice of using the value-type or class to implement that.

[desruisseaux]

The way that CodeList are translated to the Java language is not a requirement to do the same in other languages. If we wanted to do a "GeoAPI in C#" (volunteer welcome), that profile would be free to translate OGC/ISO CodeList in the way that is most suitable to C#. The CodeList classes done in Java could be used as a source of inspiration, but nothing more. In particular, I would not recommend to translate the Java classes or interfaces to C# using some automatic translation tools and use that as the C# API. I would expect a human to use her/his own judgment for adapting the output before we can call that a C# API.