Package org.elasticsearch.common

Class LocalTimeOffset

java.lang.Object
org.elasticsearch.common.LocalTimeOffset
Direct Known Subclasses:
LocalTimeOffset.Transition
public abstract class LocalTimeOffset extends Object
Converts utc into local time and back again.

"Local time" is defined by some time zone, specifically and ZoneId. At any point in time a particular time zone is at some offset from from utc. So converting from utc is as simple as adding the offset.

Getting from local time back to utc is harder. Most local times happen once. But some local times happen twice (DST overlap). And some don't happen at all (DST gap). Take, for example, the time in my house. Most days I don't touch my clocks and I'm a constant offset from UTC. But once in the fall at 2am I roll my clock back. So at 5am utc my clocks say 1am. Then at 6am utc my clocks say 1am AGAIN. I do similarly terrifying things again in the spring when I skip my clocks straight from 1:59am to 3am.

So there are two methods to convert from local time back to utc, localToUtc(long, Strategy) and localToUtcInThisOffset(long).

See Also:

  • Method Details

    • lookup

      public static LocalTimeOffset.Lookup lookup(ZoneId zone, long minUtcMillis, long maxUtcMillis)
      Lookup offsets for a provided zone. This can fail if there are many transitions and the provided lookup would be very large.
      Returns:
      a LocalTimeOffset.Lookup or null if none could be built

    • fixedOffset

      public static LocalTimeOffset fixedOffset(ZoneId zone)
      Lookup offsets without any known min or max time. This will generally fail if the provided zone isn't fixed.
      Returns:
      a lookup function of null if none could be built

    • utcToLocalTime

      public final long utcToLocalTime(long utcMillis)
      Convert a time in utc into a the local time at this offset.

    • localToUtcInThisOffset

      public final long localToUtcInThisOffset(long localMillis)
      Convert a time in local millis to utc millis using this offset.

      Important: Callers will rarely want to force using this offset and are instead instead interested in picking an appropriate offset for some local time that they have rounded down. In that case use localToUtc(long, Strategy).

    • localToUtc

      public abstract long localToUtc(long localMillis, LocalTimeOffset.Strategy strat)
      Convert a local time that occurs during this offset or a previous offset to utc, providing a strategy for how to resolve "funny" cases. You can use this if you've converted from utc to local, rounded down, and then want to convert back to utc and you need fine control over how to handle the "funny" edges.

      This will not help you if you must convert a local time that you've rounded up. For that you are on your own. May God have mercy on your soul.

    • containsUtcMillis

      protected abstract boolean containsUtcMillis(long utcMillis)
      Does this offset contain the provided time?

    • offsetContaining

      protected abstract LocalTimeOffset offsetContaining(long utcMillis)
      Find the offset containing the provided time, first checking this offset, then its previous offset, the than one's previous offset, etc.

    • anyMoveBackToPreviousDay

      protected abstract boolean anyMoveBackToPreviousDay()
      Does this transition or any previous transitions move back to the previous day? See LocalTimeOffset.Lookup.anyMoveBackToPreviousDay() for rules.

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • toString

      protected abstract String toString(long millis)