From 2a78b257f38c3a941fdf5ce650219c94fe939444 Mon Sep 17 00:00:00 2001 From: Lukas Eder Date: Thu, 26 Sep 2024 10:01:34 +0200 Subject: [PATCH] [jOOQ/jOOQ#17376] Add a link to DSL::coerce from DSL::cast and Field::cast --- jOOQ/src/main/java/org/jooq/Field.java | 118 ++++++++---- jOOQ/src/main/java/org/jooq/impl/DSL.java | 225 ++++++++++++++++++---- 2 files changed, 275 insertions(+), 68 deletions(-) diff --git a/jOOQ/src/main/java/org/jooq/Field.java b/jOOQ/src/main/java/org/jooq/Field.java index 8520c8f004..36b575297d 100644 --- a/jOOQ/src/main/java/org/jooq/Field.java +++ b/jOOQ/src/main/java/org/jooq/Field.java @@ -318,8 +318,10 @@ extends /** * Cast this field to the type of another field. *

- * This results in the same as casting this field to - * {@link DataType#getCastTypeName()} + * Casting converts expressions between data types directly in SQL using SQL + * CAST expressions or similar. If you want to convert data + * types only in jOOQ without any effect on generated SQL, you can use + * {@link Field#coerce(Field)} instead. * * @param The generic type of the cast field * @param field The field whose type is used for the cast @@ -332,6 +334,11 @@ extends /** * Cast this field to a dialect-specific data type. + *

+ * Casting converts expressions between data types directly in SQL using SQL + * CAST expressions or similar. If you want to convert data + * types only in jOOQ without any effect on generated SQL, you can use + * {@link Field#coerce(DataType)} instead. * * @param The generic type of the cast field * @param type The data type that is used for the cast @@ -344,6 +351,11 @@ extends /** * Cast this field to another type. *

+ * Casting converts expressions between data types directly in SQL using SQL + * CAST expressions or similar. If you want to convert data + * types only in jOOQ without any effect on generated SQL, you can use + * {@link Field#coerce(Class)} instead. + *

* The actual cast may not be accurate as the {@link DataType} has to be * "guessed" from the jOOQ-configured data types. Use * {@link #cast(DataType)} for more accurate casts. @@ -371,24 +383,36 @@ extends /** * Coerce this field to the type of another field. *

- * Unlike with casting, coercing doesn't affect the way the database sees a - * Field's type. This is how coercing affects your SQL: - *

Bind values


-     * // This binds an int value to a JDBC PreparedStatement
-     * DSL.val(1).coerce(String.class);
+     * Unlike with {@link Field#cast(Field)}, coercing doesn't affect the
+     * way the database sees a Field's type. This is how coercing
+     * affects your SQL:
+     * 

+     * 
Bind values

+     *
+     * 
+     * 
+     * // This binds an int value to a JDBC PreparedStatement,
+     * // where a String is expected
+     * DSL.val(1).coerce(VARCHAR);
      *
      * // This binds an int value to a JDBC PreparedStatement
      * // and casts it to VARCHAR in SQL
-     * DSL.val(1).cast(String.class);
-     * 

-     * 
Other Field types
 

+     * DSL.val(1).cast(VARCHAR);
+     * 
+     * 

+     *
+     * 
Other Field types

+     *
+     * 
+     * 
      * // This fetches a String value for the BOOK.ID field from JDBC
-     * BOOK.ID.coerce(String.class);
+     * BOOK.ID.coerce(VARCHAR);
      *
      * // This fetches a String value for the BOOK.ID field from JDBC
      * // after casting it to VARCHAR in the database
-     * BOOK.ID.cast(String.class);
-     * 

+     * BOOK.ID.cast(VARCHAR);
+     * 
+     *
* * @param The generic type of the coerced field * @param field The field whose type is used for the coercion @@ -403,24 +427,36 @@ extends /** * Coerce this field to a dialect-specific data type. *

- * Unlike with casting, coercing doesn't affect the way the database sees a - * Field's type. This is how coercing affects your SQL: - *

Bind values


-     * // This binds an int value to a JDBC PreparedStatement
-     * DSL.val(1).coerce(String.class);
+     * Unlike with {@link Field#cast(DataType)}, coercing doesn't affect the
+     * way the database sees a Field's type. This is how coercing
+     * affects your SQL:
+     * 

+     * 
Bind values

+     *
+     * 
+     * 
+     * // This binds an int value to a JDBC PreparedStatement,
+     * // where a String is expected
+     * DSL.val(1).coerce(VARCHAR);
      *
      * // This binds an int value to a JDBC PreparedStatement
      * // and casts it to VARCHAR in SQL
-     * DSL.val(1).cast(String.class);
-     * 

-     * 
Other Field types
 

+     * DSL.val(1).cast(VARCHAR);
+     * 
+     * 

+     *
+     * 
Other Field types

+     *
+     * 
+     * 
      * // This fetches a String value for the BOOK.ID field from JDBC
-     * BOOK.ID.coerce(String.class);
+     * BOOK.ID.coerce(VARCHAR);
      *
      * // This fetches a String value for the BOOK.ID field from JDBC
      * // after casting it to VARCHAR in the database
-     * BOOK.ID.cast(String.class);
-     * 

+     * BOOK.ID.cast(VARCHAR);
+     * 
+     *
* * @param The generic type of the coerced field * @param type The data type that is used for the coercion @@ -434,24 +470,36 @@ extends /** * Coerce this field to another type. *

- * Unlike with casting, coercing doesn't affect the way the database sees a - * Field's type. This is how coercing affects your SQL: - *

Bind values


-     * // This binds an int value to a JDBC PreparedStatement
-     * DSL.val(1).coerce(String.class);
+     * Unlike with {@link Field#cast(Class)}, coercing doesn't affect the
+     * way the database sees a Field's type. This is how coercing
+     * affects your SQL:
+     * 

+     * 
Bind values

+     *
+     * 
+     * 
+     * // This binds an int value to a JDBC PreparedStatement,
+     * // where a String is expected
+     * DSL.val(1).coerce(VARCHAR);
      *
      * // This binds an int value to a JDBC PreparedStatement
      * // and casts it to VARCHAR in SQL
-     * DSL.val(1).cast(String.class);
-     * 

-     * 
Other Field types
 

+     * DSL.val(1).cast(VARCHAR);
+     * 
+     * 

+     *
+     * 
Other Field types

+     *
+     * 
+     * 
      * // This fetches a String value for the BOOK.ID field from JDBC
-     * BOOK.ID.coerce(String.class);
+     * BOOK.ID.coerce(VARCHAR);
      *
      * // This fetches a String value for the BOOK.ID field from JDBC
      * // after casting it to VARCHAR in the database
-     * BOOK.ID.cast(String.class);
-     * 

+     * BOOK.ID.cast(VARCHAR);
+     * 
+     *
*

* NOTE [#15286]: It is strongly recommended to pass only * {@link Class} references of types supported by jOOQ internally, i.e. diff --git a/jOOQ/src/main/java/org/jooq/impl/DSL.java b/jOOQ/src/main/java/org/jooq/impl/DSL.java index 0d59eec602..a01d33fe8a 100644 --- a/jOOQ/src/main/java/org/jooq/impl/DSL.java +++ b/jOOQ/src/main/java/org/jooq/impl/DSL.java @@ -17743,6 +17743,37 @@ public class DSL { /** * Coerce this field to the type of another field. + *

+ * Unlike with {@link DSL#cast(Object, Field)}, coercing doesn't affect the + * way the database sees a Field's type. This is how coercing + * affects your SQL: + *

+ *

Bind values

+ * + * 
+     * 
+     * // This binds an int value to a JDBC PreparedStatement,
+     * // where a String is expected
+     * DSL.val(1).coerce(VARCHAR);
+     *
+     * // This binds an int value to a JDBC PreparedStatement
+     * // and casts it to VARCHAR in SQL
+     * DSL.val(1).cast(VARCHAR);
+     * 
+     *
+ * + *

Other Field types

+ * + * 
+     * 
+     * // This fetches a String value for the BOOK.ID field from JDBC
+     * BOOK.ID.coerce(VARCHAR);
+     *
+     * // This fetches a String value for the BOOK.ID field from JDBC
+     * // after casting it to VARCHAR in the database
+     * BOOK.ID.cast(VARCHAR);
+     * 
+     *
* * @see #coerce(Field, Field) */ @@ -17755,6 +17786,37 @@ public class DSL { /** * Coerce this field to another type. *

+ * Unlike with {@link DSL#cast(Object, Class)}, coercing doesn't affect the + * way the database sees a Field's type. This is how coercing + * affects your SQL: + *

+ *

Bind values

+ * + * 
+     * 
+     * // This binds an int value to a JDBC PreparedStatement,
+     * // where a String is expected
+     * DSL.val(1).coerce(VARCHAR);
+     *
+     * // This binds an int value to a JDBC PreparedStatement
+     * // and casts it to VARCHAR in SQL
+     * DSL.val(1).cast(VARCHAR);
+     * 
+     *
+ * + *

Other Field types

+ * + * 
+     * 
+     * // This fetches a String value for the BOOK.ID field from JDBC
+     * BOOK.ID.coerce(VARCHAR);
+     *
+     * // This fetches a String value for the BOOK.ID field from JDBC
+     * // after casting it to VARCHAR in the database
+     * BOOK.ID.cast(VARCHAR);
+     * 
+     *
+ *

* NOTE [#15286]: It is strongly recommended to pass only * {@link Class} references of types supported by jOOQ internally, i.e. * types from {@link SQLDataType}. If you're using any custom data types by @@ -17775,6 +17837,37 @@ public class DSL { /** * Coerce a field to another type. + *

+ * Unlike with {@link DSL#cast(Object, DataType)}, coercing doesn't affect the + * way the database sees a Field's type. This is how coercing + * affects your SQL: + *

+ *

Bind values

+ * + * 
+     * 
+     * // This binds an int value to a JDBC PreparedStatement,
+     * // where a String is expected
+     * DSL.val(1).coerce(VARCHAR);
+     *
+     * // This binds an int value to a JDBC PreparedStatement
+     * // and casts it to VARCHAR in SQL
+     * DSL.val(1).cast(VARCHAR);
+     * 
+     *
+ * + *

Other Field types

+ * + * 
+     * 
+     * // This fetches a String value for the BOOK.ID field from JDBC
+     * BOOK.ID.coerce(VARCHAR);
+     *
+     * // This fetches a String value for the BOOK.ID field from JDBC
+     * // after casting it to VARCHAR in the database
+     * BOOK.ID.cast(VARCHAR);
+     * 
+     *
* * @see #coerce(Field, DataType) */ @@ -17787,24 +17880,36 @@ public class DSL { /** * Coerce this field to the type of another field. *

- * Unlike with casting, coercing doesn't affect the way the database sees a - * Field's type. This is how coercing affects your SQL: - *

Bind values


-     * // This binds an int value to a JDBC PreparedStatement
-     * DSL.val(1).coerce(String.class);
+     * Unlike with {@link DSL#cast(Field, Field)}, coercing doesn't affect the
+     * way the database sees a Field's type. This is how coercing
+     * affects your SQL:
+     * 

+     * 
Bind values

+     *
+     * 
+     * 
+     * // This binds an int value to a JDBC PreparedStatement,
+     * // where a String is expected
+     * DSL.val(1).coerce(VARCHAR);
      *
      * // This binds an int value to a JDBC PreparedStatement
      * // and casts it to VARCHAR in SQL
-     * DSL.val(1).cast(String.class);
-     * 

-     * 
Other Field types
 

+     * DSL.val(1).cast(VARCHAR);
+     * 
+     * 

+     *
+     * 
Other Field types

+     *
+     * 
+     * 
      * // This fetches a String value for the BOOK.ID field from JDBC
-     * BOOK.ID.coerce(String.class);
+     * BOOK.ID.coerce(VARCHAR);
      *
      * // This fetches a String value for the BOOK.ID field from JDBC
      * // after casting it to VARCHAR in the database
-     * BOOK.ID.cast(String.class);
-     * 

+     * BOOK.ID.cast(VARCHAR);
+     * 
+     *
* * @param The generic type of the coerced field * @param field The field to be coerced @@ -17822,24 +17927,36 @@ public class DSL { /** * Coerce this field to another type. *

- * Unlike with casting, coercing doesn't affect the way the database sees a - * Field's type. This is how coercing affects your SQL: - *

Bind values


-     * // This binds an int value to a JDBC PreparedStatement
-     * DSL.val(1).coerce(String.class);
+     * Unlike with {@link DSL#cast(Field, Class)}, coercing doesn't affect the
+     * way the database sees a Field's type. This is how coercing
+     * affects your SQL:
+     * 

+     * 
Bind values

+     *
+     * 
+     * 
+     * // This binds an int value to a JDBC PreparedStatement,
+     * // where a String is expected
+     * DSL.val(1).coerce(VARCHAR);
      *
      * // This binds an int value to a JDBC PreparedStatement
      * // and casts it to VARCHAR in SQL
-     * DSL.val(1).cast(String.class);
-     * 

-     * 
Other Field types
 

+     * DSL.val(1).cast(VARCHAR);
+     * 
+     * 

+     *
+     * 
Other Field types

+     *
+     * 
+     * 
      * // This fetches a String value for the BOOK.ID field from JDBC
-     * BOOK.ID.coerce(String.class);
+     * BOOK.ID.coerce(VARCHAR);
      *
      * // This fetches a String value for the BOOK.ID field from JDBC
      * // after casting it to VARCHAR in the database
-     * BOOK.ID.cast(String.class);
-     * 

+     * BOOK.ID.cast(VARCHAR);
+     * 
+     *
*

* NOTE [#15286]: It is strongly recommended to pass only * {@link Class} references of types supported by jOOQ internally, i.e. @@ -17865,24 +17982,36 @@ public class DSL { /** * Coerce a field to another type. *

- * Unlike with casting, coercing doesn't affect the way the database sees a - * Field's type. This is how coercing affects your SQL: - *

Bind values


-     * // This binds an int value to a JDBC PreparedStatement
-     * DSL.val(1).coerce(String.class);
+     * Unlike with {@link DSL#cast(Field, DataType)}, coercing doesn't affect the
+     * way the database sees a Field's type. This is how coercing
+     * affects your SQL:
+     * 

+     * 
Bind values

+     *
+     * 
+     * 
+     * // This binds an int value to a JDBC PreparedStatement,
+     * // where a String is expected
+     * DSL.val(1).coerce(VARCHAR);
      *
      * // This binds an int value to a JDBC PreparedStatement
      * // and casts it to VARCHAR in SQL
-     * DSL.val(1).cast(String.class);
-     * 

-     * 
Other Field types
 

+     * DSL.val(1).cast(VARCHAR);
+     * 
+     * 

+     *
+     * 
Other Field types

+     *
+     * 
+     * 
      * // This fetches a String value for the BOOK.ID field from JDBC
-     * BOOK.ID.coerce(String.class);
+     * BOOK.ID.coerce(VARCHAR);
      *
      * // This fetches a String value for the BOOK.ID field from JDBC
      * // after casting it to VARCHAR in the database
-     * BOOK.ID.cast(String.class);
-     * 

+     * BOOK.ID.cast(VARCHAR);
+     * 
+     *
* * @param The generic type of the coerced field * @param field The field to be coerced @@ -17937,6 +18066,11 @@ public class DSL { /** * Cast a value to the type of another field. + *

+ * Casting converts expressions between data types directly in SQL using SQL + * CAST expressions or similar. If you want to convert data + * types only in jOOQ without any effect on generated SQL, you can use + * {@link DSL#coerce(Object, Field)} instead. * * @param The generic type of the cast field * @param value The value to cast @@ -17951,6 +18085,11 @@ public class DSL { /** * Cast a field to the type of another field. + *

+ * Casting converts expressions between data types directly in SQL using SQL + * CAST expressions or similar. If you want to convert data + * types only in jOOQ without any effect on generated SQL, you can use + * {@link DSL#coerce(Field, Field)} instead. * * @param The generic type of the cast field * @param field The field to cast @@ -17979,6 +18118,11 @@ public class DSL { /** * Cast a value to another type. *

+ * Casting converts expressions between data types directly in SQL using SQL + * CAST expressions or similar. If you want to convert data + * types only in jOOQ without any effect on generated SQL, you can use + * {@link DSL#coerce(Object, Class)} instead. + *

* NOTE [#15286]: It is strongly recommended to pass only * {@link Class} references of types supported by jOOQ internally, i.e. * types from {@link SQLDataType}. If you're using any custom data types by @@ -18001,6 +18145,11 @@ public class DSL { /** * Cast a field to another type. *

+ * Casting converts expressions between data types directly in SQL using SQL + * CAST expressions or similar. If you want to convert data + * types only in jOOQ without any effect on generated SQL, you can use + * {@link DSL#coerce(Field, Class)} instead. + *

* NOTE [#15286]: It is strongly recommended to pass only * {@link Class} references of types supported by jOOQ internally, i.e. * types from {@link SQLDataType}. If you're using any custom data types by @@ -18035,6 +18184,11 @@ public class DSL { /** * Cast a value to another type. + *

+ * Casting converts expressions between data types directly in SQL using SQL + * CAST expressions or similar. If you want to convert data + * types only in jOOQ without any effect on generated SQL, you can use + * {@link DSL#coerce(Object, DataType)} instead. * * @param The generic type of the cast field * @param value The value to cast @@ -18049,6 +18203,11 @@ public class DSL { /** * Cast a field to another type. + *

+ * Casting converts expressions between data types directly in SQL using SQL + * CAST expressions or similar. If you want to convert data + * types only in jOOQ without any effect on generated SQL, you can use + * {@link DSL#coerce(Field, DataType)} instead. * * @param The generic type of the cast field * @param field The value to cast