Skip to content

Commit

Permalink
JDBC-540 Add support for legacy JDBC date/time types
Browse files Browse the repository at this point in the history
  • Loading branch information
mrotteveel committed Mar 30, 2019
1 parent 95e1857 commit 0f3ad42
Show file tree
Hide file tree
Showing 8 changed files with 707 additions and 135 deletions.
57 changes: 39 additions & 18 deletions devdoc/jdp/jdp-2019-03-time-zone-support.md
Expand Up @@ -167,6 +167,43 @@ Jaybird 4 will support Java 7 and higher, and Java 7 does not include `java.time

11. The driver-side session time zone for deriving time/timestamp values will
also be applied when connecting to earlier Firebird versions.

12. Support legacy types `java.sql.Time`, `java.sql.Timestamp` for the `WITH
TIME ZONE` types.

Although not specified by JDBC, this option allows for some flexibility for
applications or libraries still expecting `java.sql.*` types. It will also
ease migration between Java 7 and 8 or higher.

Firebird to Java conversion will derive the `OffsetDateTime` and then convert
this to epoch milliseconds, which is then used for constructing
`java.sql.Time` or `java.sql.Timestamp`. This will yield slightly different
results compared to `TIME WITHOUT TIME ZONE` type as there the conversion
applies 1970-01-01 instead of the current date.

Java to Firebird conversion will derive an `OffsetDateTime` using
`toLocalTime()` and the current date, or `toLocalDateTime()`, combined with
the default JVM time zone (it will not apply `sessionTimeZone`).

Methods with parameters of type `java.util.Calendar` will ignore the
calendar.

13. Support legacy types `java.sql.Date` for the `TIMESTAMP WITH TIME ZONE` type.

Although not specified by JDBC, this option allows for some flexibility for
applications or libraries still expecting `java.sql.*` types. It will also
ease migration between Java 7 and 8 or higher.

Firebird to Java conversion will derive the `OffsetDateTime` and then convert
this to epoch milliseconds, which is then used for constructing
`java.sql.Date`.

Java to Firebird conversion will derive an `OffsetDateTime`
using `toLocalDate()` at start of day combined with the default JVM time
zone (it will not apply `sessionTimeZone`).

Methods with parameters of type `java.util.Calendar` will ignore the
calendar.

### Open options or questions

Expand Down Expand Up @@ -204,25 +241,9 @@ Time zone support in Jaybird will not include the following:

If there is demand, we can always add it in later.

4. Support `java.sql.Time` and `java.sql.Timestamp` for `WITH TIME ZONE` types.

Although not specified by JDBC, this option allows for some flexibility for
applications or libraries still expecting `java.sql.*` types. It will also
ease migration between Java 7 and 8 or higher.

Decided to prefer to abandon support for the legacy types. If people really
need to use legacy types, they can use `set time zone bind legacy`.

5. Support `java.sql.Date` for `TIMESTAMP WITH TIME ZONE` type.

Although not specified by JDBC, this option allows for some flexibility for
applications or libraries still expecting `java.sql.*` types. It will also
ease migration between Java 7 and 8 or higher.

Possible confusion/ambiguity. See also section 4.6 in ISO-9075-2:2016.
4. _removed, see decision 12_

Decided to prefer to abandon support for the legacy types, see also rejected
option 4.
5. _removed, see decision 13_

6. Support `OffsetTime`/`OffsetDateTime` on `WITHOUT TIME ZONE` types.

Expand Down
73 changes: 58 additions & 15 deletions src/documentation/release_notes.md
Expand Up @@ -818,13 +818,23 @@ marked with * are not defined in JDBC)
- On get, if the value is a named zone, it will derive the offset using the
current date
- `java.time.OffsetDateTime`
- On set the date information is removed
- On get the current date is added
- On set the date information is removed
- `java.lang.String`
- On get applies `OffsetTime.toString()` (eg `13:25:13.1+01:00`)
- On set tries the default parse format of either `OffsetTime` or
`OffsetDateTime` (eg `13:25:13.1+01:00` or `2019-03-10T13:25:13+01:00`)
and then sets as that type
- `java.sql.Time`
- On get obtains `java.time.OffsetDateTime`, converts this to epoch
milliseconds and uses `new java.sql.Time(millis)`
- On set applies `toLocalTime()`, combines this with `LocalDate.now()`
and then derives the offset time for the default JVM time zone
- `java.sql.Timestamp`
- On get obtains `java.time.OffsetDateTime`, converts this to epoch
milliseconds and uses `new java.sql.Timestamp(millis)`
- On set applies `toLocalDateTime()` and derives the offset time for the
default JVM time zone

`TIMESTAMP WITH TIME ZONE`:

Expand All @@ -837,12 +847,42 @@ marked with * are not defined in JDBC)
- On set tries the default parse format of either `OffsetTime` or
`OffsetDateTime` (eg `13:25:13.1+01:00` or `2019-03-10T13:25:13+01:00`)
and then sets as that type
- `java.sql.Time`
- On get obtains `java.time.OffsetDateTime`, converts this to epoch
milliseconds and uses `new java.sql.Time(millis)`
- On set applies `toLocalTime()`, combines this with `LocalDate.now()`
and then derives the offset date time for the default JVM time zone
- `java.sql.Timestamp`
- On get obtains `java.time.OffsetDateTime`, converts this to epoch
milliseconds and uses `new java.sql.Timestamp(millis)`
- On set applies `toLocalDateTime()` and derives the offset date time for the
default JVM time zone
- `java.sql.Date`
- On get obtains `java.time.OffsetDateTime`, converts this to epoch
milliseconds and uses `new java.sql.Date(millis)`
- On set applies `toLocalDate()` at start of day and derives the offset date
time for the default JVM time zone

#### Support for legacy JDBC date/time types ####

For the `WITH TIME ZONE` types, JDBC does not define support for the legacy JDBC
types (`java.sql.Time`, `java.sql.Timestamp` and `java.sql.Date`). To ease the
transition and potential compatibility with tools and libraries, Jaybird does
provide support. However, we strongly recommend to avoid using these types.

Compared to the `WITHOUT TIME ZONE` types, there may be small discrepancies in
values as Jaybird uses 1970-01-01 for `WITHOUT TIME ZONE`, while for `WITH TIME
ZONE` it uses the current date. If this is problematic, then either apply the
necessary conversions yourself, enable legacy time zone bind, or define or cast
your columns as `TIME` or `TIMESTAMP`.

#### No support for other java.time types ####

The legacy JDBC types `java.sql.Time`, `java.sql.Timestamp` and `java.sql.Date`
are not supported, nor are `java.time.LocalTime`, `java.time.LocalDateTime` or
`java.time.LocalDate`. Supporting these types would be ambiguous. If you need to
use these, then either apply the necessary conversions yourself, enable legacy
time zone bind, or define or cast your columns as `TIME` or `TIMESTAMP`.
The types `java.time.LocalTime`, `java.time.LocalDateTime` and
`java.time.LocalDate` are not supported. Supporting these types would be
ambiguous. If you need to use these, then either apply the necessary conversions
yourself, enable legacy time zone bind, or define or cast your columns as `TIME`
or `TIMESTAMP`.
**NOTE: This is not final yet**

Jaybird also does not support non-standard extensions like `java.time.Instant`,
Expand Down Expand Up @@ -897,17 +937,21 @@ Other examples include values generated in triggers and default value clauses.

#### Session time zone for conversion ####

The session time zone will also be used to derive the `java.sql.Time`,
`java.sql.Timestamp` and `java.sql.Date` values. This is also done for
Firebird 3 and earlier.
For `WITHOUT TIME ZONE` types, the session time zone will be used to derive the
`java.sql.Time`, `java.sql.Timestamp` and `java.sql.Date` values. This is also
done for Firebird 3 and earlier.

If Java does not know the session time zone, no error is reported, but when
retrieving `java.sql.Time`, `java.sql.Timestamp` or `java.sql.Date` a warning is
logged and conversion will happen in GMT, which might yield unexpected values.

We strongly suggest that you use `java.time.LocalTime`,
`java.time.LocalDateTime` and `java.time.LocalDate` types instead of these
legacy datetime types.

If Java does not know the session time zone, no error is reported, but when
retrieving `java.sql.Time`, `java.sql.Timestamp` or `java.sql.Date` a warning is
logged and conversion will happen in GMT, which might yield unexpected values.
For `WITH TIME ZONE` types, the session time zone has no effect on the conversion
to the legacy JDBC date/time types: to offset date/time is converted to epoch
milliseconds and used to construct these legacy types directly.

Executing `SET TIME ZONE <zone name>` statements after connect will change the
session time zone on the server, but Jaybird will continue to use the session
Expand All @@ -925,9 +969,8 @@ In addition to the standard-defined types, it also supports the type names

### Caveats for time zone types ###

- Time zone fields do not support the legacy JDBC types `java.sql.Time`,
`java.sql.Timestamp`, `java.sql.Date`, nor do they support
`java.time.LocalDate`, `java.time.LocalTime`, `java.time.LocalDateTime`.
- Time zone fields do not support `java.time.LocalDate`, `java.time.LocalTime`,
`java.time.LocalDateTime`.
**NOTE: This is not final yet**

- Firebird 4 redefines `CURRENT_TIME` and `CURRENT_TIMESTAMP` to return a
Expand Down
174 changes: 174 additions & 0 deletions src/jdbc_42/org/firebirdsql/jdbc/field/AbstractWithTimeZoneField.java
@@ -0,0 +1,174 @@
/*
* Firebird Open Source JavaEE Connector - JDBC Driver
*
* Distributable under LGPL license.
* You may obtain a copy of the License at http://www.gnu.org/copyleft/lgpl.html
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* LGPL License for more details.
*
* This file was created by members of the firebird development team.
* All individual contributions remain the Copyright (C) of those
* individuals. Contributors to this file are either listed here or
* can be obtained from a source control history command.
*
* All rights reserved.
*/
package org.firebirdsql.jdbc.field;

import org.firebirdsql.gds.ng.fields.FieldDescriptor;
import org.firebirdsql.gds.ng.tz.TimeZoneDatatypeCoder;

import java.sql.SQLException;
import java.sql.SQLNonTransientException;
import java.time.*;
import java.util.Calendar;

import static org.firebirdsql.jdbc.JavaTypeNameConstants.OFFSET_DATE_TIME_CLASS_NAME;
import static org.firebirdsql.jdbc.JavaTypeNameConstants.OFFSET_TIME_CLASS_NAME;

/**
* Superclass for {@link FBTimeTzField}, {@link FBTimestampTzField} to handle legacy date/time types and common behaviour.
*
* @author <a href="mailto:mrotteveel@users.sourceforge.net">Mark Rotteveel</a>
*/
abstract class AbstractWithTimeZoneField extends FBField {

private ZoneId defaultZoneId;

AbstractWithTimeZoneField(FieldDescriptor fieldDescriptor, FieldDataProvider dataProvider, int requiredType)
throws SQLException {
super(fieldDescriptor, dataProvider, requiredType);
}

abstract OffsetDateTime getOffsetDateTime() throws SQLException;

abstract void setOffsetDateTime(OffsetDateTime offsetDateTime) throws SQLException;

abstract OffsetTime getOffsetTime() throws SQLException;

abstract void setOffsetTime(OffsetTime offsetTime) throws SQLException;

@SuppressWarnings("unchecked")
@Override
public <T> T getObject(Class<T> type) throws SQLException {
if (type == null) {
throw new SQLNonTransientException("getObject called with type null");
}
switch (type.getName()) {
case OFFSET_TIME_CLASS_NAME:
return (T) getOffsetTime();
case OFFSET_DATE_TIME_CLASS_NAME:
return (T) getOffsetDateTime();
}
return super.getObject(type);
}

@Override
public void setObject(Object value) throws SQLException {
if (value == null) {
setNull();
return;
}

if (value instanceof OffsetTime) {
setOffsetTime((OffsetTime) value);
} else if (value instanceof OffsetDateTime) {
setOffsetDateTime((OffsetDateTime) value);
} else {
super.setObject(value);
}
}

@Override
public java.sql.Time getTime() throws SQLException {
OffsetDateTime offsetDateTime = getOffsetDateTime();
if (offsetDateTime == null) {
return null;
}
return new java.sql.Time(offsetDateTime.toInstant().toEpochMilli());
}

@Override
public java.sql.Time getTime(Calendar cal) throws SQLException {
// Intentionally ignoring calendar, see jdp-2019-03
return getTime();
}

@Override
public void setTime(java.sql.Time value) throws SQLException {
if (value == null) {
setNull();
return;
}

OffsetDateTime offsetDateTime = ZonedDateTime.of(LocalDate.now(), value.toLocalTime(), getDefaultZoneId())
.toOffsetDateTime();
setOffsetDateTime(offsetDateTime);
}

@Override
public void setTime(java.sql.Time value, Calendar cal) throws SQLException {
// Intentionally ignoring calendar, see jdp-2019-03
setTime(value);
}

@Override
public java.sql.Timestamp getTimestamp() throws SQLException {
OffsetDateTime offsetDateTime = getOffsetDateTime();
if (offsetDateTime == null) {
return null;
}
return new java.sql.Timestamp(offsetDateTime.toInstant().toEpochMilli());
}

@Override
public java.sql.Timestamp getTimestamp(Calendar cal) throws SQLException {
// Intentionally ignoring calendar, see jdp-2019-03
return getTimestamp();
}

@Override
public void setTimestamp(java.sql.Timestamp value) throws SQLException {
if (value == null) {
setNull();
return;
}

OffsetDateTime offsetDateTime = value.toLocalDateTime()
.atZone(getDefaultZoneId())
.toOffsetDateTime();
setOffsetDateTime(offsetDateTime);
}

@Override
public void setTimestamp(java.sql.Timestamp value, Calendar cal) throws SQLException {
// Intentionally ignoring calendar, see jdp-2019-03
setTimestamp(value);
}

final TimeZoneDatatypeCoder getTimeZoneDatatypeCoder() {
return TimeZoneDatatypeCoder.getInstanceFor(getDatatypeCoder());
}

final ZoneId getDefaultZoneId() {
if (defaultZoneId != null) {
return defaultZoneId;
}
return defaultZoneId = ZoneId.systemDefault();
}

void setStringParse(String value) throws SQLException {
// TODO Better way to do this?
// TODO More lenient parsing?
if (value.indexOf('T') != -1) {
OffsetDateTime offsetDateTime = OffsetDateTime.parse(value.trim());
setOffsetDateTime(offsetDateTime);
} else {
OffsetTime offsetTime = OffsetTime.parse(value.trim());
setOffsetTime(offsetTime);
}
}
}

0 comments on commit 0f3ad42

Please sign in to comment.