#946 Provide service managers with a way to customize request buffers

Backport of #945

Author: mrotteveel

src/docs/asciidoc/release_notes.adoc

@@ -51,6 +51,7 @@ See also <<compat-legacy-auth>>.
 Fix was contributed by Artyom Abakumov.
 * Fixed: `NullPointerException` on authentication failure with non-existent user and single plugin in `AuthServer` (https://github.com/FirebirdSQL/jaybird/issues/940[#940])
 * Dependency update: updated `org.bouncycastle:bcprov-jdk18on` from 1.83 to 1.84 (used by `chacha64-plugin`) (https://github.com/FirebirdSQL/jaybird/issues/941[#941])
+* Improvement: Support customization of service requests in service managers (https://github.com/FirebirdSQL/jaybird/issues/946[#946])
 
 === Jaybird 6.0.5
 

src/main/org/firebirdsql/management/FBServiceManager.java

@@ -27,6 +27,7 @@
 import org.firebirdsql.jaybird.props.PropertyConstants;
 import org.firebirdsql.jaybird.props.PropertyNames;
 import org.firebirdsql.jaybird.props.def.ConnectionProperty;
+import org.jspecify.annotations.Nullable;
 
 import java.io.IOException;
 import java.io.OutputStream;
@@ -37,9 +38,9 @@
 import static org.firebirdsql.gds.ISCConstants.isc_info_svc_to_eof;
 import static org.firebirdsql.gds.ISCConstants.isc_info_truncated;
 import static org.firebirdsql.gds.ISCConstants.isc_infunk;
+import static org.firebirdsql.gds.VaxEncoding.iscVaxInteger2;
 import static org.firebirdsql.jaybird.fb.constants.SpbItems.isc_spb_dbname;
 import static org.firebirdsql.jaybird.fb.constants.SpbItems.isc_spb_options;
-import static org.firebirdsql.gds.VaxEncoding.iscVaxInteger2;
 
 /**
  * An implementation of the basic Firebird Service API functionality.
@@ -53,6 +54,7 @@ public class FBServiceManager implements ServiceManager {
     private final FbDatabaseFactory dbFactory;
     private String database;
     private OutputStream logger;
+    private @Nullable ServiceRequestCustomizer serviceRequestCustomizer;
 
     public static final int BUFFER_SIZE = 1024; //1K
 
@@ -310,6 +312,16 @@ public synchronized void setLogger(OutputStream logger) {
         this.logger = logger;
     }
 
+    @Override
+    public void setServiceRequestCustomizer(@Nullable ServiceRequestCustomizer serviceRequestCustomizer) {
+        this.serviceRequestCustomizer = serviceRequestCustomizer;
+    }
+
+    @Override
+    public @Nullable ServiceRequestCustomizer getServiceRequestCustomizer() {
+        return serviceRequestCustomizer;
+    }
+
     public FbService attachServiceManager() throws SQLException {
         FbService fbService = dbFactory.serviceConnect(serviceProperties);
         fbService.attach();
@@ -403,13 +415,57 @@ public void queueService(FbService service) throws SQLException, IOException {
      */
     protected final void executeServicesOperation(FbService service, ServiceRequestBuffer srb) throws SQLException {
         try {
-            service.startServiceAction(srb);
+            service.startServiceAction(customize(srb));
             queueService(service);
         } catch (IOException ioe) {
             throw new SQLException(ioe);
         }
     }
 
+    /**
+     * Customizes the service request buffer, if a customizer was set.
+     *
+     * @param srb
+     *         service request buffer
+     * @return {@code srb}, possibly modified
+     * @throws SQLException
+     *         for exceptions thrown by the service request customizer
+     * @see #setServiceRequestCustomizer(ServiceRequestCustomizer)
+     * @since 6.0.5
+     */
+    protected final ServiceRequestBuffer customize(ServiceRequestBuffer srb) throws SQLException {
+        ServiceRequestCustomizer customizer = serviceRequestCustomizer;
+        if (customizer != null) {
+            var context = new ServiceRequestContext(determineOperation());
+            try {
+                customizer.customize(srb, context);
+            } catch (RuntimeException e) {
+                throw new SQLException("Service request terminated by ServiceRequestCustomizer", e);
+            }
+        }
+        return srb;
+    }
+
+    /**
+     * Determines the service operation in this call chain.
+     *
+     * @return service operation
+     */
+    private String determineOperation() {
+        Class<?> serviceManagerClass = getClass();
+        return StackWalker.getInstance(StackWalker.Option.RETAIN_CLASS_REFERENCE)
+                .walk(frames -> frames
+                        // Skip determineOperation and customize
+                        .skip(2)
+                        // Determine method calls within this service manager
+                        .takeWhile(f -> f.getDeclaringClass().isAssignableFrom(serviceManagerClass)
+                                && ServiceManager.class.isAssignableFrom(f.getDeclaringClass()))
+                        // Obtain the last stack frame in the stream, which is the initiating operation
+                        .reduce((first, second) -> second)
+                        .map(StackWalker.StackFrame::getMethodName)
+                        .orElse("unknown"));
+    }
+
     protected ServiceRequestBuffer createRequestBuffer(FbService service, int operation, int options) {
         ServiceRequestBuffer srb = service.createServiceRequestBuffer();
         srb.addArgument(operation);

src/main/org/firebirdsql/management/FBStreamingBackupManager.java

@@ -185,7 +185,7 @@ protected void addBackupsToRestoreRequestBuffer(FbService service, ServiceReques
 
     private void executeServiceBackupOperation(FbService service, ServiceRequestBuffer srb) throws SQLException {
         try {
-            service.startServiceAction(srb);
+            service.startServiceAction(customize(srb));
 
             ServiceRequestBuffer infoSRB = service.createServiceRequestBuffer();
             infoSRB.addArgument(isc_info_svc_to_eof);
@@ -224,7 +224,7 @@ private void executeServiceRestoreOperation(FbService service, ServiceRequestBuf
             throw new SQLException("Verbose mode was requested but there is no logger provided.");
         }
         try {
-            service.startServiceAction(srb);
+            service.startServiceAction(customize(srb));
 
             ServiceRequestBuffer infoSRB = service.createServiceRequestBuffer();
             infoSRB.addArgument(isc_info_svc_stdin);

src/main/org/firebirdsql/management/FBTraceManager.java

@@ -29,6 +29,7 @@
 import java.util.Map;
 
 import static org.firebirdsql.gds.ISCConstants.*;
+import static org.firebirdsql.jaybird.util.StringUtils.isNullOrEmpty;
 
 /**
  * Implements the Trace/Audit API available new in Firebird 2.5
@@ -148,7 +149,7 @@ private ServiceRequestBuffer getTraceSPB(FbService service, int action, String t
      *         Firebird installation
      */
     public void startTraceSession(String traceSessionName, String configuration) throws SQLException {
-        if (configuration == null || configuration.equals("")) {
+        if (isNullOrEmpty(configuration)) {
             throw new SQLException("No configuration provided");
         }
         if (traceSessionName == null) {
@@ -179,10 +180,7 @@ public void startTraceSession(String traceSessionName, String configuration) thr
      */
     public void stopTraceSession(int traceSessionId) throws SQLException {
         try (FbService service = attachServiceManager()) {
-            service.startServiceAction(getTraceSPB(service, isc_action_svc_trace_stop, traceSessionId));
-            queueService(service);
-        }  catch (IOException ioe) {
-            throw new SQLException(ioe);
+            executeServicesOperation(service, getTraceSPB(service, isc_action_svc_trace_stop, traceSessionId));
         }
     }
 
@@ -194,10 +192,7 @@ public void stopTraceSession(int traceSessionId) throws SQLException {
      */
     public void suspendTraceSession(int traceSessionId) throws SQLException {
         try (FbService service = attachServiceManager()) {
-            service.startServiceAction(getTraceSPB(service, isc_action_svc_trace_suspend, traceSessionId));
-            queueService(service);
-        }  catch (IOException ioe) {
-            throw new SQLException(ioe);
+            executeServicesOperation(service, getTraceSPB(service, isc_action_svc_trace_suspend, traceSessionId));
         }
     }
 
@@ -209,10 +204,7 @@ public void suspendTraceSession(int traceSessionId) throws SQLException {
      */
     public void resumeTraceSession(int traceSessionId) throws SQLException {
         try (FbService service = attachServiceManager()) {
-            service.startServiceAction(getTraceSPB(service, isc_action_svc_trace_resume, traceSessionId));
-            queueService(service);
-        }  catch (IOException ioe) {
-            throw new SQLException(ioe);
+            executeServicesOperation(service, getTraceSPB(service, isc_action_svc_trace_resume, traceSessionId));
         }
     }
 
@@ -221,10 +213,7 @@ public void resumeTraceSession(int traceSessionId) throws SQLException {
      */
     public void listTraceSessions() throws SQLException {
         try (FbService service = attachServiceManager()) {
-            service.startServiceAction(getTraceSPB(service, isc_action_svc_trace_list));
-            queueService(service);
-        }  catch (IOException ioe) {
-            throw new SQLException(ioe);
+            executeServicesOperation(service, getTraceSPB(service, isc_action_svc_trace_list));
         }
     }
 

src/main/org/firebirdsql/management/ServiceManager.java

@@ -28,6 +28,7 @@
 import org.firebirdsql.gds.ng.WireCrypt;
 import org.firebirdsql.jaybird.props.AttachmentProperties;
 import org.firebirdsql.jaybird.props.ServiceConnectionProperties;
+import org.jspecify.annotations.Nullable;
 
 import java.io.OutputStream;
 import java.sql.SQLException;
@@ -132,6 +133,32 @@ public interface ServiceManager extends ServiceConnectionProperties {
      */
     void setLogger(OutputStream logger);
 
+    /**
+     * Sets a service request customizer on this service manager. This replaces any previously set customizer.
+     * <p>
+     * The customizer is called just before the request is sent to the server, allowing users to modify the request.
+     * </p>
+     * <p>
+     * If you set a customizer to access a feature not implemented by Jaybird, please consider creating an improvement
+     * ticket on <a href="https://github.com/FirebirdSQL/jaybird/issues">the Jaybird GitHub repository</a> as well.
+     * </p>
+     *
+     * @param customizer
+     *         service request customizer, {@code null} to remove a previous customizer
+     * @see #getServiceRequestCustomizer()
+     * @see ServiceRequestCustomizer
+     * @since 6.0.5
+     */
+    void setServiceRequestCustomizer(@Nullable ServiceRequestCustomizer customizer);
+
+    /**
+     * @return service request customizer, {@code null} if none set
+     * @see #setServiceRequestCustomizer(ServiceRequestCustomizer)
+     * @since 6.0.5
+     */
+    @Nullable ServiceRequestCustomizer getServiceRequestCustomizer();
+
+
     /**
      * Obtains the server version through a service call.
      *

src/main/org/firebirdsql/management/ServiceRequestContext.java

@@ -0,0 +1,35 @@
+/*
+ * Public Firebird Java API.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *    1. Redistributions of source code must retain the above copyright notice,
+ *       this list of conditions and the following disclaimer.
+ *    2. Redistributions in binary form must reproduce the above copyright
+ *       notice, this list of conditions and the following disclaimer in the
+ *       documentation and/or other materials provided with the distribution.
+ *    3. The name of the author may not be used to endorse or promote products
+ *       derived from this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED
+ * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+ * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
+ * EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+ * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
+ * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
+ * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
+ * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+ * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+package org.firebirdsql.management;
+
+/**
+ * Context information about a service request for {@link ServiceRequestCustomizer}.
+ *
+ * @param operation
+ *         name of the operation (the initiating service method name)
+ * @since 6.0.5
+ */
+public record ServiceRequestContext(String operation) {
+}

src/main/org/firebirdsql/management/ServiceRequestCustomizer.java

@@ -0,0 +1,65 @@
+/*
+ * Public Firebird Java API.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *    1. Redistributions of source code must retain the above copyright notice,
+ *       this list of conditions and the following disclaimer.
+ *    2. Redistributions in binary form must reproduce the above copyright
+ *       notice, this list of conditions and the following disclaimer in the
+ *       documentation and/or other materials provided with the distribution.
+ *    3. The name of the author may not be used to endorse or promote products
+ *       derived from this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED
+ * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+ * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
+ * EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+ * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
+ * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
+ * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
+ * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+ * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+package org.firebirdsql.management;
+
+import org.firebirdsql.gds.ServiceRequestBuffer;
+
+/**
+ * Functional interface for modifying service requests.
+ * <p>
+ * This can be used to modify service requests before they are sent to the server, for example to access features not
+ * currently supported by Jaybird.
+ * </p>
+ * <p>
+ * If you implement this interface to access a feature not implemented by Jaybird, please consider creating an
+ * improvement ticket on <a href="https://github.com/FirebirdSQL/jaybird/issues">the Jaybird GitHub repository</a> as
+ * well.
+ * </p>
+ *
+ * @see ServiceManager#setServiceRequestCustomizer(ServiceRequestCustomizer)
+ * @since 6.0.5
+ */
+@FunctionalInterface
+public interface ServiceRequestCustomizer {
+
+    /**
+     * Provides access to, and allows customization of, a service request.
+     * <p>
+     * Called by the service manager just before the request is sent to the server. Exceptions thrown by the customizer
+     * terminate the service request before it's sent to the server.
+     * </p>
+     * <p>
+     * Incorrect use (e.g. adding wrong arguments or values, removing or replacing arguments, etc.) may result in
+     * errors on Firebird or in Jaybird.
+     * </p>
+     *
+     * @param serviceRequest
+     *         service request buffer populated by the service manager, to be modified by this customizer
+     * @param requestContext
+     *         service request context information
+     */
+    void customize(ServiceRequestBuffer serviceRequest, ServiceRequestContext requestContext);
+
+}

src/test/org/firebirdsql/management/FBBackupManagerTest.java

@@ -68,6 +68,7 @@ class FBBackupManagerTest {
     final UsesDatabaseExtension.UsesDatabaseForEach usesDatabase = UsesDatabaseExtension.noDatabase();
 
     private BackupManager backupManager;
+    private final GetServiceRequestContext getServiceRequestContext = new GetServiceRequestContext();
     @TempDir
     Path tempFolder;
 
@@ -89,6 +90,7 @@ void setUp() {
         backupManager.setParallelWorkers(2);
         backupManager.setLogger(System.out);
         backupManager.setVerbose(true);
+        backupManager.setServiceRequestCustomizer(getServiceRequestContext);
     }
 
     private String getBackupPath() {
@@ -108,18 +110,32 @@ void testBackup() throws Exception {
         usesDatabase.createDefaultDatabase();
         backupManager.backupDatabase();
 
-        final Path restorePath = tempFolder.resolve("testrestore.fdb");
+        getServiceRequestContext.assertLastOperation("backupDatabase");
 
         backupManager.clearRestorePaths();
+        final Path restorePath = tempFolder.resolve("testrestore.fdb");
         usesDatabase.addDatabase(restorePath.toString());
         backupManager.setDatabase(restorePath.toString());
         backupManager.restoreDatabase();
 
+        getServiceRequestContext.assertLastOperation("restoreDatabase");
         try (var c = DriverManager.getConnection(getUrl(restorePath), getDefaultPropertiesForConnection())) {
             assertTrue(c.isValid(0));
         }
     }
 
+    @Test
+    void testBackupMetadata() throws Exception {
+        usesDatabase.createDefaultDatabase();
+        backupManager.clearBackupPaths();
+        final Path backupPath = tempFolder.resolve("testmetadatabackup.fbk");
+        backupManager.setBackupPath(backupPath.toString());
+        backupManager.backupMetadata();
+
+        assertTrue(Files.isRegularFile(backupPath), "Expected file to exist");
+        getServiceRequestContext.assertLastOperation("backupMetadata");
+    }
+
     @Test
     void testSetBadBufferCount() {
         assertThrows(IllegalArgumentException.class, () -> backupManager.setRestorePageBufferCount(-1),