From 1b04fb27d7b2ebf84568c43d4f5e979afa46a309 Mon Sep 17 00:00:00 2001 From: lukaseder Date: Thu, 18 Aug 2016 13:28:42 +0200 Subject: [PATCH] [#5494] Improve section of the manual explaining the plain SQL templating logic --- .../resources/org/jooq/web/manual-3.6.xml | 86 ++++++++++++++----- .../resources/org/jooq/web/manual-3.7.xml | 86 ++++++++++++++----- .../resources/org/jooq/web/manual-3.8.xml | 86 ++++++++++++++----- .../resources/org/jooq/web/manual-3.9.xml | 52 +++++++++-- jOOQ/src/main/java/org/jooq/impl/DSL.java | 58 +++++++------ 5 files changed, 270 insertions(+), 98 deletions(-) diff --git a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.6.xml b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.6.xml index 0a4c97897d..b517f1dc5e 100644 --- a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.6.xml +++ b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.6.xml @@ -9134,34 +9134,76 @@ class ToChar extends CustomField { -
- Plain SQL QueryParts - -

- If you don't need the integration of rather complex QueryParts into jOOQ, then you might be safer using simple functionality, where you can provide jOOQ with a simple String representation of your embedded SQL. Plain SQL methods in jOOQ's API come in two flavours. -

-
    -
  • method(String, Object...): This is a method that accepts a SQL string and a list of bind values that are to be bound to the variables contained in the SQL string
    • -
  • method(String, QueryPart...): This is a method that accepts a SQL string and a list of QueryParts that are "injected" at the position of their respective placeholders in the SQL string
    • -
-

- The above distinction is best explained using an example: -

+
+ Plain SQL QueryParts + +

+ If you don't need the integration of rather complex QueryParts into jOOQ, then you might be safer using simple functionality, where you can provide jOOQ with a simple String representation of your embedded SQL. Plain SQL methods in jOOQ's API come in two flavours. +

+
    +
  • method(String, Object...): This is a method that accepts a SQL string and a list of bind values that are to be bound to the variables contained in the SQL string
    • +
  • method(String, QueryPart...): This is a method that accepts a SQL string and a list of QueryParts that are "injected" at the position of their respective placeholders in the SQL string
    • +
+

+ The above distinction is best explained using an example: +

id = val(5); Field title = val("Animal Farm"); -create.selectFrom(BOOK).where("BOOK.ID = {0} AND TITLE = {1}", id, title).fetch();]]> +create.selectFrom(BOOK).where( + "BOOK.ID = {0} AND TITLE = {1}", // The SQL string containing QueryPart placeholders ("{N}") + id, // The QueryPart at index 0 + title // The QueryPart at index 1 +).fetch();]]> -

- The above technique allows for creating rather complex SQL clauses that are currently not supported by jOOQ, without extending any of the as indicated in the previous chapter. -

- -
+

+ Note that for historic reasons the two API usages can also be mixed, although this is not recommended and the exact behaviour is unspecified. +

+ +

Plain SQL templating specification

+ +

+ Templating with QueryPart placeholders (or bind value placeholders) requires a simple parsing logic to be applied to SQL strings. The jOOQ template parser behaves according to the following rules: +

+ +
    +
  • Single-line comments (starting with -- in all databases (or #) in MySQL) are rendered without modification. Any bind variable or QueryPart placeholders in such comments are ignored.
    • +
  • Multi-line comments (starting with /* and ending with */ in all databases) are rendered without modification. Any bind variable or QueryPart placeholders in such comments are ignored.
    • +
  • String literals (starting and ending with ' in all databases, where all databases support escaping of the quote character by duplication as such: '', or in MySQL by escaping as such: \' (if is turned on)) are rendered without modification. Any bind variable or QueryPart placeholders in such comments are ignored.
    • +
  • Quoted names (starting and ending with " in most databases, with ` in MySQL, or with [ and ] in T-SQL databases) are rendered without modification. Any bind variable or QueryPart placeholders in such comments are ignored.
    • +
  • JDBC escape syntax ({fn ...}, {d ...}, {t ...}, {ts ...}) is rendered without modification. Any bind variable or QueryPart placeholders in such comments are ignored.
    • +
  • Bind variable placeholders (? or :name for named bind variables) are replaced by the matching bind value in case inlining is activated, e.g. through .
    • +
  • QueryPart placeholders ({number}) are replaced by the matching QueryPart.
    • +
  • Keywords ({identifier}) are treated like keywords and rendered in the correct case according to .
    • +
+ +

Tools for templating

+ +

+ A variety of API is provided to create template elements that are intended for use with the above templating mechanism. These tools can be found in +

+ + parts) { ... } +]]> + +
Serializability diff --git a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.7.xml b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.7.xml index e9265c1d61..1aef9e6568 100644 --- a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.7.xml +++ b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.7.xml @@ -9369,34 +9369,76 @@ class ToChar extends CustomField {
-
- Plain SQL QueryParts - -

- If you don't need the integration of rather complex QueryParts into jOOQ, then you might be safer using simple functionality, where you can provide jOOQ with a simple String representation of your embedded SQL. Plain SQL methods in jOOQ's API come in two flavours. -

-
    -
  • method(String, Object...): This is a method that accepts a SQL string and a list of bind values that are to be bound to the variables contained in the SQL string
    • -
  • method(String, QueryPart...): This is a method that accepts a SQL string and a list of QueryParts that are "injected" at the position of their respective placeholders in the SQL string
    • -
-

- The above distinction is best explained using an example: -

+
+ Plain SQL QueryParts + +

+ If you don't need the integration of rather complex QueryParts into jOOQ, then you might be safer using simple functionality, where you can provide jOOQ with a simple String representation of your embedded SQL. Plain SQL methods in jOOQ's API come in two flavours. +

+
    +
  • method(String, Object...): This is a method that accepts a SQL string and a list of bind values that are to be bound to the variables contained in the SQL string
    • +
  • method(String, QueryPart...): This is a method that accepts a SQL string and a list of QueryParts that are "injected" at the position of their respective placeholders in the SQL string
    • +
+

+ The above distinction is best explained using an example: +

id = val(5); Field title = val("Animal Farm"); -create.selectFrom(BOOK).where("BOOK.ID = {0} AND TITLE = {1}", id, title).fetch();]]> +create.selectFrom(BOOK).where( + "BOOK.ID = {0} AND TITLE = {1}", // The SQL string containing QueryPart placeholders ("{N}") + id, // The QueryPart at index 0 + title // The QueryPart at index 1 +).fetch();]]> -

- The above technique allows for creating rather complex SQL clauses that are currently not supported by jOOQ, without extending any of the as indicated in the previous chapter. -

- -
+

+ Note that for historic reasons the two API usages can also be mixed, although this is not recommended and the exact behaviour is unspecified. +

+ +

Plain SQL templating specification

+ +

+ Templating with QueryPart placeholders (or bind value placeholders) requires a simple parsing logic to be applied to SQL strings. The jOOQ template parser behaves according to the following rules: +

+ +
    +
  • Single-line comments (starting with -- in all databases (or #) in MySQL) are rendered without modification. Any bind variable or QueryPart placeholders in such comments are ignored.
    • +
  • Multi-line comments (starting with /* and ending with */ in all databases) are rendered without modification. Any bind variable or QueryPart placeholders in such comments are ignored.
    • +
  • String literals (starting and ending with ' in all databases, where all databases support escaping of the quote character by duplication as such: '', or in MySQL by escaping as such: \' (if is turned on)) are rendered without modification. Any bind variable or QueryPart placeholders in such comments are ignored.
    • +
  • Quoted names (starting and ending with " in most databases, with ` in MySQL, or with [ and ] in T-SQL databases) are rendered without modification. Any bind variable or QueryPart placeholders in such comments are ignored.
    • +
  • JDBC escape syntax ({fn ...}, {d ...}, {t ...}, {ts ...}) is rendered without modification. Any bind variable or QueryPart placeholders in such comments are ignored.
    • +
  • Bind variable placeholders (? or :name for named bind variables) are replaced by the matching bind value in case inlining is activated, e.g. through .
    • +
  • QueryPart placeholders ({number}) are replaced by the matching QueryPart.
    • +
  • Keywords ({identifier}) are treated like keywords and rendered in the correct case according to .
    • +
+ +

Tools for templating

+ +

+ A variety of API is provided to create template elements that are intended for use with the above templating mechanism. These tools can be found in +

+ + parts) { ... } +]]> + +
Serializability diff --git a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.8.xml b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.8.xml index fa86bcdc8e..2a30323783 100644 --- a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.8.xml +++ b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.8.xml @@ -9458,34 +9458,76 @@ class ToChar extends CustomField {
-
- Plain SQL QueryParts - -

- If you don't need the integration of rather complex QueryParts into jOOQ, then you might be safer using simple functionality, where you can provide jOOQ with a simple String representation of your embedded SQL. Plain SQL methods in jOOQ's API come in two flavours. -

-
    -
  • method(String, Object...): This is a method that accepts a SQL string and a list of bind values that are to be bound to the variables contained in the SQL string
    • -
  • method(String, QueryPart...): This is a method that accepts a SQL string and a list of QueryParts that are "injected" at the position of their respective placeholders in the SQL string
    • -
-

- The above distinction is best explained using an example: -

+
+ Plain SQL QueryParts + +

+ If you don't need the integration of rather complex QueryParts into jOOQ, then you might be safer using simple functionality, where you can provide jOOQ with a simple String representation of your embedded SQL. Plain SQL methods in jOOQ's API come in two flavours. +

+
    +
  • method(String, Object...): This is a method that accepts a SQL string and a list of bind values that are to be bound to the variables contained in the SQL string
    • +
  • method(String, QueryPart...): This is a method that accepts a SQL string and a list of QueryParts that are "injected" at the position of their respective placeholders in the SQL string
    • +
+

+ The above distinction is best explained using an example: +

id = val(5); Field title = val("Animal Farm"); -create.selectFrom(BOOK).where("BOOK.ID = {0} AND TITLE = {1}", id, title).fetch();]]> +create.selectFrom(BOOK).where( + "BOOK.ID = {0} AND TITLE = {1}", // The SQL string containing QueryPart placeholders ("{N}") + id, // The QueryPart at index 0 + title // The QueryPart at index 1 +).fetch();]]> -

- The above technique allows for creating rather complex SQL clauses that are currently not supported by jOOQ, without extending any of the as indicated in the previous chapter. -

- -
+

+ Note that for historic reasons the two API usages can also be mixed, although this is not recommended and the exact behaviour is unspecified. +

+ +

Plain SQL templating specification

+ +

+ Templating with QueryPart placeholders (or bind value placeholders) requires a simple parsing logic to be applied to SQL strings. The jOOQ template parser behaves according to the following rules: +

+ +
    +
  • Single-line comments (starting with -- in all databases (or #) in MySQL) are rendered without modification. Any bind variable or QueryPart placeholders in such comments are ignored.
    • +
  • Multi-line comments (starting with /* and ending with */ in all databases) are rendered without modification. Any bind variable or QueryPart placeholders in such comments are ignored.
    • +
  • String literals (starting and ending with ' in all databases, where all databases support escaping of the quote character by duplication as such: '', or in MySQL by escaping as such: \' (if is turned on)) are rendered without modification. Any bind variable or QueryPart placeholders in such comments are ignored.
    • +
  • Quoted names (starting and ending with " in most databases, with ` in MySQL, or with [ and ] in T-SQL databases) are rendered without modification. Any bind variable or QueryPart placeholders in such comments are ignored.
    • +
  • JDBC escape syntax ({fn ...}, {d ...}, {t ...}, {ts ...}) is rendered without modification. Any bind variable or QueryPart placeholders in such comments are ignored.
    • +
  • Bind variable placeholders (? or :name for named bind variables) are replaced by the matching bind value in case inlining is activated, e.g. through .
    • +
  • QueryPart placeholders ({number}) are replaced by the matching QueryPart.
    • +
  • Keywords ({identifier}) are treated like keywords and rendered in the correct case according to .
    • +
+ +

Tools for templating

+ +

+ A variety of API is provided to create template elements that are intended for use with the above templating mechanism. These tools can be found in +

+ + parts) { ... } +]]> + +
Serializability diff --git a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.9.xml b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.9.xml index ca9134cb7c..06d9768056 100644 --- a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.9.xml +++ b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.9.xml @@ -9472,17 +9472,59 @@ class ToChar extends CustomField {

id = val(5); Field title = val("Animal Farm"); -create.selectFrom(BOOK).where("BOOK.ID = {0} AND TITLE = {1}", id, title).fetch();]]> +create.selectFrom(BOOK).where( + "BOOK.ID = {0} AND TITLE = {1}", // The SQL string containing QueryPart placeholders ("{N}") + id, // The QueryPart at index 0 + title // The QueryPart at index 1 +).fetch();]]>

- The above technique allows for creating rather complex SQL clauses that are currently not supported by jOOQ, without extending any of the as indicated in the previous chapter. + Note that for historic reasons the two API usages can also be mixed, although this is not recommended and the exact behaviour is unspecified.

+ +

Plain SQL templating specification

+ +

+ Templating with QueryPart placeholders (or bind value placeholders) requires a simple parsing logic to be applied to SQL strings. The jOOQ template parser behaves according to the following rules: +

+ +
    +
  • Single-line comments (starting with -- in all databases (or #) in MySQL) are rendered without modification. Any bind variable or QueryPart placeholders in such comments are ignored.
    • +
  • Multi-line comments (starting with /* and ending with */ in all databases) are rendered without modification. Any bind variable or QueryPart placeholders in such comments are ignored.
    • +
  • String literals (starting and ending with ' in all databases, where all databases support escaping of the quote character by duplication as such: '', or in MySQL by escaping as such: \' (if is turned on)) are rendered without modification. Any bind variable or QueryPart placeholders in such comments are ignored.
    • +
  • Quoted names (starting and ending with " in most databases, with ` in MySQL, or with [ and ] in T-SQL databases) are rendered without modification. Any bind variable or QueryPart placeholders in such comments are ignored.
    • +
  • JDBC escape syntax ({fn ...}, {d ...}, {t ...}, {ts ...}) is rendered without modification. Any bind variable or QueryPart placeholders in such comments are ignored.
    • +
  • Bind variable placeholders (? or :name for named bind variables) are replaced by the matching bind value in case inlining is activated, e.g. through .
    • +
  • QueryPart placeholders ({number}) are replaced by the matching QueryPart.
    • +
  • Keywords ({identifier}) are treated like keywords and rendered in the correct case according to .
    • +
+ +

Tools for templating

+ +

+ A variety of API is provided to create template elements that are intended for use with the above templating mechanism. These tools can be found in +

+ + parts) { ... } +]]>
diff --git a/jOOQ/src/main/java/org/jooq/impl/DSL.java b/jOOQ/src/main/java/org/jooq/impl/DSL.java index d14212b084..44485ffd04 100644 --- a/jOOQ/src/main/java/org/jooq/impl/DSL.java +++ b/jOOQ/src/main/java/org/jooq/impl/DSL.java @@ -6968,6 +6968,37 @@ public class DSL { return new KeywordImpl(keyword); } + // ------------------------------------------------------------------------- + // XXX Names + // ------------------------------------------------------------------------- + + /** + * Create a new SQL identifier using a qualified name. + *

+ * Use this method to construct syntax-safe, SQL-injection-safe SQL + * identifiers for use in plain SQL where {@link QueryPart} objects are + * accepted. For instance, this can be used with any of these methods: + *

+ *

+ * An example: 

+     * // This qualified name here
+     * name("book", "title");
+     *
+     * // ... will render this SQL on SQL Server with RenderNameStyle.QUOTED set
+     * [book].[title]
+     *
+ * + * @param qualifiedName The SQL identifier's qualified name parts + * @return A {@link QueryPart} that will render the SQL identifier + */ + public static Name name(String... qualifiedName) { + return new NameImpl(qualifiedName); + } + // ------------------------------------------------------------------------- // XXX QueryPart composition // ------------------------------------------------------------------------- @@ -7033,33 +7064,6 @@ public class DSL { return new SQLField(field.getDataType(), keyword("default")); } - /** - * Create a new SQL identifier using a qualified name. - *

- * Use this method to construct syntax-safe, SQL-injection-safe SQL - * identifiers for use in plain SQL where {@link QueryPart} objects are - * accepted. For instance, this can be used with any of these methods: - *

    - *
  • {@link #field(String, QueryPart...)}
    • - *
  • {@link #field(String, Class, QueryPart...)}
    • - *
  • {@link #field(String, DataType, QueryPart...)}
    • - *
- *

- * An example: 

-     * // This qualified name here
-     * name("book", "title");
-     *
-     * // ... will render this SQL on SQL Server with RenderNameStyle.QUOTED set
-     * [book].[title]
-     *
- * - * @param qualifiedName The SQL identifier's qualified name parts - * @return A {@link QueryPart} that will render the SQL identifier - */ - public static Name name(String... qualifiedName) { - return new NameImpl(qualifiedName); - } - /** * Create a qualified schema, given its schema name. *