From 981c54370b16deca27f08416da4543555790a533 Mon Sep 17 00:00:00 2001 From: Lukas Eder Date: Tue, 27 Jun 2023 09:23:32 +0200 Subject: [PATCH] [jOOQ/jOOQ#15286] Add Javadoc to discourage using any m(Class) method if there's an m(DataType) overload --- jOOQ/src/main/java/org/jooq/Field.java | 15 ++ jOOQ/src/main/java/org/jooq/impl/DSL.java | 279 +++++++++++++++++++++- 2 files changed, 283 insertions(+), 11 deletions(-) diff --git a/jOOQ/src/main/java/org/jooq/Field.java b/jOOQ/src/main/java/org/jooq/Field.java index 0f1000cc25..3ba4246a7f 100644 --- a/jOOQ/src/main/java/org/jooq/Field.java +++ b/jOOQ/src/main/java/org/jooq/Field.java @@ -84,6 +84,7 @@ import java.util.function.Function; import org.jooq.conf.Settings; import org.jooq.impl.DSL; +import org.jooq.impl.SQLDataType; import org.jooq.types.Interval; // ... @@ -345,6 +346,13 @@ extends * 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. + *

+ * NOTE [#15268]: 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 + * means of a {@link Converter} or {@link Binding}, it's better to pass that + * converted {@link DataType} reference explicitly to + * {@link #cast(DataType)}. * * @param The generic type of the cast field * @param type The type that is used for the cast @@ -443,6 +451,13 @@ extends * // after casting it to VARCHAR in the database * BOOK.ID.cast(String.class); * + *

+ * NOTE [#15268]: 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 + * means of a {@link Converter} or {@link Binding}, it's better to pass that + * converted {@link DataType} reference explicitly to + * {@link #coerce(DataType)}. * * @param The generic type of the coerced field * @param type The type that is used for the coercion diff --git a/jOOQ/src/main/java/org/jooq/impl/DSL.java b/jOOQ/src/main/java/org/jooq/impl/DSL.java index 4374161650..d8f03fd1ba 100644 --- a/jOOQ/src/main/java/org/jooq/impl/DSL.java +++ b/jOOQ/src/main/java/org/jooq/impl/DSL.java @@ -164,6 +164,7 @@ import org.jooq.ArrayAggOrderByStep; // ... // ... import org.jooq.Asterisk; +import org.jooq.Binding; import org.jooq.Block; import org.jooq.Case; import org.jooq.CaseConditionStep; @@ -204,6 +205,7 @@ import org.jooq.ConstraintForeignKeyReferencesStep9; import org.jooq.ConstraintForeignKeyReferencesStepN; import org.jooq.ConstraintTypeStep; // ... +import org.jooq.Converter; import org.jooq.CreateTypeStep; import org.jooq.CreateViewAsStep; import org.jooq.DSLContext; @@ -12208,6 +12210,13 @@ public class DSL { * UPDATE, or MERGE statements. *

* This is an alias for {@link #default_(Class)}. + *

+ * NOTE [#15268]: 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 means of a + * {@link Converter} or {@link Binding}, it's better to pass that converted + * {@link DataType} reference explicitly to + * {@link #defaultValue(DataType)}. * * @see #default_(Class) */ @@ -12263,6 +12272,13 @@ public class DSL { /** * Create a DEFAULT keyword for use with INSERT, * UPDATE, or MERGE statements. + *

+ * NOTE [#15268]: 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 + * means of a {@link Converter} or {@link Binding}, it's better to pass that + * converted {@link DataType} reference explicitly to + * {@link #default_(DataType)}. */ @NotNull @Support({ CUBRID, DERBY, FIREBIRD, H2, HSQLDB, MARIADB, MYSQL, POSTGRES }) @@ -12358,6 +12374,12 @@ public class DSL { * In clauses that project fields to a given {@link Record} type, the * {@link #noField()} simply projects NULL and cannot be used * to avoid the clause. + *

+ * NOTE [#15268]: 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 means of a + * {@link Converter} or {@link Binding}, it's better to pass that converted + * {@link DataType} reference explicitly to {@link #noField(DataType)}. * * @param type A class to derive the {@link Field#getDataType()} from. */ @@ -12531,13 +12553,24 @@ public class DSL { *

* This constructs a sequence reference given the sequence's qualified name. *

- * Example: 


+     * Example:
+     *
+     * 
+     * 
      * // This sequence...
      * sequence(name("MY_SCHEMA", "MY_SEQUENCE"));
      *
      * // ... will render this SQL by default, using the SQL Server dialect
      * [MY_SCHEMA].[MY_SEQUENCE]
-     * 

+     * 
+     *
+ *

+ * NOTE [#15268]: 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 means of a + * {@link Converter} or {@link Binding}, it's better to pass that converted + * {@link DataType} reference explicitly to + * {@link #sequence(Name, DataType)}. * * @param name The sequence name * @param type The sequence type (a type that is supported by @@ -12674,22 +12707,37 @@ public class DSL { *

* This constructs a field reference given the field's qualified name. jOOQ *

- * Example: 


+     * Example:
+     *
+     * 
+     * 
      * // This field...
      * field(name("MY_SCHEMA", "MY_TABLE", "MY_FIELD"));
      *
      * // ... will render this SQL by default, using the SQL Server dialect
      * [MY_SCHEMA].[MY_TABLE].[MY_FIELD]
-     * 

+     * 
+     *
*

- * Another example: 


+     * Another example:
+     *
+     * 
+     * 
      * create.select(field("length({1})", Integer.class, field(name("TITLE"))))
      *       .from(table(name("T_BOOK")))
      *       .fetch();
      *
      * // ... will execute this SQL on SQL Server:
      * select length([TITLE]) from [T_BOOK]
-     * 

+     * 
+     *
+ *

+ * NOTE [#15268]: 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 means of a + * {@link Converter} or {@link Binding}, it's better to pass that converted + * {@link DataType} reference explicitly to + * {@link #field(Name, DataType)}. * * @param name The field name * @param type The field type (a type that is supported by @@ -12820,6 +12868,19 @@ public class DSL { + + + + + + + + + + + + + @@ -14006,13 +14067,21 @@ public class DSL { * guarantee syntax integrity. You may also create the possibility of * malicious SQL injection. Be sure to properly use bind variables and/or * escape literals when concatenated into SQL clauses! + *

+ * NOTE [#15268]: 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 means of a + * {@link Converter} or {@link Binding}, it's better to pass that converted + * {@link DataType} reference explicitly to + * {@link #sequence(String, DataType)}. * * @param sql The sequence name * @param type The sequence type (a type that is supported by * {@link SQLDataType}) * @return A field wrapping the plain SQL * @see SQL - * @deprecated - 3.10 - [#6162] - Use {@link #sequence(Name, Class)} instead. + * @deprecated - 3.10 - [#6162] - Use {@link #sequence(Name, Class)} + * instead. */ @Deprecated(forRemoval = true, since = "3.10") @NotNull @@ -14048,6 +14117,13 @@ public class DSL { /** * Create the VALUE pseudo field for usage with * DOMAIN specifications. + *

+ * NOTE [#15268]: 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 means of a + * {@link Converter} or {@link Binding}, it's better to pass that converted + * {@link DataType} reference explicitly to + * {@link #value(DataType)}. */ @NotNull @Support({ FIREBIRD, H2, HSQLDB, POSTGRES, YUGABYTEDB }) @@ -14085,6 +14161,13 @@ public class DSL { /** * Create a DOMAIN reference. + *

+ * NOTE [#15268]: 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 means of a + * {@link Converter} or {@link Binding}, it's better to pass that converted + * {@link DataType} reference explicitly to + * {@link #domain(String, DataType)}. */ @NotNull @Support({ FIREBIRD, H2, HSQLDB, POSTGRES, YUGABYTEDB }) @@ -14094,6 +14177,13 @@ public class DSL { /** * Create a DOMAIN reference. + *

+ * NOTE [#15268]: 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 means of a + * {@link Converter} or {@link Binding}, it's better to pass that converted + * {@link DataType} reference explicitly to + * {@link #domain(Name, DataType)}. */ @NotNull @Support({ FIREBIRD, H2, HSQLDB, POSTGRES, YUGABYTEDB }) @@ -14282,14 +14372,24 @@ public class DSL { *

* Example: *

- * 


+     *
+     * 
+     * 
      * String sql = "DECODE(MY_FIELD, 1, 100, 200)";
-     * 

+     * 
+     *
*

* NOTE: When inserting plain SQL into jOOQ objects, you must * guarantee syntax integrity. You may also create the possibility of * malicious SQL injection. Be sure to properly use bind variables and/or * escape literals when concatenated into SQL clauses! + *

+ * NOTE [#15268]: 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 means of a + * {@link Converter} or {@link Binding}, it's better to pass that converted + * {@link DataType} reference explicitly to + * {@link #field(SQL, DataType)}. * * @param sql The SQL * @param type The field type (a type that is supported by @@ -14314,14 +14414,24 @@ public class DSL { *

* Example: *

- * 


+     *
+     * 
+     * 
      * String sql = "DECODE(MY_FIELD, 1, 100, 200)";
-     * 

+     * 
+     *
*

* NOTE: When inserting plain SQL into jOOQ objects, you must * guarantee syntax integrity. You may also create the possibility of * malicious SQL injection. Be sure to properly use bind variables and/or * escape literals when concatenated into SQL clauses! + *

+ * NOTE [#15268]: 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 + * means of a {@link Converter} or {@link Binding}, it's better to pass that + * converted {@link DataType} reference explicitly to + * {@link #field(String, DataType)}. * * @param sql The SQL * @param type The field type (a type that is supported by @@ -14354,6 +14464,13 @@ public class DSL { * guarantee syntax integrity. You may also create the possibility of * malicious SQL injection. Be sure to properly use bind variables and/or * escape literals when concatenated into SQL clauses! + *

+ * NOTE [#15268]: 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 + * means of a {@link Converter} or {@link Binding}, it's better to pass that + * converted {@link DataType} reference explicitly to + * {@link #field(String, DataType, Object...)}. * * @param sql The SQL * @param type The field type (a type that is supported by @@ -14587,6 +14704,13 @@ public class DSL { * malicious SQL injection. Be sure to properly use bind variables and/or * escape literals when concatenated into SQL clauses! One way to escape * literals is to use {@link #name(String...)} and similar methods + *

+ * NOTE [#15268]: 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 + * means of a {@link Converter} or {@link Binding}, it's better to pass that + * converted {@link DataType} reference explicitly to + * {@link #field(String, DataType, QueryPart...)}. * * @param sql The SQL clause, containing {numbered placeholders} where query * parts can be injected @@ -14613,6 +14737,13 @@ public class DSL { * guarantee syntax integrity. You may also create the possibility of * malicious SQL injection. Be sure to properly use bind variables and/or * escape literals when concatenated into SQL clauses! + *

+ * NOTE [#15268]: 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 + * means of a {@link Converter} or {@link Binding}, it's better to pass that + * converted {@link DataType} reference explicitly to + * {@link #function(String, DataType, Field...)}. * * @param name The function name (without parentheses) * @param type The function return type (a type that is supported by @@ -14651,6 +14782,13 @@ public class DSL { /** * function() can be used to access native or user-defined * functions that are not yet or insufficiently supported by jOOQ. + *

+ * NOTE [#15268]: 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 + * means of a {@link Converter} or {@link Binding}, it's better to pass that + * converted {@link DataType} reference explicitly to + * {@link #function(Name, DataType, Field...)}. * * @param name The function name (possibly qualified) * @param type The function return type (a type that is supported by @@ -14699,6 +14837,13 @@ public class DSL { * guarantee syntax integrity. You may also create the possibility of * malicious SQL injection. Be sure to properly use bind variables and/or * escape literals when concatenated into SQL clauses! + *

+ * NOTE [#15268]: 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 + * means of a {@link Converter} or {@link Binding}, it's better to pass that + * converted {@link DataType} reference explicitly to + * {@link #aggregate(String, DataType, Field...)}. * * @param name The aggregate function name (possibly qualified) * @param type The aggregate function return type (a type that is supported @@ -14738,6 +14883,13 @@ public class DSL { /** * aggregate() can be used to access native or user-defined * aggregate functions that are not yet or insufficiently supported by jOOQ. + *

+ * NOTE [#15268]: 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 + * means of a {@link Converter} or {@link Binding}, it's better to pass that + * converted {@link DataType} reference explicitly to + * {@link #aggregate(Name, DataType, Field...)}. * * @param name The aggregate function name (possibly qualified) * @param type The aggregate function return type (a type that is supported @@ -14774,6 +14926,13 @@ public class DSL { * guarantee syntax integrity. You may also create the possibility of * malicious SQL injection. Be sure to properly use bind variables and/or * escape literals when concatenated into SQL clauses! + *

+ * NOTE [#15268]: 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 + * means of a {@link Converter} or {@link Binding}, it's better to pass that + * converted {@link DataType} reference explicitly to + * {@link #aggregateDistinct(String, DataType, Field...)}. * * @param name The aggregate function name (possibly qualified) * @param type The aggregate function return type (a type that is supported @@ -14814,6 +14973,13 @@ public class DSL { * aggregateDistinct() can be used to access native or * user-defined aggregate functions that are not yet or insufficiently * supported by jOOQ. + *

+ * NOTE [#15268]: 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 + * means of a {@link Converter} or {@link Binding}, it's better to pass that + * converted {@link DataType} reference explicitly to + * {@link #aggregateDistinct(Name, DataType, Field...)}. * * @param name The aggregate function name (possibly qualified) * @param type The aggregate function return type (a type that is supported @@ -15886,6 +16052,13 @@ public class DSL { /** * Coerce this field to another type. + *

+ * NOTE [#15268]: 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 + * means of a {@link Converter} or {@link Binding}, it's better to pass that + * converted {@link DataType} reference explicitly to + * {@link #coerce(Object, DataType)}. * * @param value The value to be coerced * @param as The field type (a type that is supported by @@ -15965,6 +16138,13 @@ public class DSL { * // after casting it to VARCHAR in the database * BOOK.ID.cast(String.class); * + *

+ * NOTE [#15268]: 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 + * means of a {@link Converter} or {@link Binding}, it's better to pass that + * converted {@link DataType} reference explicitly to + * {@link #coerce(Field, DataType)}. * * @param The generic type of the coerced field * @param value The value to be coerced @@ -16096,6 +16276,13 @@ public class DSL { /** * Cast a value to another type. + *

+ * NOTE [#15268]: 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 + * means of a {@link Converter} or {@link Binding}, it's better to pass that + * converted {@link DataType} reference explicitly to + * {@link #cast(Object, DataType)}. * * @param The generic type of the cast field * @param value The value to cast @@ -16111,6 +16298,13 @@ public class DSL { /** * Cast a field to another type. + *

+ * NOTE [#15268]: 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 + * means of a {@link Converter} or {@link Binding}, it's better to pass that + * converted {@link DataType} reference explicitly to + * {@link #cast(Field, DataType)}. * * @param The generic type of the cast field * @param field The field to cast @@ -16167,6 +16361,13 @@ public class DSL { /** * Cast null to a type. + *

+ * NOTE [#15268]: 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 + * means of a {@link Converter} or {@link Binding}, it's better to pass that + * converted {@link DataType} reference explicitly to + * {@link #castNull(DataType)}. * * @param The generic type of the cast field * @param type The type that is used for the cast @@ -29244,6 +29445,20 @@ public class DSL { + + + + + + + + + + + + + + @@ -30171,6 +30386,13 @@ public class DSL { /** * Create an unnamed parameter with a defined type and no initial value. + *

+ * NOTE [#15268]: 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 + * means of a {@link Converter} or {@link Binding}, it's better to pass that + * converted {@link DataType} reference explicitly to + * {@link #param(DataType)}. * * @see #param(String, Object) */ @@ -30230,6 +30452,13 @@ public class DSL { /** * Create a named parameter with a defined type and no initial value. + *

+ * NOTE [#15268]: 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 + * means of a {@link Converter} or {@link Binding}, it's better to pass that + * converted {@link DataType} reference explicitly to + * {@link #param(String, DataType)}. * * @param name The parameter name * @param type The type that is used for the parameter (a type that is @@ -30751,6 +30980,13 @@ public class DSL { /** * A synonym for {@link #val(Object, Class)} to be used in Scala and Groovy, * where val is a reserved keyword. + *

+ * NOTE [#15268]: 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 + * means of a {@link Converter} or {@link Binding}, it's better to pass that + * converted {@link DataType} reference explicitly to + * {@link #value(Object, DataType)}. * * @param value The bind value * @param type The type that is used for the bind value (a type that is @@ -31727,6 +31963,13 @@ public class DSL { *

  • inline("abc'def") renders 'abc''def'
    • *
  • field("abc'def") renders abc'def
    • * + *

    + * NOTE [#15268]: 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 + * means of a {@link Converter} or {@link Binding}, it's better to pass that + * converted {@link DataType} reference explicitly to + * {@link #inline(Object, DataType)}. * * @param value The inline value * @param type The data type to enforce upon the value (a type that is @@ -32235,6 +32478,13 @@ public class DSL { /** * Get a bind value with an associated type, taken from a field. + *

    + * NOTE [#15268]: 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 + * means of a {@link Converter} or {@link Binding}, it's better to pass that + * converted {@link DataType} reference explicitly to + * {@link #val(Object, DataType)}. * * @param The generic value type * @param value The constant value @@ -34117,6 +34367,13 @@ public class DSL { /** * Get the default data type for the {@link DSLContext}'s underlying * {@link SQLDialect} and a given Java type. + *

    + * NOTE [#15268]: 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 + * means of a {@link Converter} or {@link Binding}, it's better to pass that + * converted {@link DataType} reference explicitly to + * {@link #param(DataType)}. * * @param The generic type * @param type The Java type. This must be a type supported by