Class TimestampUtils

java.lang.Object
org.postgresql.jdbc.TimestampUtils

public class TimestampUtils extends Object
Misc utils for handling time and date values.
  • Field Details

    • ONEDAY

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

      private static final char[] ZEROS
    • NUMBERS

      private static final char[][] NUMBERS
    • GMT_ZONES

      private static final HashMap<String,TimeZone> GMT_ZONES
    • MAX_NANOS_BEFORE_WRAP_ON_ROUND

      private static final int MAX_NANOS_BEFORE_WRAP_ON_ROUND
      See Also:
    • ONE_MICROSECOND

      private static final Duration ONE_MICROSECOND
    • MAX_TIME

      private static final LocalTime MAX_TIME
    • MAX_OFFSET_DATETIME

      private static final OffsetDateTime MAX_OFFSET_DATETIME
    • MAX_LOCAL_DATETIME

      private static final LocalDateTime MAX_LOCAL_DATETIME
    • MIN_LOCAL_DATE

      private static final LocalDate MIN_LOCAL_DATE
    • MIN_LOCAL_DATETIME

      private static final LocalDateTime MIN_LOCAL_DATETIME
    • MIN_OFFSET_DATETIME

      private static final OffsetDateTime MIN_OFFSET_DATETIME
    • PG_EPOCH_DIFF

      private static final Duration PG_EPOCH_DIFF
    • DEFAULT_TIME_ZONE_FIELD

      private static final Field DEFAULT_TIME_ZONE_FIELD
    • UTC_TIMEZONE

      private static final TimeZone UTC_TIMEZONE
    • prevDefaultZoneFieldValue

      private TimeZone prevDefaultZoneFieldValue
    • defaultTimeZoneCache

      private TimeZone defaultTimeZoneCache
    • sbuf

      private final StringBuilder sbuf
    • calendarWithUserTz

      private final Calendar calendarWithUserTz
    • calCache

      private Calendar calCache
    • calCacheZone

      private 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<TimeZone> timeZoneProvider
  • Constructor Details

    • TimestampUtils

      public TimestampUtils(boolean usesDouble, Provider<TimeZone> timeZoneProvider)
  • Method Details

    • getCalendar

      private Calendar getCalendar(ZoneOffset offset)
    • parseBackendTimestamp

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

      public Timestamp toTimestamp(Calendar cal, String s) throws 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:
      SQLException - if there is a problem parsing s.
    • toLocalTime

      public LocalTime toLocalTime(String s) throws 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:
      SQLException - if there is a problem parsing s.
    • toOffsetTimeBin

      public 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 OffsetTime toOffsetTime(String s) throws 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:
      SQLException - if there is a problem parsing s.
    • toLocalDateTime

      public LocalDateTime toLocalDateTime(String s) throws 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:
      SQLException - if there is a problem parsing s.
    • toOffsetDateTime

      @Deprecated public OffsetDateTime toOffsetDateTime(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 OffsetDateTime toOffsetDateTime(String s) throws 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:
      SQLException - if there is a problem parsing s.
    • toOffsetDateTimeBin

      public 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 Time toTime(Calendar cal, String s) throws SQLException
      Throws:
      SQLException
    • toDate

      public Date toDate(Calendar cal, String s) throws SQLException
      Throws:
      SQLException
    • setupCalendar

      private Calendar setupCalendar(Calendar cal)
    • getSharedCalendar

      public Calendar getSharedCalendar(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 String toString(Calendar cal, Timestamp x)
    • toString

      public String toString(Calendar cal, Timestamp x, boolean withTimeZone)
    • toString

      public String toString(Calendar cal, Date x)
    • toString

      public String toString(Calendar cal, Date x, boolean withTimeZone)
    • toString

      public String toString(Calendar cal, Time x)
    • toString

      public String toString(Calendar cal, Time x, boolean withTimeZone)
    • appendDate

      private static void appendDate(StringBuilder sb, Calendar cal)
    • appendDate

      private static void appendDate(StringBuilder sb, int year, int month, int day)
    • appendTime

      private static void appendTime(StringBuilder sb, Calendar cal, int nanos)
    • appendTime

      private static void appendTime(StringBuilder sb, int hours, int minutes, int seconds, int nanos)
      Appends time part to the StringBuilder in PostgreSQL-compatible format. The function truncates 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(StringBuilder sb, Calendar cal)
    • appendTimeZone

      private void appendTimeZone(StringBuilder sb, int offset)
    • appendEra

      private static void appendEra(StringBuilder sb, Calendar cal)
    • toString

      public String toString(LocalDate localDate)
    • toString

      public String toString(LocalTime localTime)
    • toString

      public String toString(OffsetTime offsetTime)
    • toString

      public String toString(OffsetDateTime offsetDateTime)
    • toString

      public String toString(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(StringBuilder sb, LocalDate localDate)
    • appendTime

      private static void appendTime(StringBuilder sb, LocalTime localTime)
    • appendTimeZone

      private void appendTimeZone(StringBuilder sb, ZoneOffset offset)
    • appendEra

      private static void appendEra(StringBuilder sb, 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 Date toDateBin(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 TimeZone getDefaultTz()
    • hasFastDefaultTimeZone

      public boolean hasFastDefaultTimeZone()
    • toTimeBin

      public Time toTimeBin(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 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 Timestamp toTimestampBin(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.
    • toParsedTimestampBinPlain

      private TimestampUtils.ParsedBinaryTimestamp toParsedTimestampBinPlain(byte[] bytes) throws PSQLException
      Throws:
      PSQLException
    • toParsedTimestampBin

      private TimestampUtils.ParsedBinaryTimestamp toParsedTimestampBin(TimeZone tz, byte[] bytes, boolean timestamptz) throws PSQLException
      Throws:
      PSQLException
    • toProlepticParsedTimestampBin

      private TimestampUtils.ParsedBinaryTimestamp toProlepticParsedTimestampBin(byte[] bytes) throws PSQLException
      Throws:
      PSQLException
    • toLocalDateTimeBin

      public 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 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, 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(String id)
    • convertToDate

      public Date convertToDate(long millis, 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 Time convertToTime(long millis, 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 String timeToString(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(TimeZone tz, byte[] bytes, 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 TimeZone parseBackendTimeZone(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)