#945 jdp-2026-06: Service manager request customization

Author: mrotteveel

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

@@ -0,0 +1,118 @@
+= jdp-2026-06: Service manager request customization
+
+// SPDX-FileCopyrightText: Copyright 2026 Mark Rotteveel
+// SPDX-License-Identifier: LicenseRef-PDL-1.0
+
+== Status
+
+* Draft
+* Proposed for: Jaybird 5.0.13, Jaybird 6.0.6, Jaybird 7
+
+== Type
+
+* Feature-Specification
+
+== Context
+
+When new options are added to Services API operations, users of Jaybird cannot use them without:
+
+. A new Jaybird release providing support
+. Subclassing or duplicating the service manager implementation to add support
+
+Sometimes we only add new features after users explicitly ask for them, or if we notice their absence -- possibly long after the initial introduction in Firebird.
+
+Having some way for Jaybird users to customize the request buffer of an operation before it's executed will allow them to configure options not (yet) supported by Jaybird (or, possibly, correct or work around bugs).
+
+Most operations to be customized go through `FBServiceManager#executeServicesOperation(FbService, ServiceRequestBuffer)`.
+
+Exceptions to this are:
+
+* `FBStreamingBackupManager#backupDatabase`
+* `FBStreamingBackupManager#backupMetadata`
+* `FBStreamingBackupManager#restoreDatabase`
+* Various operations in `FBTraceManager`
+
+(Some might be rewritten to call `executeServicesOperation` instead.)
+
+== Decision
+
+We add a functional interface `org.firebirdsql.management.ServiceRequestCustomizer` with a single method, `customize(ServiceRequestBuffer, ServiceRequestContext)`.
+
+.Parameters of `customize`
+`org.firebirdsql.gds.ServiceRequestBuffer`::
+The parameter buffer to be passed to the start service action method.
++
+This parameter buffer has been populated by the implementation before it is passed to the customizer.
+The customizer may add or remove arguments as needed.
+
+`org.firebirdsql.management.ServiceRequestContext`::
+A class (or interface or record) providing context information.
++
+Initially, we'll only add one accessor:
+
+`String operation()`:::
+The operation name.
+
+`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.
+
+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.
+
+The use of the `ServiceRequestContext` object instead of passing the operation name directly allows for future extension without changing the method signature.
+
+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:
+
+[source,java]
+----
+var backupManager = new FBBackupManager();
+// Perform other config...
+// Set customizer
+backupManager.setServiceRequestCustomizer((request, context) -> {
+    // Only apply for backup
+    if (!"backupDatabase".equals(context.operation())) return;
+    request.addArgument(ISCConstants.isc_spb_bkp_include_data, "ORDER%")
+});
+----
+
+(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.
+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.
+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.
+This could result in Jaybird never or much later receiving such new features.
+We accept that risk.
+
+[appendix]
+== License Notice
+
+The contents of this Documentation are subject to the Public Documentation License Version 1.0 (the “License”);
+you may only use this Documentation if you comply with the terms of this License.
+A copy of the License is available at https://firebirdsql.org/en/public-documentation-license/.
+
+The Original Documentation is "`jdp-2026-06: Service manager request customization`".
+The Initial Writer of the Original Documentation is Mark Rotteveel, Copyright © 2026.
+All Rights Reserved.
+(Initial Writer contact(s): mark (at) lawinegevaar (dot) nl).
+
+////
+Contributor(s): ______________________________________.
+Portions created by ______ are Copyright © _________ [Insert year(s)].
+All Rights Reserved.
+(Contributor contact(s): ________________ [Insert hyperlink/alias]).
+////
+
+The exact file history is recorded in our Git repository;
+see https://github.com/FirebirdSQL/jaybird