Package org.vast.util

Class TimeExtent

java.lang.Object
org.vast.util.TimeExtent
Direct Known Subclasses:
ZonedTimeExtent
public class TimeExtent extends Object

Immutable class for storing a time instant or time period.

This class also supports special cases of time instants at 'now', time periods beginning or ending at 'now', and open-ended time periods.

Note that no time zone information is retained. It usually means begin and end times are UTC unless otherwise specified by the application. See ZonedTimeExtent if you need to store a time extent with a time zone.

Since:
Apr 12, 2020

  • Field Details

  • Constructor Details

    • TimeExtent

      protected TimeExtent()

  • Method Details

    • now

      public static TimeExtent now()
      Returns:
      A time extent representing the special value 'now'

    • currentTime

      public static TimeExtent currentTime()
      Returns:
      A time extent representing the current time instant, that is to say the value returned by Instant.now()

    • instant

      public static TimeExtent instant(Instant t)
      Parameters:
      t - Time instant
      Returns:
      A time extent representing a time instant

    • period

      public static TimeExtent period(Instant begin, Instant end)
      Parameters:
      begin - Beginning of time period
      end - End of time period
      Returns:
      A time extent representing a time period

    • period

      public static TimeExtent period(com.google.common.collect.Range<Instant> timeRange)
      Build a time extent from a range of instant
      Parameters:
      timeRange - Range object. Both ends can be bounded or unbounded
      Returns:
      A time extent representing a time period

    • beginAt

      public static TimeExtent beginAt(Instant begin)
      Parameters:
      begin - Begin time instant
      Returns:
      An open-ended time extent starting at the specified time

    • endAt

      public static TimeExtent endAt(Instant end)
      Parameters:
      end - End time instant
      Returns:
      An open time extent ending at the specified time

    • beginNow

      public static TimeExtent beginNow(Instant end)
      Parameters:
      end - End time instant
      Returns:
      A time extent starting 'now' and ending at the specified time

    • endNow

      public static TimeExtent endNow(Instant begin)
      Parameters:
      begin - Begin time instant
      Returns:
      A time extent starting at the specified time and ending 'now'

    • span

      public static TimeExtent span(TimeExtent... timeExtents)
      Computes a time extent that exactly contains all provided time extents
      Parameters:
      timeExtents - One or more time extents
      Returns:
      A time extent that contains all provided time extents, accounting for 'now' edge cases

    • parse

      public static TimeExtent parse(String text)

      Parse a time extent from a string that can be either an ISO-8601 time instant or a time interval with begin and end times in ISO-8601 format, and separated by a '/'. Special values 'now' and '..' (meaning unbounded) are also supported.

      Example values that can be parsed:

    • Time instant: "2018-03-12T00:00:00Z", "2000-05-25T00:00:00-06:00", "2019-09-25" or "now"
    • Closed interval: "2020-02-12T00:00:00Z/2020-03-18T12:31:12Z" or "2020-01-15Z/2020-02-16Z"
    • Open interval: "2020-02-12T00:00:00Z/.." or "../2020-03-18T12:31:12Z"
    • Interval with indeterminate value: "2020-02-12T00:00:00Z/now", "now/2030-08-01+01:00" or "now/.."

      • When only the date portion is provided, the implied time is 00:00:00

      Parameters:
      text - The text to be parsed
      Returns:
      The TimeExtent representing the same time instant or interval

    • hasBegin

      public boolean hasBegin()
      Returns:
      True if begin time is defined, false otherwise

    • begin

      public Instant begin()
      Returns:
      The beginning instant of Instant.MIN if undefined. If beginsNow() also returns true, the current system time is returned.

    • hasEnd

      public boolean hasEnd()
      Returns:
      True if end time is defined, false otherwise

    • end

      public Instant end()
      Returns:
      The end instant of Instant.MAX if undefined. If endsNow() also returns true, the current system time is returned.

    • isInstant

      public boolean isInstant()
      Returns:
      True if this time extent represents a time instant, false if it represents a time period

    • isNow

      public boolean isNow()
      Returns:
      True if this time extent represents the 'now' instant, false otherwise

    • beginsNow

      public boolean beginsNow()
      Returns:
      True if this time extent begins at 'now', false otherwise

    • endsNow

      public boolean endsNow()
      Returns:
      True if this time extent ends at 'now', false otherwise

    • isAllTimes

      public boolean isAllTimes()
      Returns:
      True if this time extent contains all possible time instants (i.e. no begin and end bounds)

    • duration

      public Duration duration()
      Returns:
      The duration of this time extent

    • contains

      public boolean contains(TimeExtent other)
      Parameters:
      other - Another time extent
      Returns:
      True if the specified time extent is contained within this time extent, false otherwise

    • contains

      public boolean contains(Instant t)
      Parameters:
      t - A time instant
      Returns:
      True if the specified time instant is contained within this time extent, false otherwise

    • intersects

      public boolean intersects(TimeExtent other)
      Parameters:
      other - Another time extent
      Returns:
      True if the specified time extent intersects this time extent, false otherwise

    • intersection

      public static TimeExtent intersection(TimeExtent te1, TimeExtent te2)
      Compute the intersection between 2 time extents accouting for edge cases
      Parameters:
      te1 - First time extent
      te2 - Second time extent
      Returns:
      A time extent representing the intersection or null if none exists

    • isoStringUTC

      public String isoStringUTC(boolean keepNow)
      Parameters:
      keepNow - Keep the 'now' string if set to true, otherwise use the current time
      Returns:
      The ISO8601 representation of this time extent

    • asRange

      public com.google.common.collect.Range<Instant> asRange()
      Returns:
      This time extent as a Range of two time instants.
      Note that calling this method is invalid if this time extent either begins or ends at 'now'

    • atZone

      public ZonedTimeExtent atZone(ZoneId timeZone)
      Parameters:
      timeZone - The desired time zone
      Returns:
      A new time extent with the associated time zone

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object