github/jooq
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[jOOQ/jOOQ#15261] Add Javadoc to plain SQL DSL.field() constructors recommending to use code generation or at least pass a DataType

Browse Source
This commit is contained in:
Lukas Eder 2023-06-21 08:40:03 +02:00
parent 91fa53d6c5
commit 03c14397ca
1 changed files with 128 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

151
jOOQ/src/main/java/org/jooq/impl/DSL.java
View File

@ -12622,22 +12622,46 @@ public class DSL {
* <p>
* This constructs a field reference given the field's qualified name. jOOQ
* <p>
* Example: <pre><code>
* Example:
*
* <pre>
* <code>
* // 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]
* </code></pre>
* </code>
* </pre>
* <p>
* Another example: <pre><code>
* Another example:
*
* <pre>
* <code>
* 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]
* </code></pre>
* </code>
* </pre>
* <p>
* <b>NOTE</b>: A lot of things work less well in jOOQ if no
* {@link DataType} information is attached to a {@link Field} expression,
* including:
* <ul>
* <li>Some drivers may find it hard to bind <code>NULL</code> values.</li>
* <li>Some RDBMS may find it hard to infer a type from an expression
* alone.</li>
* <li>User defined types may not be supported.</li>
* <li>You don't get compile time type safety.</li>
* </ul>
* It is usually better to use {@link DSL#field(Name, DataType)}, instead,
* or even better, use code generation where possible: <a href=
* "https://blog.jooq.org/why-you-should-use-jooq-with-code-generation/">https://blog.jooq.org/why-you-should-use-jooq-with-code-generation/</a>,
* in case of which {@link DataType} information is attached to all
* {@link Field} expressions automatically.
*/
@NotNull
@Support
@ -14102,16 +14126,35 @@ public class DSL {
/**
* Create a "plain SQL" field.
* <p>
* A PlainSQLField is a field that can contain user-defined plain SQL,
* A plain SQL field is a field that can contain user-defined plain SQL,
* because sometimes it is easier to express things directly in SQL, for
* instance complex proprietary functions. There must not be any binding
* variables contained in the SQL.
* <p>
* Example:
* <p>
* <pre><code>
*
* <pre>
* <code>
* String sql = "DECODE(MY_FIELD, 1, 100, 200)";
* </code></pre>
* </code>
* </pre>
* <p>
* <b>NOTE</b>: A lot of things work less well in jOOQ if no
* {@link DataType} information is attached to a {@link Field} expression,
* including:
* <ul>
* <li>Some drivers may find it hard to bind <code>NULL</code> values.</li>
* <li>Some RDBMS may find it hard to infer a type from an expression
* alone.</li>
* <li>User defined types may not be supported.</li>
* <li>You don't get compile time type safety.</li>
* </ul>
* It is usually better to use {@link DSL#field(SQL, DataType)}, instead, or
* even better, use code generation where possible: <a href=
* "https://blog.jooq.org/why-you-should-use-jooq-with-code-generation/">https://blog.jooq.org/why-you-should-use-jooq-with-code-generation/</a>,
* in case of which {@link DataType} information is attached to all
* {@link Field} expressions automatically.
* <p>
* <b>NOTE</b>: When inserting plain SQL into jOOQ objects, you must
* guarantee syntax integrity. You may also create the possibility of
@ -14132,16 +14175,35 @@ public class DSL {
/**
* Create a "plain SQL" field.
* <p>
* A PlainSQLField is a field that can contain user-defined plain SQL,
* A plain SQL field is a field that can contain user-defined plain SQL,
* because sometimes it is easier to express things directly in SQL, for
* instance complex proprietary functions. There must not be any binding
* variables contained in the SQL.
* <p>
* Example:
* <p>
* <pre><code>
*
* <pre>
* <code>
* String sql = "DECODE(MY_FIELD, 1, 100, 200)";
* </code></pre>
* </code>
* </pre>
* <p>
* <b>NOTE</b>: A lot of things work less well in jOOQ if no
* {@link DataType} information is attached to a {@link Field} expression,
* including:
* <ul>
* <li>Some drivers may find it hard to bind <code>NULL</code> values.</li>
* <li>Some RDBMS may find it hard to infer a type from an expression
* alone.</li>
* <li>User defined types may not be supported.</li>
* <li>You don't get compile time type safety.</li>
* </ul>
* It is usually better to use {@link DSL#field(String, DataType)}, instead,
* or even better, use code generation where possible: <a href=
* "https://blog.jooq.org/why-you-should-use-jooq-with-code-generation/">https://blog.jooq.org/why-you-should-use-jooq-with-code-generation/</a>,
* in case of which {@link DataType} information is attached to all
* {@link Field} expressions automatically.
* <p>
* <b>NOTE</b>: When inserting plain SQL into jOOQ objects, you must
* guarantee syntax integrity. You may also create the possibility of
@ -14162,16 +14224,35 @@ public class DSL {
/**
* Create a "plain SQL" field.
* <p>
* A PlainSQLField is a field that can contain user-defined plain SQL,
* A plain SQL field is a field that can contain user-defined plain SQL,
* because sometimes it is easier to express things directly in SQL, for
* instance complex proprietary functions. There must be as many binding
* variables contained in the SQL, as passed in the bindings parameter
* <p>
* Example:
* <p>
* <pre><code>
*
* <pre>
* <code>
* String sql = "DECODE(MY_FIELD, ?, ?, ?)";
* Object[] bindings = new Object[] { 1, 100, 200 };</code></pre>
* Object[] bindings = new Object[] { 1, 100, 200 };</code>
* </pre>
* <p>
* <b>NOTE</b>: A lot of things work less well in jOOQ if no
* {@link DataType} information is attached to a {@link Field} expression,
* including:
* <ul>
* <li>Some drivers may find it hard to bind <code>NULL</code> values.</li>
* <li>Some RDBMS may find it hard to infer a type from an expression
* alone.</li>
* <li>User defined types may not be supported.</li>
* <li>You don't get compile time type safety.</li>
* </ul>
* It is usually better to use {@link DSL#field(String, DataType, Object...)}, instead,
* or even better, use code generation where possible: <a href=
* "https://blog.jooq.org/why-you-should-use-jooq-with-code-generation/">https://blog.jooq.org/why-you-should-use-jooq-with-code-generation/</a>,
* in case of which {@link DataType} information is attached to all
* {@link Field} expressions automatically.
* <p>
* <b>NOTE</b>: When inserting plain SQL into jOOQ objects, you must
* guarantee syntax integrity. You may also create the possibility of
@ -14194,7 +14275,7 @@ public class DSL {
/**
* Create a "plain SQL" field.
* <p>
* A PlainSQLField is a field that can contain user-defined plain SQL,
* A plain SQL field is a field that can contain user-defined plain SQL,
* because sometimes it is easier to express things directly in SQL, for
* instance complex proprietary functions. There must not be any binding
* variables contained in the SQL.
@ -14226,7 +14307,7 @@ public class DSL {
/**
* Create a "plain SQL" field.
* <p>
* A PlainSQLField is a field that can contain user-defined plain SQL,
* A plain SQL field is a field that can contain user-defined plain SQL,
* because sometimes it is easier to express things directly in SQL, for
* instance complex proprietary functions. There must not be any binding
* variables contained in the SQL.
@ -14258,7 +14339,7 @@ public class DSL {
/**
* Create a "plain SQL" field.
* <p>
* A PlainSQLField is a field that can contain user-defined plain SQL,
* A plain SQL field is a field that can contain user-defined plain SQL,
* because sometimes it is easier to express things directly in SQL, for
* instance complex proprietary functions. There must be as many binding
* variables contained in the SQL, as passed in the bindings parameter
@ -14292,7 +14373,7 @@ public class DSL {
/**
* Create a "plain SQL" field.
* <p>
* A PlainSQLField is a field that can contain user-defined plain SQL,
* A plain SQL field is a field that can contain user-defined plain SQL,
* because sometimes it is easier to express things directly in SQL, for
* instance complex proprietary functions. There must not be any binding
* variables contained in the SQL.
@ -14323,7 +14404,7 @@ public class DSL {
/**
* Create a "plain SQL" field.
* <p>
* A PlainSQLField is a field that can contain user-defined plain SQL,
* A plain SQL field is a field that can contain user-defined plain SQL,
* because sometimes it is easier to express things directly in SQL, for
* instance complex proprietary functions. There must not be any binding
* variables contained in the SQL.
@ -14354,7 +14435,7 @@ public class DSL {
/**
* Create a "plain SQL" field.
* <p>
* A PlainSQLField is a field that can contain user-defined plain SQL,
* A plain SQL field is a field that can contain user-defined plain SQL,
* because sometimes it is easier to express things directly in SQL, for
* instance complex proprietary functions. There must be as many binding
* variables contained in the SQL, as passed in the bindings parameter
@ -14428,16 +14509,40 @@ public class DSL {
* This is useful for constructing more complex SQL syntax elements wherever
* <code>Field</code> types are expected. An example for this is MySQL's
* <code>GROUP_CONCAT</code> aggregate function, which has MySQL-specific
* keywords that are hard to reflect in jOOQ's DSL: <pre><code>
* keywords that are hard to reflect in jOOQ's DSL:
*
* <pre>
* <code>
* GROUP_CONCAT([DISTINCT] expr [,expr ...]
* [ORDER BY {unsigned_integer | col_name | expr}
* [ASC | DESC] [,col_name ...]]
* [SEPARATOR str_val])
* </code></pre>
* </code>
* </pre>
* <p>
* The above MySQL function can be expressed as such: <pre><code>
* The above MySQL function can be expressed as such:
*
* <pre>
* <code>
* field("GROUP_CONCAT(DISTINCT {0} ORDER BY {1} ASC SEPARATOR '-')", expr1, expr2);
* </code></pre>
* </code>
* </pre>
* <p>
* <b>NOTE</b>: A lot of things work less well in jOOQ if no
* {@link DataType} information is attached to a {@link Field} expression,
* including:
* <ul>
* <li>Some drivers may find it hard to bind <code>NULL</code> values.</li>
* <li>Some RDBMS may find it hard to infer a type from an expression
* alone.</li>
* <li>User defined types may not be supported.</li>
* <li>You don't get compile time type safety.</li>
* </ul>
* It is usually better to use {@link DSL#field(String, DataType, QueryPart...)}, instead,
* or even better, use code generation where possible: <a href=
* "https://blog.jooq.org/why-you-should-use-jooq-with-code-generation/">https://blog.jooq.org/why-you-should-use-jooq-with-code-generation/</a>,
* in case of which {@link DataType} information is attached to all
* {@link Field} expressions automatically.
* <p>
* <b>NOTE</b>: When inserting plain SQL into jOOQ objects, you must
* guarantee syntax integrity. You may also create the possibility of