Package org.postgresql.jdbc
Class TimestampUtils
java.lang.Object
org.postgresql.jdbc.TimestampUtils
Misc utils for handling time and date values.
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescription(package private) static enum
private static class
private static class
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate Calendar
private ZoneOffset
private final Calendar
private static final Field
private TimeZone
private static final byte[]
private final ResourceLock
private static final LocalDateTime
private static final int
private static final byte[]
private static final OffsetDateTime
private static final LocalTime
private static final long
private static final LocalDate
private static final LocalDateTime
private static final OffsetDateTime
private static final byte[]
private static final char[][]
private static final Duration
private static final int
Number of milliseconds in one day.private static final Duration
private TimeZone
private final StringBuilder
private final boolean
True if the backend uses doubles for time values.private static final TimeZone
private static final char[]
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionprivate static void
appendDate
(StringBuilder sb, int year, int month, int day) private static void
appendDate
(StringBuilder sb, LocalDate localDate) private static void
appendDate
(StringBuilder sb, Calendar cal) private static void
appendEra
(StringBuilder sb, LocalDate localDate) private static void
appendEra
(StringBuilder sb, Calendar cal) private static void
appendTime
(StringBuilder sb, int hours, int minutes, int seconds, int nanos) Appends time part to theStringBuilder
in PostgreSQL-compatible format.private static void
appendTime
(StringBuilder sb, LocalTime localTime) private static void
appendTime
(StringBuilder sb, Calendar cal, int nanos) private void
appendTimeZone
(StringBuilder sb, int offset) private void
appendTimeZone
(StringBuilder sb, ZoneOffset offset) private void
appendTimeZone
(StringBuilder sb, Calendar cal) convertToDate
(long millis, TimeZone tz) Extracts the date part from a timestamp.convertToTime
(long millis, TimeZone tz) Extracts the time part from a timestamp.private static int
firstNonDigit
(byte[] bytes, int start) private static long
floorDiv
(long x, long y) private static long
floorMod
(long x, long y) private Calendar
getCalendar
(ZoneOffset offset) private TimeZone
getSharedCalendar
(TimeZone timeZone) Get a shared calendar, applying the supplied time zone or the default time zone if null.private long
guessTimestamp
(long millis, TimeZone tz) Given a UTC timestampmillis
finds another point in time that is rendered in given time zonetz
exactly as "millis in UTC".boolean
private static boolean
private static boolean
nanosExceed499
(int nanos) Returns true when microsecond part of the time should be increased when rounding to microsecondsprivate static int
number
(byte[] bytes, int start, int end) private TimestampUtils.ParsedTimestamp
parseBackendTimestamp
(byte[] s) Load date/time information into the provided calendar returning the fractional seconds.static TimeZone
parseBackendTimeZone
(String timeZone) Converts backend's TimeZone parameter to java format.(package private) TimestampUtils.ParsedTimestamp
parseDate
(byte[] dateBytes) private Calendar
setupCalendar
(Calendar cal) private static int
skipWhitespace
(byte[] bytes, int start) timeToString
(Date time, boolean withTimeZone) Returns the given time value as String matching what the current postgresql server would send in text mode.void
Converts the SQL Date to binary representation forOid.DATE
.Deprecated.Returns the SQL Date object matching the given bytes withOid.DATE
.private static long
toJavaSecs
(long secs) Converts the given postgresql seconds to java seconds.toLocalDate
(byte[] dateBytes) toLocalDateBin
(byte[] bytes) Returns the local date time object matching the given bytes withOid.DATE
orOid.TIMESTAMP
.toLocalDateTime
(byte[] bytes) Parse an array of bytes and return a LocalDateTime representing its value.Deprecated.toLocalDateTimeBin
(byte[] bytes) Returns the local date time object matching the given bytes withOid.TIMESTAMP
orOid.TIMESTAMPTZ
.Parse a string and return a LocalTime representing its value.toLocalTimeBin
(byte[] bytes) Returns the SQL Time object matching the given bytes withOid.TIME
.toOffsetDateTime
(byte[] bytes) Parse an array of bytes and return a OffsetDateTime representing its value.Deprecated.Deprecated.was used internally, and not used anymoretoOffsetDateTimeBin
(byte[] bytes) Returns the offset date time object matching the given bytes with Oid#TIMESTAMPTZ.toOffsetTime
(byte[] bytes) Parse an array of bytes and return a OffsetTime representing its value.Deprecated.in usetoOffsetTime(byte[])
insteadtoOffsetTimeBin
(byte[] bytes) Returns the offset time object matching the given bytes with Oid#TIMETZ or Oid#TIME.toParsedTimestampBin
(TimeZone tz, byte[] bytes, boolean timestamptz) toParsedTimestampBinPlain
(byte[] bytes) private static long
toPgSecs
(long secs) Converts the given java seconds to postgresql seconds.toProlepticParsedTimestampBin
(byte[] bytes) toString
(LocalDateTime localDateTime) FormatsLocalDateTime
to be sent to the backend, thus it adds time zone.toString
(OffsetDateTime offsetDateTime) toString
(OffsetTime offsetTime) toStringOffsetDateTime
(byte[] value) Convertstimestamptz
to string taking client time zone (timeZoneProvider
) into account.toStringOffsetTimeBin
(byte[] value) Convertstimetz
to string taking client time zone (timeZoneProvider
) into account.Deprecated.Returns the SQL Time object matching the given bytes withOid.TIME
orOid.TIMETZ
.toTimestamp
(Calendar cal, byte[] bytes) Parse an array of bytes and return a timestamp representing its value.toTimestamp
(Calendar cal, String s) Deprecated.toTimestampBin
(TimeZone tz, byte[] bytes, boolean timestamptz) Returns the SQL Timestamp object matching the given bytes withOid.TIMESTAMP
orOid.TIMESTAMPTZ
.PostgreSQL does not store the time zone in the binary representation of timestamptz.PostgreSQL does not store the time zone in the binary representation of timetz.
-
Field Details
-
ONEDAY
private static final int ONEDAYNumber of milliseconds in one day.- See Also:
-
ZEROS
private static final char[] ZEROS -
NUMBERS
private static final char[][] NUMBERS -
GMT_ZONES
-
MAX_NANOS_BEFORE_WRAP_ON_ROUND
private static final int MAX_NANOS_BEFORE_WRAP_ON_ROUND- See Also:
-
ONE_MICROSECOND
-
MAX_TIME
-
MAX_TIME_NANOS
private static final long MAX_TIME_NANOS -
MAX_OFFSET_DATETIME
-
MAX_LOCAL_DATETIME
-
MIN_LOCAL_DATE
-
MIN_LOCAL_DATETIME
-
MIN_OFFSET_DATETIME
-
PG_EPOCH_DIFF
-
DEFAULT_TIME_ZONE_FIELD
-
UTC_TIMEZONE
-
INFINITY
private static final byte[] INFINITY -
NEGATIVE_INFINITY
private static final byte[] NEGATIVE_INFINITY -
MAX_OFFSET
private static final byte[] MAX_OFFSET -
prevDefaultZoneFieldValue
-
defaultTimeZoneCache
-
sbuf
-
calendarWithUserTz
-
calCache
-
calCacheZone
-
usesDouble
private final boolean usesDoubleTrue if the backend uses doubles for time values. False if long is used. -
timeZoneProvider
-
lock
-
-
Constructor Details
-
TimestampUtils
-
-
Method Details
-
getCalendar
-
parseBackendTimestamp
Load date/time information into the provided calendar returning the fractional seconds.- Throws:
SQLException
-
parseDate
-
toTimestamp
Deprecated.Parse a string and return a timestamp representing its value.- Parameters:
cal
- calendar to be used to parse the input strings
- 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
Parse an array of bytes and return a timestamp representing its value.- Parameters:
cal
- calendar to be used to parse the input bytesbytes
- 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
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
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
Deprecated.in usetoOffsetTime(byte[])
insteadParse 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
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
Deprecated.- 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
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.was used internally, and not used anymoreReturns 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
Deprecated.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
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
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
Deprecated.- Throws:
SQLException
-
toTime
- Throws:
SQLException
-
toDate
Deprecated.- Throws:
SQLException
-
toDate
- Throws:
SQLException
-
toLocalDate
- Throws:
SQLException
-
setupCalendar
-
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
-
toString
-
toString
-
toString
-
toString
-
toString
-
appendDate
-
appendDate
-
appendTime
-
appendTime
Appends time part to theStringBuilder
in PostgreSQL-compatible format. The function truncates to microseconds. The value is expected to be rounded beforehand.- Parameters:
sb
- destinationhours
- hoursminutes
- minutesseconds
- secondsnanos
- nanoseconds
-
appendTimeZone
-
appendTimeZone
-
appendEra
-
toString
-
toString
-
toString
-
toStringOffsetTimeBin
Convertstimetz
to string taking client time zone (timeZoneProvider
) into account.- Parameters:
value
- binary representation oftimetz
- Returns:
- string representation of
timetz
- Throws:
PSQLException
-
withClientOffsetSameInstant
PostgreSQL does not store the time zone in the binary representation of timetz. However, we want to preserve the output ofgetString()
in both binary and text formats So we try a client time zone when serializingOffsetTime
to string.- Parameters:
input
- input offset time- Returns:
- adjusted offset time (it represents the same instant as the input one)
-
toString
-
toStringOffsetDateTime
Convertstimestamptz
to string taking client time zone (timeZoneProvider
) into account.- Parameters:
value
- binary representation oftimestamptz
- Returns:
- string representation of
timestamptz
- Throws:
PSQLException
-
withClientOffsetSameInstant
PostgreSQL does not store the time zone in the binary representation of timestamptz. However, we want to preserve the output ofgetString()
in both binary and text formats So we try a client time zone when serializingOffsetDateTime
to string.- Parameters:
input
- input offset date time- Returns:
- adjusted offset date time (it represents the same instant as the input one)
-
toString
FormatsLocalDateTime
to be sent to the backend, thus it adds time zone. Do not use this method inResultSet.getString(int)
- Parameters:
localDateTime
- The local date to format as a String- Returns:
- The formatted local date
-
appendDate
-
appendTime
-
appendTimeZone
-
appendEra
-
skipWhitespace
private static int skipWhitespace(byte[] bytes, int start) -
firstNonDigit
private static int firstNonDigit(byte[] bytes, int start) -
number
private static int number(byte[] bytes, int start, int end) -
toDateBin
Returns the SQL Date object matching the given bytes withOid.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
-
hasFastDefaultTimeZone
public boolean hasFastDefaultTimeZone() -
toTimeBin
Returns the SQL Time object matching the given bytes withOid.TIME
orOid.TIMETZ
.- Parameters:
tz
- The timezone used when received data isOid.TIME
, ignored if data already containsOid.TIMETZ
.bytes
- The binary encoded time value.- Returns:
- The parsed time object.
- Throws:
PSQLException
- If binary format could not be parsed.
-
toLocalTimeBin
Returns the SQL Time object matching the given bytes withOid.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 withOid.TIMESTAMP
orOid.TIMESTAMPTZ
.- Parameters:
tz
- The timezone used when received data isOid.TIMESTAMP
, ignored if data already containsOid.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
Returns the local date time object matching the given bytes withOid.TIMESTAMP
orOid.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
Returns the local date time object matching the given bytes withOid.DATE
orOid.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
Given a UTC timestampmillis
finds another point in time that is rendered in given time zonetz
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 timestamptz
- desired time zone- Returns:
- timestamp that would be rendered in
tz
likemillis
in UTC
-
isSimpleTimeZone
-
convertToDate
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
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
Returns the given time value as String matching what the current postgresql server would send in text mode.- Parameters:
time
- time valuewithTimeZone
- 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. SeetoPgSecs(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. SeetoJavaSecs(long)
for the reverse operation. The conversion is valid for any year 100 BC onwards.- Parameters:
secs
- Postgresql seconds.- Returns:
- Java seconds.
-
toBinDate
Converts the SQL Date to binary representation forOid.DATE
.- Parameters:
tz
- The timezone used.bytes
- The binary encoded date value.value
- value- Throws:
PSQLException
- If binary format could not be parsed.
-
parseBackendTimeZone
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)
-
toLocalDateTime(byte[])