#343 Improve call escape handling and configuration

Improve test coverage

Author: mrotteveel

src/main/org/firebirdsql/jdbc/FBCallableStatement.java

@@ -13,7 +13,11 @@
 
 import org.firebirdsql.gds.ng.LockCloseable;
 import org.firebirdsql.gds.ng.StatementType;
+import org.firebirdsql.jdbc.FBObjectListener.BlobListener;
+import org.firebirdsql.jdbc.FBObjectListener.StatementListener;
+import org.firebirdsql.jdbc.escape.CallEscapeHandling;
 import org.firebirdsql.jdbc.escape.FBEscapedCallParser;
+import org.firebirdsql.jdbc.escape.JdbcEscapeParser;
 import org.firebirdsql.jdbc.field.FBField;
 import org.firebirdsql.jdbc.field.TypeConversionException;
 import org.firebirdsql.util.InternalApi;
@@ -31,7 +35,7 @@
 import static org.firebirdsql.jdbc.SQLStateConstants.SQL_STATE_NO_RESULT_SET;
 
 /**
- * Implementation of {@link java.sql.CallableStatement}.
+ * Implementation of {@link java.sql.CallableStatement} (the <em>V1</em> implementation).
  * <p>
  * This class is internal API of Jaybird. Future versions may radically change, move, or make inaccessible this type.
  * For the public API, refer to the {@link java.sql.CallableStatement} and {@link FirebirdCallableStatement} interfaces.
@@ -51,8 +55,8 @@ public class FBCallableStatement extends FBPreparedStatement implements Callable
     protected FBProcedureCall procedureCall;
 
     protected FBCallableStatement(FBConnection connection, String sql, ResultSetBehavior rsBehavior,
-            StoredProcedureMetaData storedProcMetaData, FBObjectListener.StatementListener statementListener,
-            FBObjectListener.BlobListener blobListener) throws SQLException {
+            StoredProcedureMetaData storedProcMetaData, StatementListener statementListener, BlobListener blobListener)
+            throws SQLException {
         super(connection, rsBehavior, statementListener, blobListener);
         var parser = new FBEscapedCallParser(getEscapeParser(), connection.getServerVersion());
 
@@ -65,6 +69,12 @@ protected FBCallableStatement(FBConnection connection, String sql, ResultSetBeha
         storedProcMetaData.updateSelectability(procedureCall);
     }
 
+    @Override
+    JdbcEscapeParser getEscapeParser() throws SQLException {
+        // This implementation handles the transformation of the call escape itself, so the escape parser shouldn't
+        return super.getEscapeParser().with(CallEscapeHandling.IGNORED);
+    }
+
     @Override
     public void close() throws SQLException {
         try (var ignored = withLock()) {

src/main/org/firebirdsql/jdbc/FBConnection.java

@@ -28,6 +28,8 @@
 import org.firebirdsql.jaybird.util.SearchPathHelper;
 import org.firebirdsql.jaybird.xca.FBLocalTransaction;
 import org.firebirdsql.jaybird.xca.FBManagedConnection;
+import org.firebirdsql.jdbc.FBObjectListener.BlobListener;
+import org.firebirdsql.jdbc.FBObjectListener.StatementListener;
 import org.firebirdsql.jdbc.InternalTransactionCoordinator.MetaDataTransactionCoordinator;
 import org.firebirdsql.jdbc.escape.FBEscapedParser;
 import org.firebirdsql.util.InternalApi;
@@ -821,8 +823,8 @@ protected PreparedStatement prepareStatement(String sql, int resultSetType, int
             Optional<PreparedStatement> txStmt = prepareIfTransactionStatement(sql, rsBehavior);
             if (txStmt.isPresent()) return txStmt.get();
 
-            FBObjectListener.StatementListener coordinator = txCoordinator;
-            FBObjectListener.BlobListener blobCoordinator = txCoordinator;
+            StatementListener coordinator = txCoordinator;
+            BlobListener blobCoordinator = txCoordinator;
             if (metaData) {
                 coordinator =  new MetaDataTransactionCoordinator(txCoordinator);
                 blobCoordinator = null;
@@ -927,13 +929,26 @@ public CallableStatement prepareCall(String sql, int resultSetType, int resultSe
                 storedProcedureMetaData = StoredProcedureMetaDataFactory.getInstance(this);
             }
 
-            var stmt = new FBCallableStatement(this, sql, rsBehavior, storedProcedureMetaData, txCoordinator,
+            CallableStatement stmt = createCallableStatement(sql, rsBehavior, storedProcedureMetaData, txCoordinator,
                     txCoordinator);
             activeStatements.add(stmt);
             return stmt;
         }
     }
 
+    final FirebirdCallableStatement createCallableStatement(String sql, ResultSetBehavior rsBehavior,
+            StoredProcedureMetaData storedProcedureMetaData, StatementListener statementListener,
+            BlobListener blobListener) throws SQLException {
+        return switch (getCallableImplementation().toUpperCase(Locale.ROOT)) {
+            case PropertyConstants.CALLABLE_IMPLEMENTATION_V1 -> new FBCallableStatement(this, sql, rsBehavior,
+                    storedProcedureMetaData, statementListener, blobListener);
+            case PropertyConstants.CALLABLE_IMPLEMENTATION_V2 -> throw new FBDriverNotCapableException(
+                    "Callable implementation V2 not yet available");
+            default -> throw new FBDriverNotCapableException(
+                    "Unknown callable implementation: %s".formatted(getCallableImplementation()));
+        };
+    }
+
     @Override
     public Map<String, Class<?>> getTypeMap() throws SQLException {
         return new HashMap<>();
@@ -1596,6 +1611,10 @@ final boolean isEscapeProcessing() {
         return connectionProperties().isEscapeProcessing();
     }
 
+    final String getCallableImplementation() {
+        return connectionProperties().getCallableImplementation();
+    }
+
     final GDSServerVersion getServerVersion() throws SQLException {
         return getGDSHelper().getServerVersion();
     }

src/main/org/firebirdsql/jdbc/FBPreparedStatement.java

@@ -67,32 +67,38 @@ public class FBPreparedStatement extends FBStatement implements FirebirdPrepared
     private final boolean metaDataQuery;
 
     /**
-     * This flag is needed to guarantee the correct behavior in case when it 
-     * was created without controlling Connection object (in some metadata
-     * queries we have only GDSHelper instance)
+     * Marks the statement as a standalone statement.
+     * <p>
+     * This ensures correct behaviour when created without an owning Connection object (in some metadata queries we only
+     * have a GDSHelper instance).
+     * </p>
      */
     private final boolean standaloneStatement;
 
     /**
-     * This flag is needed to prevent throwing an exception for the case when
-     * result set is returned for INSERT statement and the statement should
-     * return the generated keys.
+     * Marks the statement as a generated keys statement.
+     * <p>
+     * This prevents throwing an exception when a result set is returned for statements with a {@code RETURNING} clause
+     * when executed with {@code executeUpdate}.
+     * </p>
      */
     private final boolean generatedKeys;
 
     private FBField[] fields = FIELDS_NOT_INITIALIZED;
 
-    // we need to handle procedure execution separately,
-    // because in this case we must send out_xsqlda to the server.
+    // We handle procedure execution separately, because we must send out_xsqlda to the server
     private boolean isExecuteProcedureStatement;
 
     private final FBObjectListener.BlobListener blobListener;
     private RowValue fieldValues = RowValue.EMPTY_ROW_VALUE;
     private @Nullable Batch batch;
 
     /**
-     * Create instance of this class for the specified result set type and concurrency. This constructor is used only in
-     * {@link FBCallableStatement} since the statement is prepared right before the execution.
+     * Create instance of this class for the specified result set type and concurrency.
+     * <p>
+     * This constructor is for use in {@link FBCallableStatement} and {@link FBCallableStatementV2} only, since there
+     * the statement is prepared right before execution.
+     * </p>
      *
      * @param connection
      *         connection to be used
@@ -247,6 +253,24 @@ public final void setEscapeProcessing(boolean enable) throws SQLException {
            change of escapeProcessing will ensure that we comply with the specified behaviour. */
     }
 
+    /**
+     * Internal access to forcibly set escape processing.
+     * <p>
+     * The normal method {@link #setEscapeProcessing(boolean)} is a no-op, but {@link FBCallableStatementV2}, which
+     * wraps a {@code FBPreparedStatement}, needs to disable escape processing on the wrapped instance.
+     * </p>
+     *
+     * @param enable
+     *         {@code true} to enable escape processing; {@code false} to disable it
+     * @throws SQLException
+     *         if this method is called on a closed statement
+     * @see #setEscapeProcessing(boolean)
+     * @since 7
+     */
+    void forceEscapeProcessing(@SuppressWarnings("SameParameterValue") boolean enable) throws SQLException {
+        super.setEscapeProcessing(enable);
+    }
+
     public FirebirdParameterMetaData getFirebirdParameterMetaData() throws SQLException {
         return new FBParameterMetaData(fbStatement.getParameterDescriptor(), connection);
     }

src/main/org/firebirdsql/jdbc/FBStatement.java

@@ -897,7 +897,7 @@ private boolean needsScrollableCursorEnabled() {
                && fbStatement.supportsFetchScroll();
     }
 
-    final JdbcEscapeParser getEscapeParser() throws SQLException {
+    JdbcEscapeParser getEscapeParser() throws SQLException {
         return isEscapeProcessing() ? connection.getEscapeParser() : JdbcEscapeParser.noEscapeParser();
     }
 

src/main/org/firebirdsql/jdbc/FirebirdPreparedStatement.java

@@ -1,6 +1,6 @@
 // SPDX-FileCopyrightText: Copyright 2003-2004 Roman Rokytskyy
 // SPDX-FileCopyrightText: Copyright 2005 Gabriel Reid
-// SPDX-FileCopyrightText: Copyright 2014-2024 Mark Rotteveel
+// SPDX-FileCopyrightText: Copyright 2014-2026 Mark Rotteveel
 // SPDX-FileCopyrightText: Copyright 2019 Vasiliy Yashkov
 // SPDX-License-Identifier: LGPL-2.1-or-later OR BSD-3-Clause
 package org.firebirdsql.jdbc;
@@ -17,7 +17,14 @@
  */
 @SuppressWarnings("unused")
 public interface FirebirdPreparedStatement extends FirebirdStatement, PreparedStatement {
- 
+
+    /**
+     * Statement type is not known, or no statement is prepared.
+     *
+     * @since 7
+     */
+    int TYPE_UNKNOWN = 0;
+
     /** A {@code SELECT} or multi-row DML with {@code RETURNING} statement. */
     int TYPE_SELECT = ISCConstants.isc_info_sql_stmt_select;
 

src/main/org/firebirdsql/jdbc/escape/CallEscapeHandling.java

@@ -0,0 +1,21 @@
+// SPDX-FileCopyrightText: Copyright 2026 Mark Rotteveel
+// SPDX-License-Identifier: LGPL-2.1-or-later
+package org.firebirdsql.jdbc.escape;
+
+/**
+ * Handling of call escapes by {@link FBEscapedParser}.
+ *
+ * @since 7
+ */
+public enum CallEscapeHandling {
+
+    /**
+     * Call escapes are processed and converted to {@code EXECUTE PROCEDURE}.
+     */
+    TO_EXECUTE_PROCEDURE,
+    /**
+     * Call escapes are ignored and remain part of the returned statement text.
+     */
+    IGNORED,
+
+}

src/main/org/firebirdsql/jdbc/escape/DisabledEscapeParser.java

@@ -19,6 +19,11 @@ public String toNative(String sql) {
         return sql;
     }
 
+    @Override
+    public JdbcEscapeParser with(CallEscapeHandling callEscapeHandling) {
+        return this;
+    }
+
     static JdbcEscapeParser getInstance() {
         return INSTANCE;
     }

src/main/org/firebirdsql/jdbc/escape/FBEscapedParser.java

@@ -60,14 +60,17 @@ public final class FBEscapedParser implements JdbcEscapeParser {
 
     private final AbstractVersion firebirdVersion;
     private final QuoteStrategy quoteStrategy;
+    private final CallEscapeHandling callEscapeHandling;
 
-    private FBEscapedParser(AbstractVersion firebirdVersion, QuoteStrategy quoteStrategy) {
+    private FBEscapedParser(AbstractVersion firebirdVersion, QuoteStrategy quoteStrategy,
+            CallEscapeHandling callEscapeHandling) {
         this.firebirdVersion = firebirdVersion;
         this.quoteStrategy = quoteStrategy;
+        this.callEscapeHandling = callEscapeHandling;
     }
 
     /**
-     * Get an instance of the escape parser for the specified Firebird version and quote strategy.
+     * Instance of the escape parser for the specified Firebird version and quote strategy, processing call escapes.
      *
      * @param firebirdVersion
      *         Firebird version
@@ -76,8 +79,32 @@ private FBEscapedParser(AbstractVersion firebirdVersion, QuoteStrategy quoteStra
      * @since 7
      */
     public static FBEscapedParser of(AbstractVersion firebirdVersion, QuoteStrategy quoteStrategy) {
-        assert !(firebirdVersion instanceof OdsVersion) : "Do not pass OdsVersion to FBEscapedParser.of(...)";
-        return new FBEscapedParser(firebirdVersion, quoteStrategy);
+        return of(firebirdVersion, quoteStrategy, CallEscapeHandling.TO_EXECUTE_PROCEDURE);
+    }
+
+    /**
+     * Instance of the escape parser for the specified Firebird version, quote strategy, and escape handling.
+     *
+     * @param firebirdVersion
+     *         Firebird version
+     * @param quoteStrategy
+     *         quote strategy
+     * @param callEscapeHandling
+     *         call escape handling
+     * @since 7
+     */
+    public static FBEscapedParser of(AbstractVersion firebirdVersion, QuoteStrategy quoteStrategy,
+            CallEscapeHandling callEscapeHandling) {
+        assert!(firebirdVersion instanceof OdsVersion) : "Do not pass OdsVersion to FBEscapedParser.of(...)";
+        return new FBEscapedParser(firebirdVersion, quoteStrategy, callEscapeHandling);
+    }
+
+    @Override
+    public FBEscapedParser with(CallEscapeHandling callEscapeHandling) {
+        if (this.callEscapeHandling == callEscapeHandling) {
+            return this;
+        }
+        return new FBEscapedParser(firebirdVersion, quoteStrategy, callEscapeHandling);
     }
 
     AbstractVersion firebirdVersion() {
@@ -89,6 +116,11 @@ QuoteStrategy quoteStrategy() {
         return quoteStrategy;
     }
 
+    @SuppressWarnings("unused")
+    CallEscapeHandling callEscapeHandling() {
+        return callEscapeHandling;
+    }
+
     /**
      * Check if the target SQL contains at least one of the escaped syntax commands. This method performs a simple regex
      * match, so it may report that SQL contains escaped syntax when the <code>"&#123;"</code> is followed by
@@ -97,7 +129,7 @@ QuoteStrategy quoteStrategy() {
      *
      * @param sql
      *         to test
-     * @return {@code true} if the {@code sql} is suspected to contain escaped syntax.
+     * @return {@code true} if the {@code sql} seems to contain escaped syntax
      */
     private static boolean checkForEscapes(String sql) {
         return CHECK_ESCAPE_PATTERN.matcher(sql).find();
@@ -281,14 +313,22 @@ private static void toTimestampString(final StringBuilder target, final CharSequ
      * Converts the escaped procedure call syntax into the native procedure call.
      *
      * @param target
-     *         Target StringBuilder to append native procedure call to.
+     *         target StringBuilder to append native procedure call to
      * @param procedureCall
-     *         part of {call proc_name(...)} without curly braces and "call"
-     *         word.
+     *         part of {call proc_name(...)} including curly braces and "call" keyword
      */
-    private void convertProcedureCall(final StringBuilder target, final String procedureCall) throws SQLException {
+    private void convertProcedureCall(StringBuilder target, String procedureCall) throws SQLException {
+        if (callEscapeHandling == CallEscapeHandling.IGNORED) {
+            target.append(procedureCall);
+        } else {
+            convertProcedureCall0(target, procedureCall);
+        }
+    }
+
+    private void convertProcedureCall0(StringBuilder target, String procedureCall) throws SQLException {
         var tempParser = new FBEscapedCallParser(this);
         FBProcedureCall call = tempParser.parseCall(procedureCall);
+        // TODO Should this be called? It result in exceptions, see FBEscapedParserTest#testCallEscapeHandling
         call.checkParameters();
         target.append(call.getSQL(quoteStrategy));
     }

src/main/org/firebirdsql/jdbc/escape/JdbcEscapeParser.java

@@ -17,6 +17,19 @@ public sealed interface JdbcEscapeParser permits DisabledEscapeParser, FBEscaped
 
     String toNative(String sql) throws SQLException;
 
+    /**
+     * Returns an instance with the appropriate call escape handling.
+     * <p>
+     * If call escape handling is already as configured, or if call escape handling is irrelevant, the same instance may
+     * be returned.
+     * </p>
+     *
+     * @param callEscapeHandling
+     *         desired call escape handling
+     * @return appropriate instance
+     */
+    JdbcEscapeParser with(CallEscapeHandling callEscapeHandling);
+
     static JdbcEscapeParser noEscapeParser() {
         return DisabledEscapeParser.getInstance();
     }