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

Backport of #945

Author: mrotteveel

src/docs/asciidoc/release_notes.adoc

@@ -56,6 +56,7 @@ This change was backported from Jaybird 6.0.6.
 * Fixed: Off-by-one error in default value for `maxInlineBlobSize` (https://github.com/FirebirdSQL/jaybird/issues/939[#939])
 +
 Fix was contributed by Artyom Abakumov, and backport from Jaybird 6.0.6.
+* Improvement: Support customization of service requests in service managers (https://github.com/FirebirdSQL/jaybird/issues/947[#947])
 
 [#jaybird-5-0-12-changelog]
 === Jaybird 5.0.12

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

@@ -18,6 +18,7 @@
  */
 package org.firebirdsql.management;
 
+import jdk.jfr.StackTrace;
 import org.firebirdsql.gds.ServiceRequestBuffer;
 import org.firebirdsql.gds.impl.DbAttachInfo;
 import org.firebirdsql.gds.impl.GDSFactory;
@@ -31,14 +32,15 @@
 import java.io.IOException;
 import java.io.OutputStream;
 import java.sql.SQLException;
+import java.util.Arrays;
 import java.util.Map;
 
 import static org.firebirdsql.gds.ISCConstants.isc_info_end;
 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.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.
@@ -52,6 +54,7 @@ public class FBServiceManager implements ServiceManager {
     private final FbDatabaseFactory dbFactory;
     private String database;
     private OutputStream logger;
+    private ServiceRequestCustomizer serviceRequestCustomizer;
 
     public final static int BUFFER_SIZE = 1024; //1K
 
@@ -305,6 +308,16 @@ public synchronized void setLogger(OutputStream logger) {
         this.logger = logger;
     }
 
+    @Override
+    public void setServiceRequestCustomizer(ServiceRequestCustomizer serviceRequestCustomizer) {
+        this.serviceRequestCustomizer = serviceRequestCustomizer;
+    }
+
+    @Override
+    public ServiceRequestCustomizer getServiceRequestCustomizer() {
+        return serviceRequestCustomizer;
+    }
+
     public FbService attachServiceManager() throws SQLException {
         FbService fbService = dbFactory.serviceConnect(serviceProperties);
         fbService.attach();
@@ -410,22 +423,81 @@ public void queueService(FbService service) throws SQLException, IOException {
     @Deprecated
     protected void executeServicesOperation(ServiceRequestBuffer srb) throws SQLException {
         try (FbService service = attachServiceManager()) {
-            service.startServiceAction(srb);
-            queueService(service);
-        } catch (IOException ioe) {
-            throw new SQLException(ioe);
+            executeServicesOperation(service, srb);
         }
     }
 
     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) {
+            ServiceRequestContext 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 StackFrame {
+            final Class<?> clazz;
+            final String methodName;
+
+            StackFrame(String className, String methodName) {
+                Class<?> tempClass;
+                try {
+                    tempClass = Class.forName(className);
+                } catch (ClassNotFoundException e) {
+                    // Shouldn't happen, and if it does, it is likely a class we're not interested in
+                    tempClass = Object.class;
+                }
+                clazz = tempClass;
+                this.methodName = methodName;
+            }
+        }
+        Class<?> serviceManagerClass = getClass();
+        StackFrame lastFrame = null;
+        StackTraceElement[] stackTrace = Thread.currentThread().getStackTrace();
+        // Start at 3 to skip getStackTrace, determineOperation and customize
+        for (int idx = 3; idx < stackTrace.length; idx++) {
+            StackTraceElement currentElement = stackTrace[idx];
+            StackFrame currentFrame = new StackFrame(currentElement.getClassName(), currentElement.getMethodName());
+            if (!currentFrame.clazz.isAssignableFrom(serviceManagerClass)
+                    || !ServiceManager.class.isAssignableFrom(currentFrame.clazz)) {
+                break;
+            }
+            lastFrame = currentFrame;
+        }
+        return lastFrame != null ? lastFrame.methodName : "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);
@@ -220,7 +220,7 @@ private void executeServiceBackupOperation(FbService service, ServiceRequestBuff
 
     private void executeServiceRestoreOperation(FbService service, ServiceRequestBuffer srb) throws SQLException {
         try {
-            service.startServiceAction(srb);
+            service.startServiceAction(customize(srb));
 
             OutputStream currentLogger = getLogger();
             ServiceRequestBuffer infoSRB = service.createServiceRequestBuffer();

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.util.StringUtils.isNullOrEmpty;
 
 /**
  * Implements the Trace/Audit API available new in Firebird 2.5
@@ -150,7 +151,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) {
@@ -181,10 +182,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));
         }
     }
 
@@ -196,10 +194,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));
         }
     }
 
@@ -211,10 +206,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));
         }
     }
 
@@ -223,10 +215,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

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

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

@@ -0,0 +1,53 @@
+/*
+ * 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}.
+ *
+ * @since 5.0.13
+ */
+public final class ServiceRequestContext {
+
+    private final String operation;
+
+    /**
+     * Creates a service request context.
+     *
+     * @param operation
+     *         name of the operation (the initiating service method name)
+     */
+    public ServiceRequestContext(String operation) {
+        this.operation = operation;
+    }
+
+    /**
+     * @return name of the operation
+     */
+    public String operation() {
+        return 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 5.0.13
+ */
+@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);
+
+}