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

Author: mrotteveel

devdoc/jdp/jdp-2026-06-service-manager-request-customization.adoc

@@ -5,8 +5,8 @@
 
 == Status
 
-* Draft
-* Proposed for: Jaybird 5.0.13, Jaybird 6.0.6, Jaybird 7
+* Published: 2026-06-30
+* Implemented in: Jaybird 5.0.13, Jaybird 6.0.6, Jaybird 7
 
 == Type
 
@@ -32,7 +32,7 @@ Exceptions to this are:
 * `FBStreamingBackupManager#restoreDatabase`
 * Various operations in `FBTraceManager`
 
-(Some might be rewritten to call `executeServicesOperation` instead.)
+(Some can be rewritten to call `executeServicesOperation` instead.)
 
 == Decision
 
@@ -53,16 +53,18 @@ Initially, we'll only add one accessor:
 `String operation()`:::
 The operation name.
 
+The use of the `ServiceRequestContext` object instead of passing the operation name directly allows for future extension without changing the method signature.
+
 `ServiceManager` receives a property for the `ServiceRequestCustomizer`, and implementations call the customizer before starting the service action.
 Implementations that previously did not call `executeServicesOperation` are either rewritten to call it, or are changed to call the customizer themselves.
 
 The operation name is generally the name of the API method initiating the operation.
-For example, it reports the method name of the caller of `executeServicesOperation`.
-Bar bugs, like deeper callstacks than assumed, the operation names are stable as these are the methods defined in the API of the various service manager interfaces.
+For example, it reports the entry point method name into the service manager (i.e. the first method called on the service manager by user code).
+For example, calling `BackupManager.backupDatabase()` or `backupDatabase(int)` reports `backupDatabase`, while calling `backupMetadata()` reports operation `backupMetadata` (even though that method calls `backupDatabase(int)`).
 
-Alternatively, a customizer can look at the first argument in the service request buffer (the action), or use solutions like `java.lang.StackWalker` to look at the callstack.
+Bar bugs, the operation names are stable as these are the methods defined in the API of the various service manager interfaces.
 
-The use of the `ServiceRequestContext` object instead of passing the operation name directly allows for future extension without changing the method signature.
+Alternatively, a customizer can look at the first argument in the service request buffer (the action), or use solutions like `java.lang.StackWalker` to look at the callstack.
 
 For example, the gbak `-INCLUDE_DATA` support added to Jaybird 7 by https://github.com/FirebirdSQL/jaybird/issues/944[#944] can also be realized with:
 
@@ -78,17 +80,16 @@ backupManager.setServiceRequestCustomizer((request, context) -> {
 });
 ----
 
-(Above example is tentative, and might differ from actual implementation.)
-
 == Consequences
 
-The addition of `ServiceRequestCustomizer` will provide users with an escape hatch for missing features.
+The addition of `ServiceRequestCustomizer` provides users with an escape hatch for missing features.
 As we consider this a feature of last resort, it is only documented in the API docs, and receives minimal coverage in the release notes.
 It will not be documented in the Jaybird manual.
 This decision may be revisited in the future.
 
 The customizer gives full control over the service request buffer.
-This means that users can change the action performed or make other additions or changes that can can result in errors from the server if wrong information is put in the request buffer.
+This means that users can also change the action performed or make other additions or changes.
+This can can result in errors from the server if wrong information is put in the request buffer.
 Jaybird may also produce errors if the changes result in different service output than expected by the implementation in Jaybird.
 
 Providing this customization feature may result in users implementing their own workarounds, and never reporting an improvement request.

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

@@ -28,9 +28,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.
@@ -44,6 +44,7 @@ public class FBServiceManager implements ServiceManager {
     private final FbDatabaseFactory dbFactory;
     private @Nullable String database;
     private @Nullable OutputStream logger;
+    private @Nullable ServiceRequestCustomizer serviceRequestCustomizer;
 
     public static final int BUFFER_SIZE = 1024; //1K
 
@@ -287,6 +288,16 @@ public synchronized void setLogger(@Nullable 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();
@@ -380,13 +391,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 7
+     */
+    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

@@ -178,7 +178,7 @@ protected void addBackupsToRestoreRequestBuffer(FbService service, ServiceReques
     private void executeServiceBackupOperation(FbService service, ServiceRequestBuffer srb,
             OutputStream backupOutputStream) throws SQLException {
         try {
-            service.startServiceAction(srb);
+            service.startServiceAction(customize(srb));
 
             ServiceRequestBuffer infoSRB = service.createServiceRequestBuffer();
             infoSRB.addArgument(isc_info_svc_to_eof);
@@ -218,7 +218,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

@@ -1,5 +1,5 @@
 // SPDX-FileCopyrightText: Copyright 2009 Thomas Steinmaurer
-// SPDX-FileCopyrightText: Copyright 2012-2024 Mark Rotteveel
+// SPDX-FileCopyrightText: Copyright 2012-2026 Mark Rotteveel
 // SPDX-License-Identifier: LGPL-2.1-or-later
 package org.firebirdsql.management;
 
@@ -168,10 +168,7 @@ public void startTraceSession(@Nullable String traceSessionName, String configur
      */
     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));
         }
     }
 
@@ -183,10 +180,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));
         }
     }
 
@@ -198,10 +192,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));
         }
     }
 
@@ -210,10 +201,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

@@ -79,6 +79,31 @@ public interface ServiceManager extends ServiceConnectionProperties {
      */
     void setLogger(@Nullable 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 7
+     */
+    void setServiceRequestCustomizer(@Nullable ServiceRequestCustomizer customizer);
+
+    /**
+     * @return service request customizer, {@code null} if none set
+     * @see #setServiceRequestCustomizer(ServiceRequestCustomizer)
+     * @since 7
+     */
+    @Nullable ServiceRequestCustomizer getServiceRequestCustomizer();
+
     /**
      * Obtains the server version through a service call.
      *

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

@@ -0,0 +1,13 @@
+// SPDX-FileCopyrightText: Copyright 2026 Mark Rotteveel
+// SPDX-License-Identifier: LGPL-2.1-or-later OR BSD-3-Clause
+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 7
+ */
+public record ServiceRequestContext(String operation) {
+}

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

@@ -0,0 +1,43 @@
+// SPDX-FileCopyrightText: Copyright 2026 Mark Rotteveel
+// SPDX-License-Identifier: LGPL-2.1-or-later OR BSD-3-Clause
+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 7
+ */
+@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

@@ -36,12 +36,10 @@
 import java.sql.DriverManager;
 import java.sql.SQLException;
 import java.sql.Statement;
-import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
 import java.util.function.Function;
 import java.util.function.Predicate;
-import java.util.stream.Collectors;
 import java.util.stream.Stream;
 
 import static java.util.stream.Collectors.toMap;
@@ -71,6 +69,7 @@ class FBBackupManagerTest {
     final UsesDatabaseExtension.UsesDatabaseForEach usesDatabase = UsesDatabaseExtension.noDatabase();
 
     private BackupManager backupManager;
+    private final GetServiceRequestContext getServiceRequestContext = new GetServiceRequestContext();
     @TempDir(factory = MappedTempDirFactory.class)
     Path tempFolder;
 
@@ -89,6 +88,7 @@ void setUp() {
         backupManager.setParallelWorkers(2);
         backupManager.setLogger(System.out);
         backupManager.setVerbose(true);
+        backupManager.setServiceRequestCustomizer(getServiceRequestContext);
     }
 
     private void createTestTable() throws SQLException {
@@ -103,19 +103,33 @@ void testBackup() throws Exception {
         usesDatabase.createDefaultDatabase();
         backupManager.backupDatabase();
 
-        MappedPath restorePath = getTempPath("testrestore.fdb");
+        getServiceRequestContext.assertLastOperation("backupDatabase");
 
         backupManager.clearRestorePaths();
+        MappedPath restorePath = getTempPath("testrestore.fdb");
         String restorePathString = restorePath.toServerPath();
         usesDatabase.addDatabase(restorePathString);
         backupManager.setDatabase(restorePathString);
         backupManager.restoreDatabase();
 
+        getServiceRequestContext.assertLastOperation("restoreDatabase");
         try (var c = DriverManager.getConnection(getUrl(restorePathString), getDefaultPropertiesForConnection())) {
             assertTrue(c.isValid(0));
         }
     }
 
+    @Test
+    void testBackupMetadata() throws Exception {
+        usesDatabase.createDefaultDatabase();
+        backupManager.clearBackupPaths();
+        MappedPath backupPath = getTempPath("testmetadatabackup.fbk");
+        backupManager.setBackupPath(backupPath.toServerPath());
+        backupManager.backupMetadata();
+
+        assertTrue(Files.isRegularFile(backupPath.local()), "Expected local file to exist");
+        getServiceRequestContext.assertLastOperation("backupMetadata");
+    }
+
     @Test
     void testSetBadBufferCount() {
         assertThrows(IllegalArgumentException.class, () -> backupManager.setRestorePageBufferCount(-1),
@@ -514,7 +528,6 @@ private static <T extends ObjectReference> Predicate<T> hasSchema(String schemaN
         return (T ref) -> ref.size() >= 2 && ref.first().name().equals(schemaName);
     }
 
-
     private MappedPath getTempPath(String name) {
         Path localPath = tempFolder.resolve(name);
         Path serverPath = transformMappedToDatabasePath(localPath).orElseThrow();