From 6ef0fdf508fc174d40a87efeac708f48ee477fb4 Mon Sep 17 00:00:00 2001 From: lukaseder Date: Mon, 15 May 2017 13:56:17 +0200 Subject: [PATCH] [#6218] Add a section to the manual about the plain SQL templating part --- .../resources/org/jooq/web/manual-3.0.xml | 40 +++++++++++++ .../resources/org/jooq/web/manual-3.1.xml | 40 +++++++++++++ .../resources/org/jooq/web/manual-3.10.xml | 56 ++++++++++++++++++- .../resources/org/jooq/web/manual-3.2.xml | 40 +++++++++++++ .../resources/org/jooq/web/manual-3.3.xml | 40 +++++++++++++ .../resources/org/jooq/web/manual-3.4.xml | 40 +++++++++++++ .../resources/org/jooq/web/manual-3.5.xml | 40 +++++++++++++ .../resources/org/jooq/web/manual-3.6.xml | 52 +++++++++++++++++ .../resources/org/jooq/web/manual-3.7.xml | 52 +++++++++++++++++ .../resources/org/jooq/web/manual-3.8.xml | 52 +++++++++++++++++ .../resources/org/jooq/web/manual-3.9.xml | 52 +++++++++++++++++ 11 files changed, 502 insertions(+), 2 deletions(-) diff --git a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.0.xml b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.0.xml index 72a9e07a14..8ca607aba4 100644 --- a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.0.xml +++ b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.0.xml @@ -5579,6 +5579,10 @@ Condition condition(String sql, Object... bindings); // Example: condition("a = {0}", val(1)); Condition condition(String sql, QueryPart... parts);]]> +

+ Both the bind value and the query part argument overloads make use of jOOQ's . +

+

Please refer to the Javadoc for more details. The following is a more complete listing of plain SQL construction methods from the DSL:

@@ -5678,6 +5682,42 @@ create.select(LAST_NAME, COUNT1, COUNT2) +
+ Plain SQL Templating Language + +

+ The , as documented in the previous chapter, supports a string templating mini-language that allows for constructing complex SQL string content from smaller parts. A simple example can be seen below, e.g. when looking for support for one of PostgreSQL's various vendor-specific operator types: +

+ + + + + + +

+ Such a plain SQL template always consists of two things: +

+ +
    +
  • The SQL string fragment
    • +
  • A set of arguments, which are expected to be embedded in the SQL string
    • +
+ +

+ The SQL string may reference the arguments by 0-based indexing. Each argument may be referenced several times. For instance, SQLite's emulation of the REPEAT(string, count) function may look like this: +

+ + count = val(3); +Field string = val("abc"); +field("replace(substr(quote(zeroblob(({0} + 1) / 2)), 3, {0}), '0', {1})", String.class, count, string); +// ^ ^ ^ ^^^^^ ^^^^^^ +// | | | | | +// argument "count" is repeated twice: \------------------+----------|---------------------/ | +// argument "string" is used only once: \-----------------------------/]]> + + +
+
Bind values and parameters diff --git a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.1.xml b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.1.xml index effd4989aa..73aa37901b 100644 --- a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.1.xml +++ b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.1.xml @@ -5918,6 +5918,10 @@ Condition condition(String sql, Object... bindings); // Example: condition("a = {0}", val(1)); Condition condition(String sql, QueryPart... parts);]]> +

+ Both the bind value and the query part argument overloads make use of jOOQ's . +

+

Please refer to the Javadoc for more details. The following is a more complete listing of plain SQL construction methods from the DSL:

@@ -6017,6 +6021,42 @@ create.select(LAST_NAME, COUNT1, COUNT2)
+
+ Plain SQL Templating Language + +

+ The , as documented in the previous chapter, supports a string templating mini-language that allows for constructing complex SQL string content from smaller parts. A simple example can be seen below, e.g. when looking for support for one of PostgreSQL's various vendor-specific operator types: +

+ + + + + + +

+ Such a plain SQL template always consists of two things: +

+ +
    +
  • The SQL string fragment
    • +
  • A set of arguments, which are expected to be embedded in the SQL string
    • +
+ +

+ The SQL string may reference the arguments by 0-based indexing. Each argument may be referenced several times. For instance, SQLite's emulation of the REPEAT(string, count) function may look like this: +

+ + count = val(3); +Field string = val("abc"); +field("replace(substr(quote(zeroblob(({0} + 1) / 2)), 3, {0}), '0', {1})", String.class, count, string); +// ^ ^ ^ ^^^^^ ^^^^^^ +// | | | | | +// argument "count" is repeated twice: \------------------+----------|---------------------/ | +// argument "string" is used only once: \-----------------------------/]]> + + +
+
Bind values and parameters diff --git a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.10.xml b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.10.xml index 4715c6f985..eb667d7943 100644 --- a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.10.xml +++ b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.10.xml @@ -8703,6 +8703,10 @@ Condition condition(String sql, Object... bindings); // Example: condition("a = {0}", val(1)); Condition condition(String sql, QueryPart... parts);]]> +

+ Both the bind value and the query part argument overloads make use of jOOQ's . +

+

Please refer to the Javadoc for more details. The following is a more complete listing of plain SQL construction methods from the DSL:

@@ -8800,8 +8804,56 @@ create.select(LAST_NAME, COUNT1, COUNT2)
  • You have to provide consistency when you use variable binding. The number of ? must match the number of variables
  • Your SQL is inserted into jOOQ queries without further checks. Hence, jOOQ can't prevent SQL injection.
    • -     -
    + + + +
    + Plain SQL Templating Language + +

    + The , as documented in the previous chapter, supports a string templating mini-language that allows for constructing complex SQL string content from smaller parts. A simple example can be seen below, e.g. when looking for support for one of PostgreSQL's various vendor-specific operator types: +

    + + + + + + +

    + Such a plain SQL template always consists of two things: +

    + +
      +
    • The SQL string fragment
      • +
    • A set of arguments, which are expected to be embedded in the SQL string
      • +
    + +

    + The SQL string may reference the arguments by 0-based indexing. Each argument may be referenced several times. For instance, SQLite's emulation of the REPEAT(string, count) function may look like this: +

    + + count = val(3); +Field string = val("abc"); +field("replace(substr(quote(zeroblob(({0} + 1) / 2)), 3, {0}), '0', {1})", String.class, count, string); +// ^ ^ ^ ^^^^^ ^^^^^^ +// | | | | | +// argument "count" is repeated twice: \------------------+----------|---------------------/ | +// argument "string" is used only once: \-----------------------------/]]> + +

    + For convenience, there is also a API that allows for wrapping a comma-separated list of query parts in a single template argument: +

    + + a = val("a"); +Field b = val("b"); +Field c = val("c"); + +// These two produce the same result: +condition("my_column IN ({0}, {1}, {2}), a, b, c); // Using distinct template arguments +condition("my_column IN ({0})", list(a, b, c)); // Using a single template argument]]> + +     +
    Names and identifiers diff --git a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.2.xml b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.2.xml index 1fa6d9bf13..c7c501712d 100644 --- a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.2.xml +++ b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.2.xml @@ -6173,6 +6173,10 @@ Condition condition(String sql, Object... bindings); // Example: condition("a = {0}", val(1)); Condition condition(String sql, QueryPart... parts);]]> +

    + Both the bind value and the query part argument overloads make use of jOOQ's . +

    +

    Please refer to the Javadoc for more details. The following is a more complete listing of plain SQL construction methods from the DSL:

    @@ -6272,6 +6276,42 @@ create.select(LAST_NAME, COUNT1, COUNT2)
    +
    + Plain SQL Templating Language + +

    + The , as documented in the previous chapter, supports a string templating mini-language that allows for constructing complex SQL string content from smaller parts. A simple example can be seen below, e.g. when looking for support for one of PostgreSQL's various vendor-specific operator types: +

    + + + + + + +

    + Such a plain SQL template always consists of two things: +

    + +
      +
    • The SQL string fragment
      • +
    • A set of arguments, which are expected to be embedded in the SQL string
      • +
    + +

    + The SQL string may reference the arguments by 0-based indexing. Each argument may be referenced several times. For instance, SQLite's emulation of the REPEAT(string, count) function may look like this: +

    + + count = val(3); +Field string = val("abc"); +field("replace(substr(quote(zeroblob(({0} + 1) / 2)), 3, {0}), '0', {1})", String.class, count, string); +// ^ ^ ^ ^^^^^ ^^^^^^ +// | | | | | +// argument "count" is repeated twice: \------------------+----------|---------------------/ | +// argument "string" is used only once: \-----------------------------/]]> + +     +
    +
    Bind values and parameters diff --git a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.3.xml b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.3.xml index 390503b46d..fbef01a68d 100644 --- a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.3.xml +++ b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.3.xml @@ -6889,6 +6889,10 @@ Condition condition(String sql, Object... bindings); // Example: condition("a = {0}", val(1)); Condition condition(String sql, QueryPart... parts);]]> +

    + Both the bind value and the query part argument overloads make use of jOOQ's . +

    +

    Please refer to the Javadoc for more details. The following is a more complete listing of plain SQL construction methods from the DSL:

    @@ -6988,6 +6992,42 @@ create.select(LAST_NAME, COUNT1, COUNT2)
    +
    + Plain SQL Templating Language + +

    + The , as documented in the previous chapter, supports a string templating mini-language that allows for constructing complex SQL string content from smaller parts. A simple example can be seen below, e.g. when looking for support for one of PostgreSQL's various vendor-specific operator types: +

    + + + + + + +

    + Such a plain SQL template always consists of two things: +

    + +
      +
    • The SQL string fragment
      • +
    • A set of arguments, which are expected to be embedded in the SQL string
      • +
    + +

    + The SQL string may reference the arguments by 0-based indexing. Each argument may be referenced several times. For instance, SQLite's emulation of the REPEAT(string, count) function may look like this: +

    + + count = val(3); +Field string = val("abc"); +field("replace(substr(quote(zeroblob(({0} + 1) / 2)), 3, {0}), '0', {1})", String.class, count, string); +// ^ ^ ^ ^^^^^ ^^^^^^ +// | | | | | +// argument "count" is repeated twice: \------------------+----------|---------------------/ | +// argument "string" is used only once: \-----------------------------/]]> + +     +
    +
    Bind values and parameters diff --git a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.4.xml b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.4.xml index 872dfd287d..06aa3c62c6 100644 --- a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.4.xml +++ b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.4.xml @@ -7688,6 +7688,10 @@ Condition condition(String sql, Object... bindings); // Example: condition("a = {0}", val(1)); Condition condition(String sql, QueryPart... parts);]]> +

    + Both the bind value and the query part argument overloads make use of jOOQ's . +

    +

    Please refer to the Javadoc for more details. The following is a more complete listing of plain SQL construction methods from the DSL:

    @@ -7788,6 +7792,42 @@ create.select(LAST_NAME, COUNT1, COUNT2)
    +
    + Plain SQL Templating Language + +

    + The , as documented in the previous chapter, supports a string templating mini-language that allows for constructing complex SQL string content from smaller parts. A simple example can be seen below, e.g. when looking for support for one of PostgreSQL's various vendor-specific operator types: +

    + + + + + + +

    + Such a plain SQL template always consists of two things: +

    + +
      +
    • The SQL string fragment
      • +
    • A set of arguments, which are expected to be embedded in the SQL string
      • +
    + +

    + The SQL string may reference the arguments by 0-based indexing. Each argument may be referenced several times. For instance, SQLite's emulation of the REPEAT(string, count) function may look like this: +

    + + count = val(3); +Field string = val("abc"); +field("replace(substr(quote(zeroblob(({0} + 1) / 2)), 3, {0}), '0', {1})", String.class, count, string); +// ^ ^ ^ ^^^^^ ^^^^^^ +// | | | | | +// argument "count" is repeated twice: \------------------+----------|---------------------/ | +// argument "string" is used only once: \-----------------------------/]]> + +     +
    +
    Names and identifiers diff --git a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.5.xml b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.5.xml index 9c89d978b9..5a5a968630 100644 --- a/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.5.xml +++ b/jOOQ-manual/src/main/resources/org/jooq/web/manual-3.5.xml @@ -8085,6 +8085,10 @@ Condition condition(String sql, Object... bindings); // Example: condition("a = {0}", val(1)); Condition condition(String sql, QueryPart... parts);]]> +

    + Both the bind value and the query part argument overloads make use of jOOQ's . +

    +

    Please refer to the Javadoc for more details. The following is a more complete listing of plain SQL construction methods from the DSL:

    @@ -8185,6 +8189,42 @@ create.select(LAST_NAME, COUNT1, COUNT2)
    +
    + Plain SQL Templating Language + +

    + The , as documented in the previous chapter, supports a string templating mini-language that allows for constructing complex SQL string content from smaller parts. A simple example can be seen below, e.g. when looking for support for one of PostgreSQL's various vendor-specific operator types: +

    + + + + + + +

    + Such a plain SQL template always consists of two things: +

    + +
      +
    • The SQL string fragment
      • +
    • A set of arguments, which are expected to be embedded in the SQL string
      • +
    + +

    + The SQL string may reference the arguments by 0-based indexing. Each argument may be referenced several times. For instance, SQLite's emulation of the REPEAT(string, count) function may look like this: +

    + + count = val(3); +Field string = val("abc"); +field("replace(substr(quote(zeroblob(({0} + 1) / 2)), 3, {0}), '0', {1})", String.class, count, string); +// ^ ^ ^ ^^^^^ ^^^^^^ +// | | | | | +// argument "count" is repeated twice: \------------------+----------|---------------------/ | +// argument "string" is used only once: \-----------------------------/]]> + +     +
    +
    Names and identifiers 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 deaa8cade5..9a374c810f 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 @@ -8204,6 +8204,10 @@ Condition condition(String sql, Object... bindings); // Example: condition("a = {0}", val(1)); Condition condition(String sql, QueryPart... parts);]]> +

    + Both the bind value and the query part argument overloads make use of jOOQ's . +

    +

    Please refer to the Javadoc for more details. The following is a more complete listing of plain SQL construction methods from the DSL:

    @@ -8304,6 +8308,54 @@ create.select(LAST_NAME, COUNT1, COUNT2)
    +
    + Plain SQL Templating Language + +

    + The , as documented in the previous chapter, supports a string templating mini-language that allows for constructing complex SQL string content from smaller parts. A simple example can be seen below, e.g. when looking for support for one of PostgreSQL's various vendor-specific operator types: +

    + + + + + + +

    + Such a plain SQL template always consists of two things: +

    + +
      +
    • The SQL string fragment
      • +
    • A set of arguments, which are expected to be embedded in the SQL string
      • +
    + +

    + The SQL string may reference the arguments by 0-based indexing. Each argument may be referenced several times. For instance, SQLite's emulation of the REPEAT(string, count) function may look like this: +

    + + count = val(3); +Field string = val("abc"); +field("replace(substr(quote(zeroblob(({0} + 1) / 2)), 3, {0}), '0', {1})", String.class, count, string); +// ^ ^ ^ ^^^^^ ^^^^^^ +// | | | | | +// argument "count" is repeated twice: \------------------+----------|---------------------/ | +// argument "string" is used only once: \-----------------------------/]]> + +

    + For convenience, there is also a API that allows for wrapping a comma-separated list of query parts in a single template argument: +

    + + a = val("a"); +Field b = val("b"); +Field c = val("c"); + +// These two produce the same result: +condition("my_column IN ({0}, {1}, {2}), a, b, c); // Using distinct template arguments +condition("my_column IN ({0})", list(a, b, c)); // Using a single template argument]]> + +     +
    +
    Names and identifiers 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 e8ea50454a..6a23da07d8 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 @@ -8457,6 +8457,10 @@ Condition condition(String sql, Object... bindings); // Example: condition("a = {0}", val(1)); Condition condition(String sql, QueryPart... parts);]]> +

    + Both the bind value and the query part argument overloads make use of jOOQ's . +

    +

    Please refer to the Javadoc for more details. The following is a more complete listing of plain SQL construction methods from the DSL:

    @@ -8557,6 +8561,54 @@ create.select(LAST_NAME, COUNT1, COUNT2)
    +
    + Plain SQL Templating Language + +

    + The , as documented in the previous chapter, supports a string templating mini-language that allows for constructing complex SQL string content from smaller parts. A simple example can be seen below, e.g. when looking for support for one of PostgreSQL's various vendor-specific operator types: +

    + + + + + + +

    + Such a plain SQL template always consists of two things: +

    + +
      +
    • The SQL string fragment
      • +
    • A set of arguments, which are expected to be embedded in the SQL string
      • +
    + +

    + The SQL string may reference the arguments by 0-based indexing. Each argument may be referenced several times. For instance, SQLite's emulation of the REPEAT(string, count) function may look like this: +

    + + count = val(3); +Field string = val("abc"); +field("replace(substr(quote(zeroblob(({0} + 1) / 2)), 3, {0}), '0', {1})", String.class, count, string); +// ^ ^ ^ ^^^^^ ^^^^^^ +// | | | | | +// argument "count" is repeated twice: \------------------+----------|---------------------/ | +// argument "string" is used only once: \-----------------------------/]]> + +

    + For convenience, there is also a API that allows for wrapping a comma-separated list of query parts in a single template argument: +

    + + a = val("a"); +Field b = val("b"); +Field c = val("c"); + +// These two produce the same result: +condition("my_column IN ({0}, {1}, {2}), a, b, c); // Using distinct template arguments +condition("my_column IN ({0})", list(a, b, c)); // Using a single template argument]]> + +     +
    +
    Names and identifiers 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 5c870410a7..3420899866 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 @@ -8594,6 +8594,10 @@ Condition condition(String sql, Object... bindings); // Example: condition("a = {0}", val(1)); Condition condition(String sql, QueryPart... parts);]]> +

    + Both the bind value and the query part argument overloads make use of jOOQ's . +

    +

    Please refer to the Javadoc for more details. The following is a more complete listing of plain SQL construction methods from the DSL:

    @@ -8694,6 +8698,54 @@ create.select(LAST_NAME, COUNT1, COUNT2)
    +
    + Plain SQL Templating Language + +

    + The , as documented in the previous chapter, supports a string templating mini-language that allows for constructing complex SQL string content from smaller parts. A simple example can be seen below, e.g. when looking for support for one of PostgreSQL's various vendor-specific operator types: +

    + + + + + + +

    + Such a plain SQL template always consists of two things: +

    + +
      +
    • The SQL string fragment
      • +
    • A set of arguments, which are expected to be embedded in the SQL string
      • +
    + +

    + The SQL string may reference the arguments by 0-based indexing. Each argument may be referenced several times. For instance, SQLite's emulation of the REPEAT(string, count) function may look like this: +

    + + count = val(3); +Field string = val("abc"); +field("replace(substr(quote(zeroblob(({0} + 1) / 2)), 3, {0}), '0', {1})", String.class, count, string); +// ^ ^ ^ ^^^^^ ^^^^^^ +// | | | | | +// argument "count" is repeated twice: \------------------+----------|---------------------/ | +// argument "string" is used only once: \-----------------------------/]]> + +

    + For convenience, there is also a API that allows for wrapping a comma-separated list of query parts in a single template argument: +

    + + a = val("a"); +Field b = val("b"); +Field c = val("c"); + +// These two produce the same result: +condition("my_column IN ({0}, {1}, {2}), a, b, c); // Using distinct template arguments +condition("my_column IN ({0})", list(a, b, c)); // Using a single template argument]]> + +     +
    +
    Names and identifiers 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 d46bb2f16f..6d7e62e2a5 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 @@ -8647,6 +8647,10 @@ Condition condition(String sql, Object... bindings); // Example: condition("a = {0}", val(1)); Condition condition(String sql, QueryPart... parts);]]> +

    + Both the bind value and the query part argument overloads make use of jOOQ's . +

    +

    Please refer to the Javadoc for more details. The following is a more complete listing of plain SQL construction methods from the DSL:

    @@ -8747,6 +8751,54 @@ create.select(LAST_NAME, COUNT1, COUNT2)
    +
    + Plain SQL Templating Language + +

    + The , as documented in the previous chapter, supports a string templating mini-language that allows for constructing complex SQL string content from smaller parts. A simple example can be seen below, e.g. when looking for support for one of PostgreSQL's various vendor-specific operator types: +

    + + + + + + +

    + Such a plain SQL template always consists of two things: +

    + +
      +
    • The SQL string fragment
      • +
    • A set of arguments, which are expected to be embedded in the SQL string
      • +
    + +

    + The SQL string may reference the arguments by 0-based indexing. Each argument may be referenced several times. For instance, SQLite's emulation of the REPEAT(string, count) function may look like this: +

    + + count = val(3); +Field string = val("abc"); +field("replace(substr(quote(zeroblob(({0} + 1) / 2)), 3, {0}), '0', {1})", String.class, count, string); +// ^ ^ ^ ^^^^^ ^^^^^^ +// | | | | | +// argument "count" is repeated twice: \------------------+----------|---------------------/ | +// argument "string" is used only once: \-----------------------------/]]> + +

    + For convenience, there is also a API that allows for wrapping a comma-separated list of query parts in a single template argument: +

    + + a = val("a"); +Field b = val("b"); +Field c = val("c"); + +// These two produce the same result: +condition("my_column IN ({0}, {1}, {2}), a, b, c); // Using distinct template arguments +condition("my_column IN ({0})", list(a, b, c)); // Using a single template argument]]> + +     +
    +
    Names and identifiers