Class TimestampUtils


  • public class TimestampUtils
    extends java.lang.Object
    Misc utils for handling time and date values.
    • Constructor Summary

      Constructors 
      Constructor Description
      TimestampUtils​(boolean usesDouble, Provider<java.util.TimeZone> timeZoneProvider)  
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      private static void appendDate​(java.lang.StringBuilder sb, int year, int month, int day)  
      private static void appendDate​(java.lang.StringBuilder sb, java.time.LocalDate localDate)  
      private static void appendDate​(java.lang.StringBuilder sb, java.util.Calendar cal)  
      private static void appendEra​(java.lang.StringBuilder sb, java.time.LocalDate localDate)  
      private static void appendEra​(java.lang.StringBuilder sb, java.util.Calendar cal)  
      private static void appendTime​(java.lang.StringBuilder sb, int hours, int minutes, int seconds, int nanos)
      Appends time part to the StringBuilder in PostgreSQL-compatible format.
      private static void appendTime​(java.lang.StringBuilder sb, java.time.LocalTime localTime)  
      private static void appendTime​(java.lang.StringBuilder sb, java.util.Calendar cal, int nanos)  
      private void appendTimeZone​(java.lang.StringBuilder sb, int offset)  
      private void appendTimeZone​(java.lang.StringBuilder sb, java.time.ZoneOffset offset)  
      private void appendTimeZone​(java.lang.StringBuilder sb, java.util.Calendar cal)  
      private static char charAt​(char[] s, int pos)  
      java.sql.Date convertToDate​(long millis, java.util.TimeZone tz)
      Extracts the date part from a timestamp.
      java.sql.Time convertToTime​(long millis, java.util.TimeZone tz)
      Extracts the time part from a timestamp.
      private static int firstNonDigit​(char[] s, int start)  
      private static long floorDiv​(long x, long y)  
      private static long floorMod​(long x, long y)  
      private java.util.Calendar getCalendar​(java.time.ZoneOffset offset)  
      private java.util.TimeZone getDefaultTz()  
      java.util.Calendar getSharedCalendar​(java.util.TimeZone timeZone)
      Get a shared calendar, applying the supplied time zone or the default time zone if null.
      private long guessTimestamp​(long millis, java.util.TimeZone tz)
      Given a UTC timestamp millis finds another point in time that is rendered in given time zone tz exactly as "millis in UTC".
      boolean hasFastDefaultTimeZone()  
      private static boolean isSimpleTimeZone​(java.lang.String id)  
      private static boolean nanosExceed499​(int nanos)
      Returns true when microsecond part of the time should be increased when rounding to microseconds
      private static int number​(char[] s, int start, int end)  
      private TimestampUtils.ParsedTimestamp parseBackendTimestamp​(java.lang.String str)
      Load date/time information into the provided calendar returning the fractional seconds.
      static java.util.TimeZone parseBackendTimeZone​(java.lang.String timeZone)
      Converts backend's TimeZone parameter to java format.
      private java.util.Calendar setupCalendar​(java.util.Calendar cal)  
      private static int skipWhitespace​(char[] s, int start)  
      java.lang.String timeToString​(java.util.Date time, boolean withTimeZone)
      Returns the given time value as String matching what the current postgresql server would send in text mode.
      void toBinDate​(java.util.TimeZone tz, byte[] bytes, java.sql.Date value)
      Converts the SQL Date to binary representation for Oid.DATE.
      java.sql.Date toDate​(java.util.Calendar cal, java.lang.String s)  
      java.sql.Date toDateBin​(java.util.TimeZone tz, byte[] bytes)
      Returns the SQL Date object matching the given bytes with Oid.DATE.
      private static long toJavaSecs​(long secs)
      Converts the given postgresql seconds to java seconds.
      java.time.LocalDate toLocalDateBin​(byte[] bytes)
      Returns the local date time object matching the given bytes with Oid.DATE or Oid.TIMESTAMP.
      java.time.LocalDateTime toLocalDateTime​(java.lang.String s)
      Parse a string and return a LocalDateTime representing its value.
      java.time.LocalDateTime toLocalDateTimeBin​(byte[] bytes)
      Returns the local date time object matching the given bytes with Oid.TIMESTAMP or Oid.TIMESTAMPTZ.
      java.time.LocalTime toLocalTime​(java.lang.String s)
      Parse a string and return a LocalTime representing its value.
      java.time.LocalTime toLocalTimeBin​(byte[] bytes)
      Returns the SQL Time object matching the given bytes with Oid.TIME.
      java.time.OffsetDateTime toOffsetDateTime​(java.lang.String s)
      Parse a string and return a OffsetDateTime representing its value.
      java.time.OffsetDateTime toOffsetDateTime​(java.sql.Time t)
      Deprecated.
      was used internally, and not used anymore
      java.time.OffsetDateTime toOffsetDateTimeBin​(byte[] bytes)
      Returns the offset date time object matching the given bytes with Oid#TIMESTAMPTZ.
      java.time.OffsetTime toOffsetTime​(java.lang.String s)
      Parse a string and return a OffsetTime representing its value.
      java.time.OffsetTime toOffsetTimeBin​(byte[] bytes)
      Returns the offset time object matching the given bytes with Oid#TIMETZ or Oid#TIME.
      private TimestampUtils.ParsedBinaryTimestamp toParsedTimestampBin​(java.util.TimeZone tz, byte[] bytes, boolean timestamptz)  
      private TimestampUtils.ParsedBinaryTimestamp toParsedTimestampBinPlain​(byte[] bytes)  
      private static long toPgSecs​(long secs)
      Converts the given java seconds to postgresql seconds.
      private TimestampUtils.ParsedBinaryTimestamp toProlepticParsedTimestampBin​(byte[] bytes)  
      java.lang.String toString​(java.time.LocalDate localDate)  
      java.lang.String toString​(java.time.LocalDateTime localDateTime)
      Formats LocalDateTime to be sent to the backend, thus it adds time zone.
      java.lang.String toString​(java.time.LocalTime localTime)  
      java.lang.String toString​(java.time.OffsetDateTime offsetDateTime)  
      java.lang.String toString​(java.time.OffsetTime offsetTime)  
      java.lang.String toString​(java.util.Calendar cal, java.sql.Date x)  
      java.lang.String toString​(java.util.Calendar cal, java.sql.Date x, boolean withTimeZone)  
      java.lang.String toString​(java.util.Calendar cal, java.sql.Time x)  
      java.lang.String toString​(java.util.Calendar cal, java.sql.Time x, boolean withTimeZone)  
      java.lang.String toString​(java.util.Calendar cal, java.sql.Timestamp x)  
      java.lang.String toString​(java.util.Calendar cal, java.sql.Timestamp x, boolean withTimeZone)  
      java.sql.Time toTime​(java.util.Calendar cal, java.lang.String s)  
      java.sql.Time toTimeBin​(java.util.TimeZone tz, byte[] bytes)
      Returns the SQL Time object matching the given bytes with Oid.TIME or Oid.TIMETZ.
      java.sql.Timestamp toTimestamp​(java.util.Calendar cal, java.lang.String s)
      Parse a string and return a timestamp representing its value.
      java.sql.Timestamp toTimestampBin​(java.util.TimeZone tz, byte[] bytes, boolean timestamptz)
      Returns the SQL Timestamp object matching the given bytes with Oid.TIMESTAMP or Oid.TIMESTAMPTZ.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • ONEDAY

        private static final int ONEDAY
        Number of milliseconds in one day.
        See Also:
        Constant Field Values
      • ZEROS

        private static final char[] ZEROS
      • NUMBERS

        private static final char[][] NUMBERS
      • GMT_ZONES

        private static final java.util.HashMap<java.lang.String,​java.util.TimeZone> GMT_ZONES
      • MAX_NANOS_BEFORE_WRAP_ON_ROUND

        private static final int MAX_NANOS_BEFORE_WRAP_ON_ROUND
        See Also:
        Constant Field Values
      • ONE_MICROSECOND

        private static final java.time.Duration ONE_MICROSECOND
      • MAX_TIME

        private static final java.time.LocalTime MAX_TIME
      • MAX_OFFSET_DATETIME

        private static final java.time.OffsetDateTime MAX_OFFSET_DATETIME
      • MAX_LOCAL_DATETIME

        private static final java.time.LocalDateTime MAX_LOCAL_DATETIME
      • MIN_LOCAL_DATE

        private static final java.time.LocalDate MIN_LOCAL_DATE
      • MIN_LOCAL_DATETIME

        private static final java.time.LocalDateTime MIN_LOCAL_DATETIME
      • MIN_OFFSET_DATETIME

        private static final java.time.OffsetDateTime MIN_OFFSET_DATETIME
      • PG_EPOCH_DIFF

        private static final java.time.Duration PG_EPOCH_DIFF
      • DEFAULT_TIME_ZONE_FIELD

        private static final java.lang.reflect.Field DEFAULT_TIME_ZONE_FIELD
      • UTC_TIMEZONE

        private static final java.util.TimeZone UTC_TIMEZONE
      • prevDefaultZoneFieldValue

        private java.util.TimeZone prevDefaultZoneFieldValue
      • defaultTimeZoneCache

        private java.util.TimeZone defaultTimeZoneCache
      • sbuf

        private final java.lang.StringBuilder sbuf
      • calendarWithUserTz

        private final java.util.Calendar calendarWithUserTz
      • calCache

        private java.util.Calendar calCache
      • calCacheZone

        private java.time.ZoneOffset calCacheZone
      • usesDouble

        private final boolean usesDouble
        True if the backend uses doubles for time values. False if long is used.
      • timeZoneProvider

        private final Provider<java.util.TimeZone> timeZoneProvider
    • Constructor Detail

      • TimestampUtils

        public TimestampUtils​(boolean usesDouble,
                              Provider<java.util.TimeZone> timeZoneProvider)
    • Method Detail

      • getCalendar

        private java.util.Calendar getCalendar​(java.time.ZoneOffset offset)
      • parseBackendTimestamp

        private TimestampUtils.ParsedTimestamp parseBackendTimestamp​(java.lang.String str)
                                                              throws java.sql.SQLException
        Load date/time information into the provided calendar returning the fractional seconds.
        Throws:
        java.sql.SQLException
      • toTimestamp

        public java.sql.Timestamp toTimestamp​(java.util.Calendar cal,
                                              java.lang.String s)
                                       throws java.sql.SQLException
        Parse a string and return a timestamp representing its value.
        Parameters:
        cal - calendar to be used to parse the input string
        s - The ISO formated date string to parse.
        Returns:
        null if s is null or a timestamp of the parsed string s.
        Throws:
        java.sql.SQLException - if there is a problem parsing s.
      • toLocalTime

        public java.time.LocalTime toLocalTime​(java.lang.String s)
                                        throws java.sql.SQLException
        Parse a string and return a LocalTime representing its value.
        Parameters:
        s - The ISO formated time string to parse.
        Returns:
        null if s is null or a LocalTime of the parsed string s.
        Throws:
        java.sql.SQLException - if there is a problem parsing s.
      • toOffsetTimeBin

        public java.time.OffsetTime toOffsetTimeBin​(byte[] bytes)
                                             throws PSQLException
        Returns the offset time object matching the given bytes with Oid#TIMETZ or Oid#TIME.
        Parameters:
        bytes - The binary encoded TIMETZ/TIME value.
        Returns:
        The parsed offset time object.
        Throws:
        PSQLException - If binary format could not be parsed.
      • toOffsetTime

        public java.time.OffsetTime toOffsetTime​(java.lang.String s)
                                          throws java.sql.SQLException
        Parse a string and return a OffsetTime representing its value.
        Parameters:
        s - The ISO formated time string to parse.
        Returns:
        null if s is null or a OffsetTime of the parsed string s.
        Throws:
        java.sql.SQLException - if there is a problem parsing s.
      • toLocalDateTime

        public java.time.LocalDateTime toLocalDateTime​(java.lang.String s)
                                                throws java.sql.SQLException
        Parse a string and return a LocalDateTime representing its value.
        Parameters:
        s - The ISO formated date string to parse.
        Returns:
        null if s is null or a LocalDateTime of the parsed string s.
        Throws:
        java.sql.SQLException - if there is a problem parsing s.
      • toOffsetDateTime

        @Deprecated
        public java.time.OffsetDateTime toOffsetDateTime​(java.sql.Time t)
        Deprecated.
        was used internally, and not used anymore
        Returns the offset date time object matching the given bytes with Oid#TIMETZ. Not used internally anymore, function is here to retain compatibility with previous versions
        Parameters:
        t - the time value
        Returns:
        the matching offset date time
      • toOffsetDateTime

        public java.time.OffsetDateTime toOffsetDateTime​(java.lang.String s)
                                                  throws java.sql.SQLException
        Parse a string and return a OffsetDateTime representing its value.
        Parameters:
        s - The ISO formatted date string to parse.
        Returns:
        null if s is null or a OffsetDateTime of the parsed string s.
        Throws:
        java.sql.SQLException - if there is a problem parsing s.
      • toOffsetDateTimeBin

        public java.time.OffsetDateTime toOffsetDateTimeBin​(byte[] bytes)
                                                     throws PSQLException
        Returns the offset date time object matching the given bytes with Oid#TIMESTAMPTZ.
        Parameters:
        bytes - The binary encoded local date time value.
        Returns:
        The parsed local date time object.
        Throws:
        PSQLException - If binary format could not be parsed.
      • toTime

        public java.sql.Time toTime​(java.util.Calendar cal,
                                    java.lang.String s)
                             throws java.sql.SQLException
        Throws:
        java.sql.SQLException
      • toDate

        public java.sql.Date toDate​(java.util.Calendar cal,
                                    java.lang.String s)
                             throws java.sql.SQLException
        Throws:
        java.sql.SQLException
      • setupCalendar

        private java.util.Calendar setupCalendar​(java.util.Calendar cal)
      • getSharedCalendar

        public java.util.Calendar getSharedCalendar​(java.util.TimeZone timeZone)
        Get a shared calendar, applying the supplied time zone or the default time zone if null.
        Parameters:
        timeZone - time zone to be set for the calendar
        Returns:
        The shared calendar.
      • nanosExceed499

        private static boolean nanosExceed499​(int nanos)
        Returns true when microsecond part of the time should be increased when rounding to microseconds
        Parameters:
        nanos - nanosecond part of the time
        Returns:
        true when microsecond part of the time should be increased when rounding to microseconds
      • toString

        public java.lang.String toString​(java.util.Calendar cal,
                                         java.sql.Timestamp x)
      • toString

        public java.lang.String toString​(java.util.Calendar cal,
                                         java.sql.Timestamp x,
                                         boolean withTimeZone)
      • toString

        public java.lang.String toString​(java.util.Calendar cal,
                                         java.sql.Date x)
      • toString

        public java.lang.String toString​(java.util.Calendar cal,
                                         java.sql.Date x,
                                         boolean withTimeZone)
      • toString

        public java.lang.String toString​(java.util.Calendar cal,
                                         java.sql.Time x)
      • toString

        public java.lang.String toString​(java.util.Calendar cal,
                                         java.sql.Time x,
                                         boolean withTimeZone)
      • appendDate

        private static void appendDate​(java.lang.StringBuilder sb,
                                       java.util.Calendar cal)
      • appendDate

        private static void appendDate​(java.lang.StringBuilder sb,
                                       int year,
                                       int month,
                                       int day)
      • appendTime

        private static void appendTime​(java.lang.StringBuilder sb,
                                       java.util.Calendar cal,
                                       int nanos)
      • appendTime

        private static void appendTime​(java.lang.StringBuilder sb,
                                       int hours,
                                       int minutes,
                                       int seconds,
                                       int nanos)
        Appends time part to the StringBuilder in PostgreSQL-compatible format. The function truncates {@param nanos} to microseconds. The value is expected to be rounded beforehand.
        Parameters:
        sb - destination
        hours - hours
        minutes - minutes
        seconds - seconds
        nanos - nanoseconds
      • appendTimeZone

        private void appendTimeZone​(java.lang.StringBuilder sb,
                                    java.util.Calendar cal)
      • appendTimeZone

        private void appendTimeZone​(java.lang.StringBuilder sb,
                                    int offset)
      • appendEra

        private static void appendEra​(java.lang.StringBuilder sb,
                                      java.util.Calendar cal)
      • toString

        public java.lang.String toString​(java.time.LocalDate localDate)
      • toString

        public java.lang.String toString​(java.time.LocalTime localTime)
      • toString

        public java.lang.String toString​(java.time.OffsetTime offsetTime)
      • toString

        public java.lang.String toString​(java.time.OffsetDateTime offsetDateTime)
      • toString

        public java.lang.String toString​(java.time.LocalDateTime localDateTime)
        Formats LocalDateTime to be sent to the backend, thus it adds time zone. Do not use this method in ResultSet.getString(int)
        Parameters:
        localDateTime - The local date to format as a String
        Returns:
        The formatted local date
      • appendDate

        private static void appendDate​(java.lang.StringBuilder sb,
                                       java.time.LocalDate localDate)
      • appendTime

        private static void appendTime​(java.lang.StringBuilder sb,
                                       java.time.LocalTime localTime)
      • appendTimeZone

        private void appendTimeZone​(java.lang.StringBuilder sb,
                                    java.time.ZoneOffset offset)
      • appendEra

        private static void appendEra​(java.lang.StringBuilder sb,
                                      java.time.LocalDate localDate)
      • skipWhitespace

        private static int skipWhitespace​(char[] s,
                                          int start)
      • firstNonDigit

        private static int firstNonDigit​(char[] s,
                                         int start)
      • number

        private static int number​(char[] s,
                                  int start,
                                  int end)
      • charAt

        private static char charAt​(char[] s,
                                   int pos)
      • toDateBin

        public java.sql.Date toDateBin​(java.util.TimeZone tz,
                                       byte[] bytes)
                                throws PSQLException
        Returns the SQL Date object matching the given bytes with Oid.DATE.
        Parameters:
        tz - The timezone used.
        bytes - The binary encoded date value.
        Returns:
        The parsed date object.
        Throws:
        PSQLException - If binary format could not be parsed.
      • getDefaultTz

        private java.util.TimeZone getDefaultTz()
      • hasFastDefaultTimeZone

        public boolean hasFastDefaultTimeZone()
      • toTimeBin

        public java.sql.Time toTimeBin​(java.util.TimeZone tz,
                                       byte[] bytes)
                                throws PSQLException
        Returns the SQL Time object matching the given bytes with Oid.TIME or Oid.TIMETZ.
        Parameters:
        tz - The timezone used when received data is Oid.TIME, ignored if data already contains Oid.TIMETZ.
        bytes - The binary encoded time value.
        Returns:
        The parsed time object.
        Throws:
        PSQLException - If binary format could not be parsed.
      • toLocalTimeBin

        public java.time.LocalTime toLocalTimeBin​(byte[] bytes)
                                           throws PSQLException
        Returns the SQL Time object matching the given bytes with Oid.TIME.
        Parameters:
        bytes - The binary encoded time value.
        Returns:
        The parsed time object.
        Throws:
        PSQLException - If binary format could not be parsed.
      • toTimestampBin

        public java.sql.Timestamp toTimestampBin​(java.util.TimeZone tz,
                                                 byte[] bytes,
                                                 boolean timestamptz)
                                          throws PSQLException
        Returns the SQL Timestamp object matching the given bytes with Oid.TIMESTAMP or Oid.TIMESTAMPTZ.
        Parameters:
        tz - The timezone used when received data is Oid.TIMESTAMP, ignored if data already contains Oid.TIMESTAMPTZ.
        bytes - The binary encoded timestamp value.
        timestamptz - True if the binary is in GMT.
        Returns:
        The parsed timestamp object.
        Throws:
        PSQLException - If binary format could not be parsed.
      • toLocalDateTimeBin

        public java.time.LocalDateTime toLocalDateTimeBin​(byte[] bytes)
                                                   throws PSQLException
        Returns the local date time object matching the given bytes with Oid.TIMESTAMP or Oid.TIMESTAMPTZ.
        Parameters:
        bytes - The binary encoded local date time value.
        Returns:
        The parsed local date time object.
        Throws:
        PSQLException - If binary format could not be parsed.
      • toLocalDateBin

        public java.time.LocalDate toLocalDateBin​(byte[] bytes)
                                           throws PSQLException
        Returns the local date time object matching the given bytes with Oid.DATE or Oid.TIMESTAMP.
        Parameters:
        bytes - The binary encoded local date value.
        Returns:
        The parsed local date object.
        Throws:
        PSQLException - If binary format could not be parsed.
      • guessTimestamp

        private long guessTimestamp​(long millis,
                                    java.util.TimeZone tz)

        Given a UTC timestamp millis finds another point in time that is rendered in given time zone tz exactly as "millis in UTC".

        For instance, given 7 Jan 16:00 UTC and tz=GMT+02:00 it returns 7 Jan 14:00 UTC == 7 Jan 16:00 GMT+02:00 Note that is not trivial for timestamps near DST change. For such cases, we rely on Calendar to figure out the proper timestamp.

        Parameters:
        millis - source timestamp
        tz - desired time zone
        Returns:
        timestamp that would be rendered in tz like millis in UTC
      • isSimpleTimeZone

        private static boolean isSimpleTimeZone​(java.lang.String id)
      • convertToDate

        public java.sql.Date convertToDate​(long millis,
                                           java.util.TimeZone tz)
        Extracts the date part from a timestamp.
        Parameters:
        millis - The timestamp from which to extract the date.
        tz - The time zone of the date.
        Returns:
        The extracted date.
      • convertToTime

        public java.sql.Time convertToTime​(long millis,
                                           java.util.TimeZone tz)
        Extracts the time part from a timestamp. This method ensures the date part of output timestamp looks like 1970-01-01 in given timezone.
        Parameters:
        millis - The timestamp from which to extract the time.
        tz - timezone to use.
        Returns:
        The extracted time.
      • timeToString

        public java.lang.String timeToString​(java.util.Date time,
                                             boolean withTimeZone)
        Returns the given time value as String matching what the current postgresql server would send in text mode.
        Parameters:
        time - time value
        withTimeZone - whether timezone should be added
        Returns:
        given time value as String
      • toJavaSecs

        private static long toJavaSecs​(long secs)
        Converts the given postgresql seconds to java seconds. Reverse engineered by inserting varying dates to postgresql and tuning the formula until the java dates matched. See toPgSecs(long) for the reverse operation.
        Parameters:
        secs - Postgresql seconds.
        Returns:
        Java seconds.
      • toPgSecs

        private static long toPgSecs​(long secs)
        Converts the given java seconds to postgresql seconds. See toJavaSecs(long) for the reverse operation. The conversion is valid for any year 100 BC onwards.
        Parameters:
        secs - Postgresql seconds.
        Returns:
        Java seconds.
      • toBinDate

        public void toBinDate​(java.util.TimeZone tz,
                              byte[] bytes,
                              java.sql.Date value)
                       throws PSQLException
        Converts the SQL Date to binary representation for Oid.DATE.
        Parameters:
        tz - The timezone used.
        bytes - The binary encoded date value.
        value - value
        Throws:
        PSQLException - If binary format could not be parsed.
      • parseBackendTimeZone

        public static java.util.TimeZone parseBackendTimeZone​(java.lang.String timeZone)
        Converts backend's TimeZone parameter to java format. Notable difference: backend's gmt-3 is GMT+03 in Java.
        Parameters:
        timeZone - time zone to use
        Returns:
        java TimeZone
      • floorDiv

        private static long floorDiv​(long x,
                                     long y)
      • floorMod

        private static long floorMod​(long x,
                                     long y)