Module org.opengis.geoapi

Package org.opengis.temporal

Interface Instant

All Superinterfaces:

TemporalPrimitive

@UML(identifier="TM_Instant",
     specification=ISO_19108)
public interface Instant
extends TemporalPrimitive

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

Since:

3.1

Method Summary

Modifier and Type	Method	Description
default TemporalAmount	distance(TemporalPrimitive other)	Returns the distance from this instant to another instant or a period (optional operation).
default Optional<IndeterminateValue>	getIndeterminatePosition()	Returns the reason why the temporal position is missing or inaccurate.
Temporal	getPosition()	Returns the date, time or position on the time-scale represented by this primitive.

Methods inherited from interface org.opengis.temporal.TemporalPrimitive

findRelativePosition

Method Details

getPosition

@UML(identifier="position",
     obligation=MANDATORY,
     specification=ISO_19108)
Temporal getPosition()

Returns the date, time or position on the time-scale represented by this primitive. The position can be of the following types:

• Date: mapped to the LocalDate class.
• Time: mapped to the LocalTime or OffsetTime classes.
• Date & time: mapped to the LocalDateTime, OffsetDateTime or ZonedDateTime classes.
• Temporal position: mapped to a vendor-specific implementation of the Temporal interface, possibly using custom temporal fields. The returned object should also implement the DirectPosition interface for providing the coordinate value together with its coordinate reference system (CRS).

The returned value should not be null, except if getIndeterminatePosition() returns IndeterminateValue.UNKNOWN. In the case of IndeterminateValue.NOW, this method should return the current time.

Returns:

the date, time or instant represented by this primitive. Should not be null, except if unknown.

Departure from OGC/ISO standard for harmonization between different specifications

ISO 19108 defines this property as an union of date8601, time8601, dateTime8601 or anyOther properties. Unions are not explicitly supported by the Java language, but the same result is achieved with type hierarchy. The mappings of ISO 19103 Date, Time and DateTime types are described in above Javadoc. The TM_TemporalPosition type used by the anyOther property is replaced by a vendor-specific Temporal implementation.

getIndeterminatePosition

@UML(identifier="TM_TemporalPosition.indeterminatePosition",
     obligation=OPTIONAL,
     specification=ISO_19108)
default Optional<IndeterminateValue> getIndeterminatePosition()

Returns the reason why the temporal position is missing or inaccurate. When the temporal position is defined, this code provides a qualifier (e.g. "before" or "after") to the temporal position value.

Returns:

the reason why the position is indeterminate.

Departure from OGC/ISO standard for closer integration with the Java environment

Moved from TM_TemporalPosition to TM_Instant because the former is replaced by the Temporal standard Java interface, and Temporal does not have an association to the IndeterminateValue code list.

distance

@UML(identifier="TM_Separation.distance",
     obligation=OPTIONAL,
     specification=ISO_19108)
default TemporalAmount distance(TemporalPrimitive other)

Returns the distance from this instant to another instant or a period (optional operation). This is the absolute value of the difference between the temporal positions. If other is a period and this instant is contained within that period, then this method shall return a distance of zero.

Exceptions

This method shall throw an IndeterminatePositionException if at least one temporal position is indeterminate. A DateTimeException may also be thrown if the temporal positions are associated to different TemporalCRS, or if the coordinates are ordinal values, or if the Temporal objects do not support required temporal fields.

Parameters:

other - the other object from which to measure the distance.

Returns:

the distance from this instant to another instant or period.

Throws:

UnsupportedOperationException - if this operation is not supported.

IndeterminatePositionException - if at least one temporal position is indeterminate.

DateTimeException - if the duration cannot be computed between the two temporal primitives.

ArithmeticException - if the duration exceeds the capacity of the implementation.

See Also:

• Duration.between(Temporal, Temporal)