#909 JDBC 4.5 support: "disable escape processing" JDBC escape

Author: mrotteveel

src/docs/asciidoc/release_notes.adoc

@@ -48,6 +48,9 @@ This results in two minor breaking changes:
 +
 ** Reserved words are no longer considered simple identifiers by `enquoteIdentifier` and `isSimpleIdentifier` and will be quoted (or -- for dialect 1 -- result in a `SQLFeatureNotSupportedException`)
 ** Presence of the NUL character (U+0000) in an identifier passed to `enquoteIdentifier` will result in a `SQLSyntaxErrorException`
+* JDBC 4.5 support: implemented "`disable escape processing`" JDBC escape (`++{\...\}++`) (https://github.com/FirebirdSQL/jaybird/issues/909[#909])
++
+See also <<jdbc-escape-disable-proc>>.
 * Fixed: JDBC escapes should not be parsed inside dialect 3 delimited identifiers or dialect 1 string literals (https://github.com/FirebirdSQL/jaybird/issues/921[#921])
 * Fixed: `IndexOutOfBoundsException` in `FBCachedBlob.getBytes(long, int)` for position or length beyond end of data (https://github.com/FirebirdSQL/jaybird/issues/923[#923])
 * Fixed: Using native client, password is limited to 255 bytes (https://github.com/FirebirdSQL/jaybird/issues/925[#925])
@@ -230,6 +233,7 @@ See <<native-plugin>> for more information.
 * <<no-close-after-last>>
 * <<scroll-rs-update-behavior>>
 * <<custom-socket-factory>>
+* <<jdbc-escape-disable-proc>> (since Jaybird 6.0.5)
 * ... and <<other-fixes-and-changes,other fixes and changes>>
 
 Upgrading from Jaybird 5 should be straightforward, but please make sure to read <<compatibility-changes>> before using Jaybird 6.
@@ -1387,6 +1391,83 @@ The other properties -- here `user`, `password` and `socketFactory` -- are *not*
 
 See also https://github.com/FirebirdSQL/jaybird/blob/master/devdoc/jdp/jdp-2024-09-custom-socket-factory-for-pure-java-connections.adoc[jdp-2024-09: Custom socket factory for pure Java connections]
 
+[#jdbc-escape-disable-proc]
+=== JDBC 4.5 support: JDBC escape to disable escape processing
+
+JDBC 4.5 (Java 26) introduces a new JDBC escape to disable escape processing and parameter parsing within part of a statement text.
+This JDBC escape has been implemented in Jaybird 5.0.12 (backported from Jaybird 6.0.5).
+The escape is always parsed if escape processing is enabled (the default), no matter the Java version and the JDBC minor version reported by `DatabaseMetaData#getJDBCMinorVersion()`.
+
+The "`disable escape processing`" escape starts with `++{\++` and ends with `++\}++`.
+Within the escape, *all* occurrences of a backslash (`\`) *must* be escaped by doubling.
+Unescaped backslashes inside the escape will result in a `FBSQLParseException`.
+
+.Some examples
+[listing]
+----
+-- Input:
+select {\"N\\A"\} from SOME_TABLE
+-- Sent to server:
+select "N\A" from SOME_TABLE
+
+-- Input:
+select {\{fn EXP(2)}\} from SOME_TABLE
+-- Sent to server (results in a syntax error)
+select {fn EXP(2)} from SOME_TABLE
+----
+
+.Same examples, but as Java string literals
+----
+-- Input:
+"select {\\\"N\\\\A\"\\} from SOME_TABLE"
+-- Sent to server:
+"select \"N\\A\" from SOME_TABLE"
+
+-- Input:
+"select {\\{fn EXP(2)}\\} from SOME_TABLE"
+-- Sent to server (results in a syntax error)
+"select {fn EXP(2)} from SOME_TABLE"
+----
+
+We think the use case for this escape is extremely limited, even non-existent, for Jaybird.
+Jaybird always offloads parameter parsing to Firebird, and Firebird currently has no syntax that could conflict with the definition of JDBC escapes.
+
+.Possible ambiguity for comments, literals, and delimited identifiers
+[CAUTION]
+====
+Given the backslash must be escaped everywhere inside the escape, the definition in the JDBC 4.5 specification can be interpreted to mean that the escape can end inside a comment, literal, or delimited identifier (quoted identifier).
+Allowing this would conflict with the fact that other JDBC escapes are not parsed inside comments, literals, and delimited identifiers.
+Discussion with the JDBC spec lead and others did not resolve this ambiguity.
+
+For Jaybird, we decide to reject attempts to end the escape in a comment, literal, or delimited identifier.
+Attempts to do so (e.g. `++{\ends/*in\}comment*/++`) will raise a `FBSQLParseException`.
+Valid alternatives would be:
+
+* End it before the comment: +
+`++{\ends\}/*in\}comment*/++`
+* End it after the comment and escape the backslash in the comment: +
+`++{\ends/*in\\}comment*/\}++`
+* Or, don't use the escape: +
+`++ends/*in\}comment*/++`
+
+If a consensus is reached in the JDBC Expert Group, or a community consensus arises, we may revisit this decision.
+
+Further details can be found in https://github.com/FirebirdSQL/jaybird/blob/master/devdoc/jdp/jdp-2026-03-jdbc-escape-to-disable-escape-processing.adoc[jdp-2026-03: JDBC escape to disable escape processing]
+====
+
+Given above ambiguity, and the lack of a real need to use it for Jaybird/Firebird, we recommend avoiding use of this escape unless absolutely necessary.
+If it is used, we recommend only using it for the shortest substring needed.
+
+For example, the last example (passing the `++{fn EXP(2)}++` to the server) could also be achieved by only disabling escape processing for the braces:
+
+[listing]
+----
+-- Input:
+select {\{\}fn EXP(2){\}\} from SOME_TABLE
+-- Sent to server (results in a syntax error)
+select {fn EXP(2)} from SOME_TABLE
+----
+
 [#other-fixes-and-changes]
 === Other fixes and changes