add CAST() function to JPQL + Expression.cast() method

api/src/main/java/jakarta/persistence/criteria/Expression.java

@@ -11,6 +11,7 @@
  */
 
 // Contributors:
+//     Gavin King      - 3.2
 //     Linda DeMichiel - 2.1
 //     Linda DeMichiel - 2.0
 
@@ -76,11 +77,29 @@ public interface Expression<T> extends Selection<T> {
     /**
      * Perform a typecast upon the expression, returning a new
      * expression object.
-     * This method does not cause type conversion:
-     * the runtime type is not changed.
-     * Warning: may result in a runtime failure.
+     * Unlike {@link #cast(Class)}, this method does not cause
+     * type conversion: the runtime type is not changed.
+     * <p><em>Warning: may result in a runtime failure.</em>
      * @param type  intended type of the expression
      * @return new expression of the given type
+     * @see #cast(Class)
      */
     <X> Expression<X> as(Class<X> type);
+
+    /**
+     * Cast this expression to the specified type, returning a
+     * new expression object.
+     * Unlike {@link #as(Class)}, this method <em>does</em>
+     * result in a runtime type conversion.
+     * <p><em>Providers are required to support casting
+     * scalar expressions to {@link String}, and
+     * {@code String} expressions to {@link Integer},
+     * {@link Long}, {@link Float}, and {@link Double}.
+     * Support for typecasts between other basic types is
+     * not required.</em>
+     * @param type  a basic type
+     * @return a scalar expression of the given basic type
+     * @since 3.2
+     */
+    <X> Expression<X> cast(Class<X> type);
 }

spec/src/main/asciidoc/ch04-query-language.adoc

@@ -1870,6 +1870,34 @@ part to EXTRACT.
 FROM Course c WHERE c.year = EXTRACT(YEAR FROM LOCAL DATE)
 ----
 
+===== Typecasts
+
+The CAST function converts an expression of one type to an expression
+of a different type.
+
+----
+string_cast_function::=
+    CAST(scalar_expression AS STRING)
+arithmetic_cast_function::=
+    CAST(string_expression AS {INTEGER | LONG | FLOAT | DOUBLE})
+----
+
+The persistence provider is required to accept typecasts of the following
+forms:
+
+- any scalar expression to STRING
+- any string expression to INTEGER, LONG, FLOAT, or DOUBLE
+
+Typecast expressions are evaluated by the database, with semantics that
+vary somewhat between different databases.
+
+When a typecast occurs as a select expression, the result type of the
+select expression is:
+
+- _java.lang.String_ for a cast to STRING
+- _java.lang.Integer_, _java.lang.Long_, _java.lang.Float_, or _java.lang.Double_
+  for a cast to INTEGER, LONG, FLOAT, or DOUBLE, respectively
+
 ===== Invocation of Predefined and User-defined Database Functions [[a5311]]
 
 The invocation of functions other than the
@@ -3081,6 +3109,7 @@ arithmetic_primary ::=
     aggregate_expression |
     case_expression |
     function_invocation |
+    arithmetic_cast_function |
     (subquery)
 string_expression ::=
     state_valued_path_expression |
@@ -3090,7 +3119,8 @@ string_expression ::=
     aggregate_expression |
     case_expression |
     function_invocation |
-    string_expression || string_expression
+    string_cast_function |
+    string_expression || string_expression |
     (subquery)
 datetime_expression ::=
     state_valued_path_expression |
@@ -3124,6 +3154,8 @@ type_discriminator ::=
     TYPE(general_identification_variable |
         single_valued_object_path_expression |
         input_parameter)
+arithmetic_cast_function::=
+    CAST(string_expression AS {INTEGER | LONG | FLOAT | DOUBLE})
 functions_returning_numerics ::=
     LENGTH(string_expression) |
     LOCATE(string_expression, string_expression[, arithmetic_expression]) |
@@ -3148,6 +3180,8 @@ functions_returning_datetime ::=
     LOCAL TIME |
     LOCAL DATETIME |
     extract_datetime_part
+string_cast_function::=
+    CAST(scalar_expression AS STRING)
 functions_returning_strings ::=
     CONCAT(string_expression, string_expression{, string_expression}*) |
     SUBSTRING(string_expression, arithmetic_expression[, arithmetic_expression]) |