deprecate APIs involving java.util.Date and friends

note that we're not making these for removal see jakartaee#402
gavinking · Aug 11, 2023 · 5604d11 · 5604d11
1 parent 3fc0666
commit 5604d11
Show file tree

Hide file tree

Showing 7 changed files with 73 additions and 3 deletions.
diff --git a/api/src/main/java/jakarta/persistence/MapKeyTemporal.java b/api/src/main/java/jakarta/persistence/MapKeyTemporal.java
@@ -42,7 +42,11 @@
  * </pre>
  *
  * @since 2.0
+ *
+ * @deprecated Newly-written code should use the date/time types
+ *             defined in {@link java.time}.
  */
+@Deprecated(since = "3.2")
 @Target({METHOD, FIELD}) 
 @Retention(RUNTIME)
 public @interface MapKeyTemporal {

diff --git a/api/src/main/java/jakarta/persistence/Query.java b/api/src/main/java/jakarta/persistence/Query.java
@@ -233,7 +233,10 @@ default Stream getResultStream() {
      * @throws IllegalArgumentException if the parameter does not
      *         correspond to a parameter of the query
      * @since 2.0
+     * @deprecated Newly-written code should use the date/time types
+     *             defined in {@link java.time}.
      */
+    @Deprecated(since = "3.2")
     Query setParameter(Parameter<Calendar> param, Calendar value, 
                        TemporalType temporalType);
 
@@ -246,7 +249,10 @@ Query setParameter(Parameter<Calendar> param, Calendar value,
      * @throws IllegalArgumentException if the parameter does not
      *         correspond to a parameter of the query
      * @since 2.0
+     * @deprecated Newly-written code should use the date/time types
+     *             defined in {@link java.time}.
      */
+    @Deprecated(since = "3.2")
     Query setParameter(Parameter<Date> param, Date value, 
                        TemporalType temporalType);
 
@@ -270,7 +276,10 @@ Query setParameter(Parameter<Date> param, Date value,
      * @throws IllegalArgumentException if the parameter name does 
      *         not correspond to a parameter of the query or if
      *         the value argument is of incorrect type
+     * @deprecated Newly-written code should use the date/time types
+     *             defined in {@link java.time}.
      */
+    @Deprecated(since = "3.2")
     Query setParameter(String name, Calendar value, 
                        TemporalType temporalType);
 
@@ -283,7 +292,10 @@ Query setParameter(String name, Calendar value,
      * @throws IllegalArgumentException if the parameter name does 
      *         not correspond to a parameter of the query or if
      *         the value argument is of incorrect type
+     * @deprecated Newly-written code should use the date/time types
+     *             defined in {@link java.time}.
      */
+    @Deprecated(since = "3.2")
     Query setParameter(String name, Date value, 
                        TemporalType temporalType);
 
@@ -308,7 +320,10 @@ Query setParameter(String name, Date value,
      * @throws IllegalArgumentException if position does not
      *         correspond to a positional parameter of the query or
      *         if the value argument is of incorrect type
+     * @deprecated Newly-written code should use the date/time types
+     *             defined in {@link java.time}.
      */
+    @Deprecated(since = "3.2")
     Query setParameter(int position, Calendar value,  
                        TemporalType temporalType);
 
@@ -321,7 +336,10 @@ Query setParameter(int position, Calendar value,
      * @throws IllegalArgumentException if position does not
      *         correspond to a positional parameter of the query or
      *         if the value argument is of incorrect type
+     * @deprecated Newly-written code should use the date/time types
+     *             defined in {@link java.time}.
      */
+    @Deprecated(since = "3.2")
     Query setParameter(int position, Date value,  
                        TemporalType temporalType);
 

diff --git a/api/src/main/java/jakarta/persistence/StoredProcedureQuery.java b/api/src/main/java/jakarta/persistence/StoredProcedureQuery.java
@@ -137,7 +137,10 @@ <T> StoredProcedureQuery setParameter(Parameter<T> param,
      * @return the same query instance
      * @throws IllegalArgumentException if the parameter does not
      *         correspond to a parameter of the query
+     * @deprecated Newly-written code should use the date/time types
+     *             defined in {@link java.time}.
      */
+    @Deprecated(since = "3.2")
     StoredProcedureQuery setParameter(Parameter<Calendar> param,
                                       Calendar value, 
                                       TemporalType temporalType);
@@ -150,9 +153,12 @@ StoredProcedureQuery setParameter(Parameter<Calendar> param,
      * @return the same query instance
      * @throws IllegalArgumentException if the parameter does not
      *         correspond to a parameter of the query
+     * @deprecated Newly-written code should use the date/time types
+     *             defined in {@link java.time}.
      */
-    StoredProcedureQuery setParameter(Parameter<Date> param, 
-                                      Date value, 
+    @Deprecated(since = "3.2")
+    StoredProcedureQuery setParameter(Parameter<Date> param,
+                                      Date value,
                                       TemporalType temporalType);
 
     /**
@@ -175,7 +181,10 @@ StoredProcedureQuery setParameter(Parameter<Date> param,
      * @throws IllegalArgumentException if the parameter name does 
      *         not correspond to a parameter of the query or if the
      *         value argument is of incorrect type
+     * @deprecated Newly-written code should use the date/time types
+     *             defined in {@link java.time}.
      */
+    @Deprecated(since = "3.2")
     StoredProcedureQuery setParameter(String name, 
                                       Calendar value, 
                                       TemporalType temporalType);
@@ -189,7 +198,10 @@ StoredProcedureQuery setParameter(String name,
      * @throws IllegalArgumentException if the parameter name does 
      *         not correspond to a parameter of the query or if the
      *         value argument is of incorrect type
+     * @deprecated Newly-written code should use the date/time types
+     *             defined in {@link java.time}.
      */
+    @Deprecated(since = "3.2")
     StoredProcedureQuery setParameter(String name, 
                                       Date value, 
                                       TemporalType temporalType);
@@ -215,7 +227,10 @@ StoredProcedureQuery setParameter(String name,
      * @throws IllegalArgumentException if position does not
      *         correspond to a positional parameter of the query or
      *         if the value argument is of incorrect type
+     * @deprecated Newly-written code should use the date/time types
+     *             defined in {@link java.time}.
      */
+    @Deprecated(since = "3.2")
     StoredProcedureQuery setParameter(int position, 
                                       Calendar value,  
                                       TemporalType temporalType);
@@ -229,7 +244,10 @@ StoredProcedureQuery setParameter(int position,
      * @throws IllegalArgumentException if position does not
      *         correspond to a positional parameter of the query or
      *         if the value argument is of incorrect type
+     * @deprecated Newly-written code should use the date/time types
+     *             defined in {@link java.time}.
      */
+    @Deprecated(since = "3.2")
     StoredProcedureQuery setParameter(int position, 
                                       Date value,  
                                       TemporalType temporalType);

diff --git a/api/src/main/java/jakarta/persistence/Temporal.java b/api/src/main/java/jakarta/persistence/Temporal.java
@@ -41,8 +41,12 @@
  * </pre>
  *
  * @since 1.0
+ *
+ * @deprecated Newly-written code should use the date/time types
+ *             defined in {@link java.time}.
  */
-@Target({METHOD, FIELD}) 
+@Deprecated(since = "3.2")
+@Target({METHOD, FIELD})
 @Retention(RUNTIME)
 public @interface Temporal {
 

diff --git a/api/src/main/java/jakarta/persistence/TemporalType.java b/api/src/main/java/jakarta/persistence/TemporalType.java
@@ -21,7 +21,11 @@
  * or <code>java.util.Calendar</code>.
  *
  * @since 1.0
+ *
+ * @deprecated Newly-written code should use the date/time types
+ *             defined in {@link java.time}.
  */
+@Deprecated(since = "3.2")
 public enum TemporalType {
 
     /** Map as <code>java.sql.Date</code> */

diff --git a/api/src/main/java/jakarta/persistence/TypedQuery.java b/api/src/main/java/jakarta/persistence/TypedQuery.java
@@ -187,7 +187,10 @@ default Stream<X> getResultStream() {
      * @return the same query instance
      * @throws IllegalArgumentException if the parameter does not
      *         correspond to a parameter of the query
+     * @deprecated Newly-written code should use the date/time types
+     *             defined in {@link java.time}.
      */
+    @Deprecated(since = "3.2")
     TypedQuery<X> setParameter(Parameter<Calendar> param, 
                                Calendar value,  
                                TemporalType temporalType);
@@ -200,7 +203,10 @@ TypedQuery<X> setParameter(Parameter<Calendar> param,
      * @return the same query instance
      * @throws IllegalArgumentException if the parameter does not
      *         correspond to a parameter of the query
+     * @deprecated Newly-written code should use the date/time types
+     *             defined in {@link java.time}.
      */
+    @Deprecated(since = "3.2")
     TypedQuery<X> setParameter(Parameter<Date> param, Date value,  
                                TemporalType temporalType);
 
@@ -224,7 +230,10 @@ TypedQuery<X> setParameter(Parameter<Date> param, Date value,
      * @throws IllegalArgumentException if the parameter name does
      *         not correspond to a parameter of the query or if 
      *         the value argument is of incorrect type
+     * @deprecated Newly-written code should use the date/time types
+     *             defined in {@link java.time}.
      */
+    @Deprecated(since = "3.2")
     TypedQuery<X> setParameter(String name, Calendar value, 
                                TemporalType temporalType);
 
@@ -237,7 +246,10 @@ TypedQuery<X> setParameter(String name, Calendar value,
      * @throws IllegalArgumentException if the parameter name does
      *         not correspond to a parameter of the query or if 
      *         the value argument is of incorrect type
+     * @deprecated Newly-written code should use the date/time types
+     *             defined in {@link java.time}.
      */
+    @Deprecated(since = "3.2")
     TypedQuery<X> setParameter(String name, Date value, 
                                TemporalType temporalType);
 
@@ -262,7 +274,10 @@ TypedQuery<X> setParameter(String name, Date value,
      * @throws IllegalArgumentException if position does not
      *         correspond to a positional parameter of the query
      *         or if the value argument is of incorrect type
+     * @deprecated Newly-written code should use the date/time types
+     *             defined in {@link java.time}.
      */
+    @Deprecated(since = "3.2")
     TypedQuery<X> setParameter(int position, Calendar value,  
                                TemporalType temporalType);
 
@@ -275,7 +290,10 @@ TypedQuery<X> setParameter(int position, Calendar value,
      * @throws IllegalArgumentException if position does not
      *         correspond to a positional parameter of the query
      *         or if the value argument is of incorrect type
+     * @deprecated Newly-written code should use the date/time types
+     *             defined in {@link java.time}.
      */
+    @Deprecated(since = "3.2")
     TypedQuery<X> setParameter(int position, Date value,  
                                TemporalType temporalType);
 

diff --git a/spec/src/main/asciidoc/ch11-metadata-for-or-mapping.adoc b/spec/src/main/asciidoc/ch11-metadata-for-or-mapping.adoc
@@ -3595,6 +3595,8 @@ public @interface MapKeyTemporal {
 }
 ----
 
+The _MapKeyTemporal_ enum is deprecated, and its use in newly-written code is strongly discouraged.
+
 <<a15593>> lists the annotation elements that
 may be specified for the _MapKeyTemporal_ annotation and their default
 values. The _TemporalType_ enum is defined in <<a16361>>.
@@ -5164,6 +5166,8 @@ public @interface Temporal {
 }
 ----
 
+The _Temporal_ annotation and _TemporalType_ enum are deprecated, and their use in newly-written code is strongly discouraged.
+
 <<a16378>> lists the annotation elements that may be specified
 for the _Temporal_ annotation and their default values.