Interface PeriodDuration

[paulushub]

This interface is marked as Effectively deprecated — use java.time.Duration instead.
I do not understand the recommendation here: Why not use PeriodDuration, which part of the ThreeTen-extra?
Documented as:
An amount of time in the ISO-8601 calendar system that combines a period and a duration.

[desruisseaux]

The main reason is to avoid dependency to external projects. OGC standards try to be implementation-neutral. The only GeoAPI dependency is JSR-363, which is itself another implementation-neutral standard. Adding a dependency to ThreeTen-extra would be choosing a particular implementation (not a JAR defined by a standardisation body), and would impose that choice to all GeoAPI users.

Furthermore, some users are very reluctant to projects having many dependencies. For them, each extra dependency is extra work for scanning the JAR for security issues.

In the particular case of PeriodDuration, adding an extra dependency seems a high price for a feature that is partially covered by the standard Java library (the org.threeten.extra.PeriodDuration classes has many similarities with java.time.Duration). But anyway, while the GeoAPI documentation suggests to use Duration, the actual API uses the TemporalAmount interface, thus letting users choose the implementation (both Duration and PeriodDuration implement that interface).

[paulushub]

Thanks, but this use java.time.Duration instead is the issue as Duration is not necessarily PeriodDuration,
which be Duration, Period or both (by the ThreeTen implementation - I have no access to the ISO doc),
and this issue seems to map it to Period: #94

[paulushub]

Clearly, there is more to this whole stuff and requires a careful analysis, and naming.
Wikipedia ISO 8601 description of the Duration/Period seems to match the Java implementations: Example of a duration

For example, "P3Y6M4DT12H30M5S" represents a duration of "three years, six months, four days, twelve hours, 
thirty minutes, and five seconds".

And it stated: P is the duration designator (for period) placed at the start of the duration representation.
Meaning: P3Y6M4D is the Period, matching the Java implementation.

The reason is that ISO 19108 Instant has an indeterminatePosition attribute which does not exist in java.time
and which appeared to be used a lot in the GML documents that we saw.

Looking at the GeoTools GML docs, the indeterminatePosition seems to be from TimePositionType.
And, your description of the Period here seems to be Interval, which is also part of Threeten-Extra,
where the start and end are instances of Instance.

[desruisseaux]

Yes, ISO 8601 is much more widespread than ISO 19108. So it is not surprising that in case of disagreement in the definition of terms between ISO 8601 and 19108, the former prevails in standard Java API. For GeoAPI, the problem is that the ISO standards used here reference explicitly ISO 19108. Therefore, GeoAPI follows ISO 19108 naming even if it disagrees with ISO 8601. We may rename Period if the risk of confusion is considered too high, but I don't know what could be a better name. An alternative could be better documentation.

About indeterminatePosition, indeed it is defined in TM_TemporalPosition (I just verified in my copy of ISO 19108:2002). In that specification, TM_Instant has a position property (actually an association) of type TM_Position, which is an union of various types including TM_TemporalPosition. Therefore, you are right that indeterminatePosition does not appear in the TM_Instant type according ISO 19108. Instead, it appears (indirectly) under the position property. However, if we want to replace as much ISO 19108 types as possible by java.time interfaces, then the closest match that I can see for the position property is java.time.temporal.Temporal. That interface allows many different java.time implementations, which matches the fact that in ISO 19108, position is an union giving a lot of flexibility on the actual type. If we do that, then since java.time has no concept of indetermine position, we have to put this attribute elsewhere. Hence, the proposal to put it in org.opengis.temporal.Instant.

[paulushub]

On this

However, if we want to replace as much ISO 19108 types as possible by java.time interfaces

And searching provides some bits of ISO 19108 definition of
TM_Instant as

An instant is a zero-dimensional geometric primitive that represents position in time. It is equivalent to a point in
space. In practice, an instant is an interval whose duration is less than the resolution of the time scale.

TM_Period as

The period is a one-dimensional geometric primitive that represents extent in time. The period is equivalent to a
curve in space. Like a curve, it is an open interval bounded by beginning and end points (instants), and has length
(duration). Its location in time is described by the temporal positions of the instants at which it begins and ends; its
duration equals the temporal distance between those two temporal positions.

My little understanding is, we are dealing with two different concepts here; one specifically about time ISO 8601, and the other about positional time ISO 19108 (as in An instant is a zero-dimensional geometric primitive that represents position in time) as required in geographical information.
Example: ISO 8601 (the current time in London), ISO 19108 (current time at a location in London) - here the positional data makes the information different for different locations in London, and London itself will only matter for a time-zone.
Therefore, ISO 8601 is a subset of ISO 19108, and should be treated as such - it can represent the time in position in time. Direct mapping could only lead to problems.

In this case, you can adapt naming that reflect that:
TemporalInstance, TemporalPeriod, TemporalDuration, TemporalPeriodDuration etc. which can extend the java.time.Temporal
or something like:
PositionalInstance, PositionalPeriod, PositionalDuration etc. which will not extend java.time.Temporal.

Simply put, adapt naming that makes it look different from the java.time types to avoid any source of confusion.

[desruisseaux]

In my understanding, ISO 19108 does not carry location in space. The discussion about position is for a coordinate value in one axis only, the time axis. But I agree that renaming may hep. For helping to find names, below is a bit of context about discussions that occurred inside OGC.

The OGC Temporal Working Group has emphasised that there is a distinction between time represented by a calendar, and time as a coordinate value. The time represented by a calendar follows complicated rules which make calculations difficult. For example, the period between 2000/01/01 and 2001/01/01 depends not only on whether there is leap day in 2000, but also (more difficult to determine) on whether there is leap second. The latter is often ignored or hidden in software. For example, the java.time specification said that leap seconds are spread over the last 1000 seconds of the year, so that we can pretend that leap seconds do not exist.

By contrast, a coordinate value on the time axis is represented by a single numerical value (e.g. number of seconds since some epoch), with a constant time interval between values. Therefore leap seconds, for example, should not be hidden. One way to see the difference between ISO 8601 and ISO 19108 is to said that 8601 is about dates represented in a calendar system, with a time interval that may not be constant between the same dates at different years or months, while 19108 is about coordinate values on the time axis with a constant time interval, completed by some mapping to 8601 dates. This interpretation is reinforced by the fact that ISO 19108 defines temporal coordinate reference system (note: these CRS definitions in ISO 19108 are deprecated as they moved to ISO 19111).

Another observation is that ISO 19108 defines not only objects for representing temporal coordinates, but also objects for topology in time. The topology side of ISO 19108 is completely omitted from GeoAPI. Therefore, ISO 19108 is the equivalent of ISO 19107 (spatial geometry), but in time. Hence the comparison between Period and curve in the documentation cited in above comment, and the use of names such as "distance" which are usually applied in space rather than time. But doing topology or calculating accurate "distances" require some mathematical properties that are not met by calendar systems, hence the use of temporal coordinates instead.

In summary, my interpretation is that ISO 8601 objects are implicitly CalendarInstant and CalendarPeriod. For ISO 19108, PositionalInstant and PositionalPeriod are not bad, but I wonder if we could find a name that carry more the idea of numbers on a time axis with (as much as practical) constant interval.

[paulushub]

One way to see the difference between ISO 8601 and ISO 19108 is to said that 8601 is about dates represented in a calendar system

Yes, that was one of the mistake in Joda-time that java.time seeks to correct.

In summary, my interpretation is that ISO 8601 objects are implicitly CalendarInstant and CalendarPeriod.

Yes, java.time did not add the calendar to the Instant but did to the period as ChronoPeriod.