Document FirebirdSQL/jaybird#828

Author: mrotteveel

Diff for: src/docs/asciidoc/appendices/connectionproperties/connectionproperties.adoc

@@ -305,11 +305,16 @@ Attempts to create a database if it does not exist.
 See <<ref-create-database-if-not-exist>> for more information.
 
 a|`reportSQLWarnings`
-a|Jaybird specific property ([.since]_Jaybird 6_)
+a|Jaybird specific property ([.since]_Jaybird 6_).
 Possible values (case-insensitive): `ALL` (default), `NONE`.
 Can be used to disable reporting of ``SQLWarning``s.
 See <<ref-report-sql-warnings>> for more information.
 
+a|`socketFactory`
+a|Jaybird specific property ([.since]_Jaybird 6_).
+Sets a custom socket factory for pure Java connections.
+See <<ref-socket-factory>> for more information.
+
 |===
 
 In addition, Jaybird allows using arbitrary Database Parameters Block entries as connection properties (provided they are defined in Jaybird's `DpbItems` and `SpbItems` ([.since]_Jaybird 5_), or `ISCConstants` ([.until]_Jaybird 5_)).

Diff for: src/docs/asciidoc/reference/connection/socketfactory.adoc

@@ -0,0 +1,47 @@
+[#ref-socket-factory]
+=== Custom socket factory
+
+[.since]_Jaybird 6_
+
+A custom socket factory can be specified to customize the creation of the `java.net.Socket` instance of a pure Java database or service connection.
+
+The connection property `socketFactory` accepts the class name of an implementation of `javax.net.SocketFactory`.
+This socket factory is created anew for each connection.
+If `socketFactory` is not specified, Jaybird will use `SocketFactory.getDefault()` as its factory.
+
+The `SocketFactory` implementation must adhere to the following rules:
+
+- The class must have a public constructor accepting a `java.util.Properties` object, or a public no-arg constructor.
+- The implementation of `SocketFactory#createSocket()` must return an unconnected socket;
+the other `createSocket` methods are not called by Jaybird.
++
+If you don't want to implement the other `createSocket` methods, we recommend throwing `java.lang.UnsupportedOperationException` with a clear message from those methods.
+
+It is possible to pass custom connection properties to the socket factory if it has a public single-arg constructor accepting a `Properties` object.
+Jaybird will instantiate the socket factory with a `Properties` object containing _only_ the connection properties with the suffix `@socketFactory` and non-``null`` values;
+non-string values are converted to string.
+In the future, we may also -- selectively -- pass other connection properties, but for now we only expose those properties that are explicitly set for the socket factory.
+
+For example, say we have some custom socket factory called `org.example.CustomProxySocketFactory` with a `CustomProxySocketFactory(Properties)` constructor:
+
+[source,java]
+----
+var props = new Properties()
+props.setProperty("user", "sysdba");
+props.setProperty("password", "masterkey");
+props.setProperty("socketFactory", "org.example.CustomProxySocketFactory");
+props.setProperty("proxyHost@socketFactory", "localhost");
+props.setProperty("proxyPort@socketFactory", "1234");
+props.setProperty("proxyUser@socketFactory", "proxy-user");
+props.setProperty("proxyPassword@socketFactory", "proxy-password");
+
+try (var connection = DriverManager.getConnection(
+        "jdbc:firebird://remoteserver.example.org/db", props)) {
+    // use connection
+}
+----
+
+This will create the specified socket factory, passing a `Properties` object containing *only* the four custom properties ending in `@socketFactory`.
+The other properties -- here `user`, `password` and `socketFactory` -- are *not* passed to the socket factory.
+
+See also https://github.com/FirebirdSQL/jaybird/blob/master/devdoc/jdp/jdp-2024-09-custom-socket-factory-for-pure-java-connections.adoc[jdp-2024-09: Custom socket factory for pure Java connections]

Diff for: src/docs/asciidoc/reference/reference.adoc

@@ -28,6 +28,8 @@ include::connection/clientinfoproperties.adoc[]
 
 include::connection/createdatabaseifnotexist.adoc[]
 
+include::connection/socketfactory.adoc[]
+
 [[ref-statement]]
 == Statement reference