#758 Deprecate RawDateTimeStruct, and remove methods using it from Da…

…taTypeCoder

Though we deprecate the class for removal at the moment, we reserve the option to remove it entirely before Jaybird 6 release

src/docs/asciidoc/release_notes.adoc

@@ -954,15 +954,6 @@ there is no replacement
 there is no replacement
 ** `getLoggerImplementation()`;
 there is no replacement
-* `DatatypeCoder`
-** `encodeTimestamp(Timestamp, Calendar, boolean)`;
-use `encodeTimestamp(Timestamp, Calendar)`
-** `decodeTimestamp(Timestamp, Calendar, boolean)`
-use `decodeTimestamp(Timestamp, Calendar)`
-** `encodeTime(Time, Calendar, boolean)`;
-use `encodeTime(Time, Calendar)`
-** `decodeTime(Time, Calendar, boolean)`;
-use `decodeTime(Time, Calendar)`
 
 The following methods had their visibility reduced:
 
@@ -1215,6 +1206,27 @@ The new package is not exported from the module.
 ** `SQLExceptionChainBuilder`
 ** `StringUtils`
 * `DbMetadataMediator` was moved to package `org.firebirdsql.jdbc` for module accessibility reasons.
+* `DatatypeCoder`
+** `encodeTimestamp(Timestamp, Calendar, boolean)` was removed;
+use `encodeTimestamp(Timestamp, Calendar)`
+** `decodeTimestamp(Timestamp, Calendar, boolean)` was removed;
+use `decodeTimestamp(Timestamp, Calendar)`
+** `encodeTime(Time, Calendar, boolean)` was removed;
+use `encodeTime(Time, Calendar)`
+** `decodeTime(Time, Calendar, boolean)` was removed;
+use `decodeTime(Time, Calendar)`
+** `encodeTimestampRaw(DatatypeCoder.RawDateTimeStruct)` was removed;
+use `encodeLocalDateTime(LocalDateTime)`
+** `decodeTimestampRaw(byte[])` was removed;
+use `decodeLocalDateTime(byte[])`
+** `encodeTimeRaw(DatatypeCoder.RawDateTimeStruct)` was removed;
+use `encodeLocalTime(LocalTime)`
+** `decodeTimeRaw(byte[])` was removed;
+use `decodeLocalTime(byte[])`
+** `encodeDateRaw(DatatypeCoder.RawDateTimeStruct)` was removed;
+use `encodeLocalDate(LocalDate)`
+** `decodeDateRaw(byte[])` was removed;
+use `decodeLocalDate(byte[])`
 
 [#breaking-changes-unlikely]
 === Unlikely breaking changes
@@ -1250,16 +1262,24 @@ With Jaybird 7 the following breaking changes will be introduced.
 [#removal-of-deprecated-classes-packages-and-methods-7]
 ==== Removal of deprecated classes, packages and methods
 
+[WARNING]
+====
+Some deprecations currently listed for removal -- especially of internal API -- may be removed without deprecation later during Jaybird 6 development.
+====
+
 [#removal-of-deprecated-methods-7]
 ===== Removal of deprecated methods
 
 The following methods will be removed in Jaybird 7:
 
-* `GDSFactoryPlugin`
+* `GDSFactoryPlugin` (semi-internal API)
 ** `getTypeAliases()` -- use `getTypeAliasList()`.
 It may get removed in Jaybird 7 or later.
 ** `getSupportedProtocols` -- use `getSupportedProtocolList()`.
 It may get removed in Jaybird 7 or later.
+* `FBField` (internal API)
+** `getRawDateTimeStruct()` -- use `getLocalDateTime()`/`getLocalDate()`/`getLocalTime()`
+** `setRawDateTimeStruct(DatatypeCoder.RawDateTimeStruct)` ` -- use `setLocalDateTime(LocalDateTime)`/`setLocalDate(LocalDate)`/`setLocalTime(LocalTime)`
 
 [#removal-of-deprecated-classes-7]
 ===== Removal of deprecated classes
@@ -1270,6 +1290,8 @@ The following classes have been deprecated and will be removed in Jaybird 7:
 Previous versions of `GDSFactoryPlugin` declared `throws GDSException` for some methods, but now `throws SQLException`.
 To retain some semblance of backwards-compatibility, this class was retrofitted to extend `SQLException`.
 It may get removed in Jaybird 7 or later.
+* `DatatypeCoder.RawDateTimeStruct` -- use one of the `java.time` types (`LocalDateTime`, `LocalDate` or `LocalTime`).
+Though this class is publicly accessible through `ResultSet.getObject/updateObject` and `PreparedStatement.setObject`, it is internal API, and we expect it is unlikely to be actually used in user code.
 
 [#removal-of-deprecated-constants-7]
 ==== Removal of deprecated constants

src/main/org/firebirdsql/gds/ng/DatatypeCoder.java

@@ -270,15 +270,6 @@ public interface DatatypeCoder {
      */
     Timestamp encodeTimestamp(Timestamp val, Calendar c);
 
-    /**
-     * Encode the date and time portions of a raw date time struct as a byte array of 8 bytes.
-     *
-     * @param val
-     *         value to be encoded
-     * @return {@code val} encoded as a byte array, or {@code null} if {@code val} is {@code null}
-     */
-    byte[] encodeTimestampRaw(RawDateTimeStruct val);
-
     /**
      * Encode a {@code Timestamp} as a byte array of 8 bytes.
      *
@@ -301,15 +292,6 @@ public interface DatatypeCoder {
      */
     Timestamp decodeTimestamp(Timestamp val, Calendar c);
 
-    /**
-     * Decode the date and time portions of a raw date time struct from {@code buf} from the first 8 bytes.
-     *
-     * @param buf
-     *         byte array of sufficient size
-     * @return {@code RawDateTimeStruct} decoded from {@code buf}, or {@code null} if {@code buf} is {@code null}
-     */
-    RawDateTimeStruct decodeTimestampRaw(byte[] buf);
-
     /**
      * Decode a {@code Timestamp} from {@code buf} from the first 8 bytes.
      *
@@ -332,15 +314,6 @@ public interface DatatypeCoder {
      */
     Time encodeTime(Time val, Calendar c);
 
-    /**
-     * Encode the time portion of a raw date time struct as a byte array of 4 bytes.
-     *
-     * @param val
-     *         value to be encoded
-     * @return {@code val} encoded as a byte array, or {@code null} if {@code val} is {@code null}
-     */
-    byte[] encodeTimeRaw(RawDateTimeStruct val);
-
     /**
      * Encode a {@code Time} value as a byte array of 4 bytes.
      *
@@ -363,15 +336,6 @@ public interface DatatypeCoder {
      */
     Time decodeTime(Time val, Calendar c);
 
-    /**
-     * Decode the time portion of a raw date time struct from {@code buf} from the first 4 bytes.
-     *
-     * @param buf
-     *         byte array of sufficient size
-     * @return {@code RawDateTimeStruct} decoded from {@code buf}, or {@code null} if {@code buf} is {@code null}
-     */
-    RawDateTimeStruct decodeTimeRaw(byte[] buf);
-
     /**
      * Decode a {@code Time} value from {@code buf} from the first 4 bytes.
      *
@@ -394,15 +358,6 @@ public interface DatatypeCoder {
      */
     Date encodeDate(Date val, Calendar c);
 
-    /**
-     * Encode the date portion of a raw date time struct as a byte array of 4 bytes.
-     *
-     * @param val
-     *         value to be encoded
-     * @return {@code val} encoded as a byte array, or {@code null} if {@code val} is {@code null}
-     */
-    byte[] encodeDateRaw(RawDateTimeStruct val);
-
     /**
      * Encode a {@code Date} value as a {@code byte} array of 4 bytes.
      *
@@ -425,15 +380,6 @@ public interface DatatypeCoder {
      */
     Date decodeDate(Date val, Calendar c);
 
-    /**
-     * Decode the date portion of a raw date time struct from {@code buf} from the first 4 bytes.
-     *
-     * @param buf
-     *         byte array of sufficient size
-     * @return {@code RawDateTimeStruct} decoded from {@code buf}, or {@code null} if {@code buf} is {@code null}
-     */
-    RawDateTimeStruct decodeDateRaw(byte[] buf);
-
     /**
      * Decode a {@code Date} value from {@code buf} from the first 4 bytes.
      *
@@ -722,7 +668,9 @@ public interface DatatypeCoder {
      * "[timestamp is] stored a two long words, one representing the number of days since 17 Nov 1858 and one
      * representing number of 100 nano-seconds since midnight" (NOTE: It is actually 100 microseconds!)
      * </p>
+     * @deprecated use a suitable {@code java.time} type; will be removed in Jaybird 7
      */
+    @Deprecated(forRemoval = true, since = "6")
     final class RawDateTimeStruct {
         public int year;
         public int month;

src/main/org/firebirdsql/gds/ng/DefaultDatatypeCoder.java

@@ -240,11 +240,6 @@ private static int calculateOffset(Calendar cal) {
         return cal.getTimeZone().getRawOffset() - Calendar.getInstance().getTimeZone().getRawOffset();
     }
 
-    @Override
-    public byte[] encodeTimestampRaw(RawDateTimeStruct val) {
-        return val != null ? new datetime(val).toTimestampBytes() : null;
-    }
-
     @Override
     public byte[] encodeTimestampCalendar(Timestamp val, Calendar c) {
         /* note, we cannot simply pass millis to the database, because
@@ -263,11 +258,6 @@ public Timestamp decodeTimestamp(Timestamp val, Calendar c) {
         return new Timestamp(val.getTime() - calculateOffset(c));
     }
 
-    @Override
-    public RawDateTimeStruct decodeTimestampRaw(byte[] buf) {
-        return buf != null ? fromLongBytes(buf).getRaw() : null;
-    }
-
     @Override
     public Timestamp decodeTimestampCalendar(byte[] buf, Calendar c) {
         return buf != null ? fromLongBytes(buf).toTimestamp(c) : null;
@@ -279,11 +269,6 @@ public Time encodeTime(Time val, Calendar c) {
         return new Time(val.getTime() + calculateOffset(c));
     }
 
-    @Override
-    public byte[] encodeTimeRaw(RawDateTimeStruct val) {
-        return val != null ? new datetime(val).toTimeBytes() : null;
-    }
-
     @Override
     public byte[] encodeTimeCalendar(Time val, Calendar c) {
         return val != null ? new datetime(val, c).toTimeBytes() : null;
@@ -295,11 +280,6 @@ public Time decodeTime(Time val, Calendar c) {
         return new Time(val.getTime() - calculateOffset(c));
     }
 
-    @Override
-    public RawDateTimeStruct decodeTimeRaw(byte[] buf) {
-        return buf != null ? new datetime(buf, -1, 0).getRaw() : null;
-    }
-
     @Override
     public Time decodeTimeCalendar(byte[] buf, Calendar c) {
         return buf != null ? new datetime(buf, -1, 0).toTime(c) : null;
@@ -313,11 +293,6 @@ public Date encodeDate(Date val, Calendar c) {
         return new Date(c.getTime().getTime());
     }
 
-    @Override
-    public byte[] encodeDateRaw(RawDateTimeStruct val) {
-        return val != null ? new datetime(val).toDateBytes() : null;
-    }
-
     @Override
     public byte[] encodeDateCalendar(Date val, Calendar c) {
         return val != null ? new datetime(val, c).toDateBytes() : null;
@@ -330,11 +305,6 @@ public Date decodeDate(Date val, Calendar c) {
         return new Date(c.getTime().getTime());
     }
 
-    @Override
-    public RawDateTimeStruct decodeDateRaw(byte[] buf) {
-        return buf != null ? new datetime(buf, 0, -1).getRaw() : null;
-    }
-
     @Override
     public Date decodeDateCalendar(byte[] buf, Calendar c) {
         return buf != null ? new datetime(buf, 0, -1).toDate(c) : null;
@@ -573,6 +543,7 @@ private datetime fromLongBytes(byte[] buf) {
     /**
      * Helper Class to encode/decode times/dates
      */
+    @SuppressWarnings("removal")
     private class datetime {
 
         private final RawDateTimeStruct raw;
@@ -611,13 +582,6 @@ private class datetime {
             this.raw = new RawDateTimeStruct(raw);
         }
 
-        /**
-         * @return copy of the raw data time struct contained in this datetime.
-         */
-        RawDateTimeStruct getRaw() {
-            return new RawDateTimeStruct(raw);
-        }
-
         byte[] toTimeBytes() {
             return encodeInt(raw.getEncodedTime());
         }

src/main/org/firebirdsql/gds/ng/EncodingSpecificDatatypeCoder.java

@@ -221,11 +221,6 @@ public Timestamp encodeTimestamp(Timestamp val, Calendar c) {
         return parentCoder.encodeTimestamp(val, c);
     }
 
-    @Override
-    public byte[] encodeTimestampRaw(RawDateTimeStruct val) {
-        return parentCoder.encodeTimestampRaw(val);
-    }
-
     @Override
     public byte[] encodeTimestampCalendar(Timestamp val, Calendar c) {
         return parentCoder.encodeTimestampCalendar(val, c);
@@ -236,11 +231,6 @@ public Timestamp decodeTimestamp(Timestamp val, Calendar c) {
         return parentCoder.decodeTimestamp(val, c);
     }
 
-    @Override
-    public RawDateTimeStruct decodeTimestampRaw(byte[] buf) {
-        return parentCoder.decodeTimestampRaw(buf);
-    }
-
     @Override
     public Timestamp decodeTimestampCalendar(byte[] buf, Calendar c) {
         return parentCoder.decodeTimestampCalendar(buf, c);
@@ -251,11 +241,6 @@ public Time encodeTime(Time val, Calendar c) {
         return parentCoder.encodeTime(val, c);
     }
 
-    @Override
-    public byte[] encodeTimeRaw(RawDateTimeStruct val) {
-        return parentCoder.encodeTimeRaw(val);
-    }
-
     @Override
     public byte[] encodeTimeCalendar(Time val, Calendar c) {
         return parentCoder.encodeTimeCalendar(val, c);
@@ -266,11 +251,6 @@ public Time decodeTime(Time val, Calendar c) {
         return parentCoder.decodeTime(val, c);
     }
 
-    @Override
-    public RawDateTimeStruct decodeTimeRaw(byte[] buf) {
-        return parentCoder.decodeTimeRaw(buf);
-    }
-
     @Override
     public Time decodeTimeCalendar(byte[] buf, Calendar c) {
         return parentCoder.decodeTimeCalendar(buf, c);
@@ -281,11 +261,6 @@ public Date encodeDate(Date val, Calendar c) {
         return parentCoder.encodeDate(val, c);
     }
 
-    @Override
-    public byte[] encodeDateRaw(RawDateTimeStruct val) {
-        return parentCoder.encodeDateRaw(val);
-    }
-
     @Override
     public byte[] encodeDateCalendar(Date val, Calendar c) {
         return parentCoder.encodeDateCalendar(val, c);
@@ -296,11 +271,6 @@ public Date decodeDate(Date val, Calendar c) {
         return parentCoder.decodeDate(val, c);
     }
 
-    @Override
-    public RawDateTimeStruct decodeDateRaw(byte[] buf) {
-        return parentCoder.decodeDateRaw(buf);
-    }
-
     @Override
     public Date decodeDateCalendar(byte[] buf, Calendar c) {
         return parentCoder.decodeDateCalendar(buf, c);

src/main/org/firebirdsql/jdbc/field/FBDateField.java

@@ -18,7 +18,7 @@
  */
 package org.firebirdsql.jdbc.field;
 
-import org.firebirdsql.gds.ng.DatatypeCoder.RawDateTimeStruct;
+import org.firebirdsql.gds.ng.DatatypeCoder;
 import org.firebirdsql.gds.ng.fields.FieldDescriptor;
 import org.firebirdsql.jaybird.util.FbDatetimeConversion;
 
@@ -98,20 +98,23 @@ void setLocalDate(LocalDate value) throws SQLException {
         setFieldData(getDatatypeCoder().encodeLocalDate(value));
     }
 
+    @SuppressWarnings("removal")
     @Override
-    public RawDateTimeStruct getRawDateTimeStruct() throws SQLException {
+    public DatatypeCoder.RawDateTimeStruct getRawDateTimeStruct() throws SQLException {
         return convertForGet(getLocalDate(),
                 v -> {
-                    var raw = new RawDateTimeStruct();
+                    var raw = new DatatypeCoder.RawDateTimeStruct();
                     raw.updateDate(v);
                     return raw;
                 },
-                RawDateTimeStruct.class);
+                DatatypeCoder.RawDateTimeStruct.class);
     }
 
+    @SuppressWarnings("removal")
     @Override
-    public void setRawDateTimeStruct(RawDateTimeStruct raw) throws SQLException {
-        setLocalDate(convertForSet(raw, RawDateTimeStruct::toLocalDate, RawDateTimeStruct.class));
+    public void setRawDateTimeStruct(DatatypeCoder.RawDateTimeStruct raw) throws SQLException {
+        setLocalDate(convertForSet(raw, DatatypeCoder.RawDateTimeStruct::toLocalDate,
+                DatatypeCoder.RawDateTimeStruct.class));
     }
 
 }