Package org.elasticsearch.common

Class LocalTimeOffset

java.lang.Object
org.elasticsearch.common.LocalTimeOffset
Direct Known Subclasses:
LocalTimeOffset.Transition
public abstract class LocalTimeOffset
extends java.lang.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. And some don't happen at all. 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).

  • Nested Class Summary

    Nested Classes 
    Modifier and Type Class Description
    static class  LocalTimeOffset.Gap  
    static class  LocalTimeOffset.Lookup
    How to get instances of LocalTimeOffset.
    static class  LocalTimeOffset.Overlap  
    static interface  LocalTimeOffset.Strategy  
    static class  LocalTimeOffset.Transition  

  • Method Summary

    Modifier and Type Method Description
    protected abstract boolean containsUtcMillis​(long utcMillis)
    Does this offset contain the provided time?
    static LocalTimeOffset fixedOffset​(java.time.ZoneId zone)
    Lookup offsets without any known min or max time.
    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.
    long localToUtcInThisOffset​(long localMillis)
    Convert a time in local millis to utc millis using this offset.
    static LocalTimeOffset.Lookup lookup​(java.time.ZoneId zone, long minUtcMillis, long maxUtcMillis)
    Lookup offsets for a provided zone.
    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.
    java.lang.String toString()  
    protected abstract java.lang.String toString​(long millis)  
    long utcToLocalTime​(long utcMillis)
    Convert a time in utc into a the local time at this offset.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Method Details

    • lookup

      public static LocalTimeOffset.Lookup lookup​(java.time.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​(java.time.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.

    • toString

      public java.lang.String toString()
      Overrides:
      toString in class java.lang.Object

    • toString

      protected abstract java.lang.String toString​(long millis)