Package org.postgresql.jdbc

# Class TimestampUtils

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

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

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `TimestampUtils(boolean usesDouble, Provider<TimeZone> timeZoneProvider)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Date`
  `convertToDate(long millis, @Nullable TimeZone tz)`
  Extracts the date part from a timestamp.
  `Time`
  `convertToTime(long millis, TimeZone tz)`
  Extracts the time part from a timestamp.
  `Calendar`
  `getSharedCalendar(@Nullable TimeZone timeZone)`
  Get a shared calendar, applying the supplied time zone or the default time zone if null.
  `boolean`
  `hasFastDefaultTimeZone()`
  `static TimeZone`
  `parseBackendTimeZone(String timeZone)`
  Converts backend's TimeZone parameter to java format.
  `String`
  `timeToString(Date time, boolean withTimeZone)`
  Returns the given time value as String matching what the current postgresql server would send in text mode.
  `void`
  `toBinDate(@Nullable TimeZone tz, byte[] bytes, Date value)`
  Converts the SQL Date to binary representation for `Oid.DATE`.
  `@PolyNull Date`
  `toDate(@Nullable Calendar cal, byte @PolyNull [] dateBytes)`
  `@PolyNull Date`
  `toDate(@Nullable Calendar cal, @PolyNull String s)`
  `Date`
  `toDateBin(@Nullable TimeZone tz, byte[] bytes)`
  Returns the SQL Date object matching the given bytes with `Oid.DATE`.
  `@PolyNull LocalDate`
  `toLocalDate(byte @PolyNull [] dateBytes)`
  `LocalDate`
  `toLocalDateBin(byte[] bytes)`
  Returns the local date time object matching the given bytes with `Oid.DATE` or `Oid.TIMESTAMP`.
  `@PolyNull LocalDateTime`
  `toLocalDateTime(byte @PolyNull [] bytes)`
  Parse an array of bytes and return a LocalDateTime representing its value.
  `@PolyNull LocalDateTime`
  `toLocalDateTime(@PolyNull String s)`
  `LocalDateTime`
  `toLocalDateTimeBin(byte[] bytes)`
  Returns the local date time object matching the given bytes with `Oid.TIMESTAMP` or `Oid.TIMESTAMPTZ`.
  `@PolyNull LocalTime`
  `toLocalTime(@PolyNull String s)`
  Parse a string and return a LocalTime representing its value.
  `LocalTime`
  `toLocalTimeBin(byte[] bytes)`
  Returns the SQL Time object matching the given bytes with `Oid.TIME`.
  `@PolyNull OffsetDateTime`
  `toOffsetDateTime(byte @PolyNull [] bytes)`
  Parse an array of bytes and return a OffsetDateTime representing its value.
  `@PolyNull OffsetDateTime`
  `toOffsetDateTime(@PolyNull String s)`
  Parse a string and return a OffsetDateTime representing its value.
  `OffsetDateTime`
  `toOffsetDateTime(Time t)`
  Deprecated.
  was used internally, and not used anymore
  `OffsetDateTime`
  `toOffsetDateTimeBin(byte[] bytes)`
  Returns the offset date time object matching the given bytes with Oid#TIMESTAMPTZ.
  `@PolyNull OffsetTime`
  `toOffsetTime(byte @PolyNull [] bytes)`
  Parse an array of bytes and return a OffsetTime representing its value.
  `@PolyNull OffsetTime`
  `toOffsetTime(@PolyNull String s)`
  Parse a string and return a OffsetTime representing its value.
  `OffsetTime`
  `toOffsetTimeBin(byte[] bytes)`
  Returns the offset time object matching the given bytes with Oid#TIMETZ or Oid#TIME.
  `String`
  `toString(LocalDate localDate)`
  `String`
  `toString(LocalDateTime localDateTime)`
  Formats `LocalDateTime` to be sent to the backend, thus it adds time zone.
  `String`
  `toString(LocalTime localTime)`
  `String`
  `toString(OffsetDateTime offsetDateTime)`
  `String`
  `toString(OffsetTime offsetTime)`
  `String`
  `toString(@Nullable Calendar cal, Date x)`
  `String`
  `toString(@Nullable Calendar cal, Date x, boolean withTimeZone)`
  `String`
  `toString(@Nullable Calendar cal, Time x)`
  `String`
  `toString(@Nullable Calendar cal, Time x, boolean withTimeZone)`
  `String`
  `toString(@Nullable Calendar cal, Timestamp x)`
  `String`
  `toString(@Nullable Calendar cal, Timestamp x, boolean withTimeZone)`
  `String`
  `toStringOffsetDateTime(byte[] value)`
  Converts `timestamptz` to string taking client time zone (`timeZoneProvider`) into account.
  `String`
  `toStringOffsetTimeBin(byte[] value)`
  Converts `timetz` to string taking client time zone (`timeZoneProvider`) into account.
  `@PolyNull Time`
  `toTime(@Nullable Calendar cal, byte @PolyNull [] bytes)`
  `@PolyNull Time`
  `toTime(@Nullable Calendar cal, @PolyNull String s)`
  `Time`
  `toTimeBin(@Nullable TimeZone tz, byte[] bytes)`
  Returns the SQL Time object matching the given bytes with `Oid.TIME` or `Oid.TIMETZ`.
  `@PolyNull Timestamp`
  `toTimestamp(@Nullable Calendar cal, byte @PolyNull [] bytes)`
  Parse an array of bytes and return a timestamp representing its value.
  `@PolyNull Timestamp`
  `toTimestamp(@Nullable Calendar cal, @PolyNull String s)`
  Parse a string and return a timestamp representing its value.
  `Timestamp`
  `toTimestampBin(@Nullable TimeZone tz, byte[] bytes, boolean timestamptz)`
  Returns the SQL Timestamp object matching the given bytes with `Oid.TIMESTAMP` or `Oid.TIMESTAMPTZ`.
  `OffsetDateTime`
  `withClientOffsetSameInstant(OffsetDateTime input)`
  PostgreSQL does not store the time zone in the binary representation of timestamptz.
  `OffsetTime`
  `withClientOffsetSameInstant(OffsetTime input)`
  PostgreSQL does not store the time zone in the binary representation of timetz.

  ### Methods inherited from class java.lang.Object

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

- ## Constructor Details

  - ### TimestampUtils

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

- ## Method Details

  - ### toTimestamp

    public @PolyNull Timestamp toTimestamp(@Nullable Calendar cal, @PolyNull 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 formatted 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.

  - ### toTimestamp

    public @PolyNull Timestamp toTimestamp(@Nullable Calendar cal, byte @PolyNull [] bytes) throws SQLException
    Parse an array of bytes and return a timestamp representing its value.
    Parameters:
      `cal` - calendar to be used to parse the input bytes
      `bytes` - The ISO formatted date to parse.
    Returns:
      null if bytes is null or a timestamp of the parsed bytes.
    Throws:
      `SQLException` - if there is a problem parsing bytes.

  - ### toLocalTime

    public @PolyNull LocalTime toLocalTime(@PolyNull String s) throws SQLException
    Parse a string and return a LocalTime representing its value.
    Parameters:
      `s` - The ISO formatted 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 @PolyNull OffsetTime toOffsetTime(@PolyNull String s) throws SQLException
    Parse a string and return a OffsetTime representing its value.
    Parameters:
      `s` - The ISO formatted 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.

  - ### toOffsetTime

    public @PolyNull OffsetTime toOffsetTime(byte @PolyNull [] bytes) throws SQLException
    Parse an array of bytes and return a OffsetTime representing its value.
    Parameters:
      `bytes` - The ISO time formatted array of bytes time to parse.
    Returns:
      null if bytes are null or a OffsetTime of the parsed string .
    Throws:
      `SQLException` - if there is a problem parsing bytes.

  - ### toLocalDateTime

    public @PolyNull LocalDateTime toLocalDateTime(@PolyNull String s) throws SQLException
    Parameters:
      `s` - The ISO formatted 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.

  - ### toLocalDateTime

    public @PolyNull LocalDateTime toLocalDateTime(byte @PolyNull [] bytes) throws SQLException
    Parse an array of bytes and return a LocalDateTime representing its value.
    Parameters:
      `bytes` - The ISO formatted date array of bytes to parse.
    Returns:
      null if s is null or a LocalDateTime of the parsed string s.
    Throws:
      `SQLException` - if there is a problem parsing bytes.

  - ### 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 @PolyNull OffsetDateTime toOffsetDateTime(@PolyNull 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.

  - ### toOffsetDateTime

    public @PolyNull OffsetDateTime toOffsetDateTime(byte @PolyNull [] bytes) throws SQLException
    Parse an array of bytes and return a OffsetDateTime representing its value.
    Parameters:
      `bytes` - The ISO formatted date string to parse.
    Returns:
      null if bytes is null or an OffsetDateTime of the parsed array of bytes.
    Throws:
      `SQLException` - if there is a problem parsing bytes.

  - ### 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 @PolyNull Time toTime(@Nullable Calendar cal, @PolyNull String s) throws SQLException
    Throws:
      `SQLException`

  - ### toTime

    public @PolyNull Time toTime(@Nullable Calendar cal, byte @PolyNull [] bytes) throws SQLException
    Throws:
      `SQLException`

  - ### toDate

    public @PolyNull Date toDate(@Nullable Calendar cal, @PolyNull String s) throws SQLException
    Throws:
      `SQLException`

  - ### toDate

    public @PolyNull Date toDate(@Nullable Calendar cal, byte @PolyNull [] dateBytes) throws SQLException
    Throws:
      `SQLException`

  - ### toLocalDate

    public @PolyNull LocalDate toLocalDate(byte @PolyNull [] dateBytes) throws SQLException
    Throws:
      `SQLException`

  - ### getSharedCalendar

    public Calendar getSharedCalendar(@Nullable 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.

  - ### toString

    public String toString(@Nullable Calendar cal, Timestamp x)

  - ### toString

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

  - ### toString

    public String toString(@Nullable Calendar cal, Date x)

  - ### toString

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

  - ### toString

    public String toString(@Nullable Calendar cal, Time x)

  - ### toString

    public String toString(@Nullable Calendar cal, Time x, boolean withTimeZone)

  - ### toString

    public String toString(LocalDate localDate)

  - ### toString

    public String toString(LocalTime localTime)

  - ### toString

    public String toString(OffsetTime offsetTime)

  - ### toStringOffsetTimeBin

    public String toStringOffsetTimeBin(byte[] value) throws PSQLException
    Converts `timetz` to string taking client time zone (`timeZoneProvider`) into account.
    Parameters:
      `value` - binary representation of `timetz`
    Returns:
      string representation of `timetz`
    Throws:
      `PSQLException`

  - ### withClientOffsetSameInstant

    public OffsetTime withClientOffsetSameInstant(OffsetTime input)
    PostgreSQL does not store the time zone in the binary representation of timetz. However, we want to preserve the output of `getString()` in both binary and text formats So we try a client time zone when serializing `OffsetTime` to string.
    Parameters:
      `input` - input offset time
    Returns:
      adjusted offset time (it represents the same instant as the input one)

  - ### toString

    public String toString(OffsetDateTime offsetDateTime)

  - ### toStringOffsetDateTime

    public String toStringOffsetDateTime(byte[] value) throws PSQLException
    Converts `timestamptz` to string taking client time zone (`timeZoneProvider`) into account.
    Parameters:
      `value` - binary representation of `timestamptz`
    Returns:
      string representation of `timestamptz`
    Throws:
      `PSQLException`

  - ### withClientOffsetSameInstant

    public OffsetDateTime withClientOffsetSameInstant(OffsetDateTime input)
    PostgreSQL does not store the time zone in the binary representation of timestamptz. However, we want to preserve the output of `getString()` in both binary and text formats So we try a client time zone when serializing `OffsetDateTime` to string.
    Parameters:
      `input` - input offset date time
    Returns:
      adjusted offset date time (it represents the same instant as the input one)

  - ### 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

  - ### toDateBin

    public Date toDateBin(@Nullable 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.

  - ### hasFastDefaultTimeZone

    public boolean hasFastDefaultTimeZone()

  - ### toTimeBin

    public Time toTimeBin(@Nullable 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(@Nullable 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 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.

  - ### convertToDate

    public Date convertToDate(long millis, @Nullable 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

  - ### toBinDate

    public void toBinDate(@Nullable 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