Package org.postgresql.jdbc

Class TimestampUtils

java.lang.Object

org.postgresql.jdbc.TimestampUtils

public class TimestampUtils
extends java.lang.Object

Misc utils for handling time and date values.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
(package private) static class	TimestampUtils.Infinity
private static class	TimestampUtils.ParsedBinaryTimestamp
private static class	TimestampUtils.ParsedTimestamp

Field Summary

Fields

Modifier and Type	Field	Description
private java.util.Calendar	calCache
private java.time.ZoneOffset	calCacheZone
private java.util.Calendar	calendarWithUserTz
private static java.lang.reflect.Field	DEFAULT_TIME_ZONE_FIELD
private java.util.TimeZone	defaultTimeZoneCache
private static java.util.HashMap<java.lang.String,java.util.TimeZone>	GMT_ZONES
private ResourceLock	lock
private static java.time.LocalDateTime	MAX_LOCAL_DATETIME
private static int	MAX_NANOS_BEFORE_WRAP_ON_ROUND
private static java.time.OffsetDateTime	MAX_OFFSET_DATETIME
private static java.time.LocalTime	MAX_TIME
private static java.time.LocalDate	MIN_LOCAL_DATE
private static java.time.LocalDateTime	MIN_LOCAL_DATETIME
private static java.time.OffsetDateTime	MIN_OFFSET_DATETIME
private static char[][]	NUMBERS
private static java.time.Duration	ONE_MICROSECOND
private static int	ONEDAY	Number of milliseconds in one day.
private static java.time.Duration	PG_EPOCH_DIFF
private java.util.TimeZone	prevDefaultZoneFieldValue
private java.lang.StringBuilder	sbuf
private Provider<java.util.TimeZone>	timeZoneProvider
private boolean	usesDouble	True if the backend uses doubles for time values.
private static java.util.TimeZone	UTC_TIMEZONE
private static char[]	ZEROS

Constructor Summary

Constructors

Constructor	Description
TimestampUtils(boolean usesDouble, Provider<java.util.TimeZone> timeZoneProvider)

Method Summary

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

lock

private final ResourceLock lock

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.

toParsedTimestampBinPlain

private TimestampUtils.ParsedBinaryTimestamp toParsedTimestampBinPlain(byte[] bytes)
                                                                throws PSQLException

Throws:

PSQLException

toParsedTimestampBin

private TimestampUtils.ParsedBinaryTimestamp toParsedTimestampBin(java.util.TimeZone tz,
                                                                  byte[] bytes,
                                                                  boolean timestamptz)
                                                           throws PSQLException

Throws:

PSQLException

toProlepticParsedTimestampBin

private TimestampUtils.ParsedBinaryTimestamp toProlepticParsedTimestampBin(byte[] bytes)
                                                                    throws PSQLException

Throws:

PSQLException

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)