From 5604d11903496a358b427fa32da9f842cdd5998f Mon Sep 17 00:00:00 2001 From: Gavin King Date: Fri, 11 Aug 2023 09:42:11 +0200 Subject: [PATCH] deprecate APIs involving java.util.Date and friends note that we're not making these for removal see #402 --- .../jakarta/persistence/MapKeyTemporal.java | 4 ++++ .../main/java/jakarta/persistence/Query.java | 18 +++++++++++++++ .../persistence/StoredProcedureQuery.java | 22 +++++++++++++++++-- .../java/jakarta/persistence/Temporal.java | 6 ++++- .../jakarta/persistence/TemporalType.java | 4 ++++ .../java/jakarta/persistence/TypedQuery.java | 18 +++++++++++++++ .../ch11-metadata-for-or-mapping.adoc | 4 ++++ 7 files changed, 73 insertions(+), 3 deletions(-) diff --git a/api/src/main/java/jakarta/persistence/MapKeyTemporal.java b/api/src/main/java/jakarta/persistence/MapKeyTemporal.java index a2eb30d2..a3d1c209 100644 --- a/api/src/main/java/jakarta/persistence/MapKeyTemporal.java +++ b/api/src/main/java/jakarta/persistence/MapKeyTemporal.java @@ -42,7 +42,11 @@ * * * @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 index dac3d2ad..0910e6e8 100644 --- 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 param, Calendar value, TemporalType temporalType); @@ -246,7 +249,10 @@ Query setParameter(Parameter 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 param, Date value, TemporalType temporalType); @@ -270,7 +276,10 @@ Query setParameter(Parameter 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 index ad27a912..b77a5af3 100644 --- a/api/src/main/java/jakarta/persistence/StoredProcedureQuery.java +++ b/api/src/main/java/jakarta/persistence/StoredProcedureQuery.java @@ -137,7 +137,10 @@ StoredProcedureQuery setParameter(Parameter 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 param, Calendar value, TemporalType temporalType); @@ -150,9 +153,12 @@ StoredProcedureQuery setParameter(Parameter 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 param, - Date value, + @Deprecated(since = "3.2") + StoredProcedureQuery setParameter(Parameter param, + Date value, TemporalType temporalType); /** @@ -175,7 +181,10 @@ StoredProcedureQuery setParameter(Parameter 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 index ba8b5328..606aa9f1 100644 --- a/api/src/main/java/jakarta/persistence/Temporal.java +++ b/api/src/main/java/jakarta/persistence/Temporal.java @@ -41,8 +41,12 @@ * * * @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 index a4565f0f..ec45cd79 100644 --- a/api/src/main/java/jakarta/persistence/TemporalType.java +++ b/api/src/main/java/jakarta/persistence/TemporalType.java @@ -21,7 +21,11 @@ * or java.util.Calendar. * * @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 java.sql.Date */ diff --git a/api/src/main/java/jakarta/persistence/TypedQuery.java b/api/src/main/java/jakarta/persistence/TypedQuery.java index 18596b83..e759c7df 100644 --- a/api/src/main/java/jakarta/persistence/TypedQuery.java +++ b/api/src/main/java/jakarta/persistence/TypedQuery.java @@ -187,7 +187,10 @@ default Stream 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 setParameter(Parameter param, Calendar value, TemporalType temporalType); @@ -200,7 +203,10 @@ TypedQuery setParameter(Parameter 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 setParameter(Parameter param, Date value, TemporalType temporalType); @@ -224,7 +230,10 @@ TypedQuery setParameter(Parameter 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 setParameter(String name, Calendar value, TemporalType temporalType); @@ -237,7 +246,10 @@ TypedQuery 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 setParameter(String name, Date value, TemporalType temporalType); @@ -262,7 +274,10 @@ TypedQuery 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 setParameter(int position, Calendar value, TemporalType temporalType); @@ -275,7 +290,10 @@ TypedQuery 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 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 index a3aad1eb..926942f4 100644 --- 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. + <> lists the annotation elements that may be specified for the _MapKeyTemporal_ annotation and their default values. The _TemporalType_ enum is defined in <>. @@ -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. + <> lists the annotation elements that may be specified for the _Temporal_ annotation and their default values.