#838 Improve blob performance by combining open and first fetch

Author: mrotteveel

devdoc/jdp/jdp-2025-02-lazy-send-blob-optimizations.adoc

@@ -5,8 +5,8 @@
 
 == Status
 
-* Draft
-* Proposed for: Jaybird 5, Jaybird 6, Jaybird 7
+* Published: 2025-03-13
+* Implemented in: Jaybird 5, Jaybird 6, Jaybird 7
 
 == Type
 

jaybird-native/src/main/java/org/firebirdsql/gds/ng/jna/JnaBlob.java

@@ -1,4 +1,4 @@
-// SPDX-FileCopyrightText: Copyright 2014-2024 Mark Rotteveel
+// SPDX-FileCopyrightText: Copyright 2014-2025 Mark Rotteveel
 // SPDX-License-Identifier: LGPL-2.1-or-later
 package org.firebirdsql.gds.ng.jna;
 
@@ -11,7 +11,6 @@
 import org.firebirdsql.gds.ng.AbstractFbBlob;
 import org.firebirdsql.gds.ng.FbBlob;
 import org.firebirdsql.gds.ng.FbExceptionBuilder;
-import org.firebirdsql.gds.ng.LockCloseable;
 import org.firebirdsql.gds.ng.listeners.DatabaseListener;
 import org.firebirdsql.jaybird.util.ByteArrayHelper;
 import org.firebirdsql.jna.fbclient.FbClientLibrary;
@@ -116,10 +115,11 @@ public void open() throws SQLException {
             } else {
                 bpb = ByteArrayHelper.emptyByteArray();
             }
-            try (LockCloseable ignored = withLock()) {
+            try (var ignored = withLock()) {
                 checkDatabaseAttached();
                 checkTransactionActive();
                 checkBlobClosed();
+                clearDeferredException();
 
                 final JnaDatabase db = getDatabase();
                 if (isOutput()) {
@@ -130,11 +130,12 @@ public void open() throws SQLException {
                             getJnaHandle(), blobId, (short) bpb.length, bpb);
                 }
                 processStatusVector();
-                setOpen(true);
+                setState(BlobState.OPEN);
                 resetEof();
+                throwAndClearDeferredException();
             }
         } catch (SQLException e) {
-            exceptionListenerDispatcher.errorOccurred(e);
+            errorOccurred(e);
             throw e;
         }
     }
@@ -146,7 +147,7 @@ public final boolean isOutput() {
 
     @Override
     public byte[] getSegment(int sizeRequested) throws SQLException {
-        try (LockCloseable ignored = withLock()) {
+        try (var ignored = withLock()) {
             if (sizeRequested <= 0) {
                 throw FbExceptionBuilder.forException(jb_blobGetSegmentNegative)
                         .messageParameter(sizeRequested)
@@ -157,11 +158,12 @@ public byte[] getSegment(int sizeRequested) throws SQLException {
             checkBlobOpen();
             ShortByReference actualLength = new ShortByReference();
             ByteBuffer responseBuffer = getSegment0(sizeRequested, actualLength);
+            throwAndClearDeferredException();
             byte[] segment = new byte[actualLength.getValue() & 0xFFFF];
             responseBuffer.get(segment);
             return segment;
         } catch (SQLException e) {
-            exceptionListenerDispatcher.errorOccurred(e);
+            errorOccurred(e);
             throw e;
         }
     }
@@ -183,7 +185,7 @@ private ByteBuffer getSegment0(int sizeRequested, ShortByReference actualLength)
 
     @Override
     protected int get(final byte[] b, final int off, final int len, final int minLen) throws SQLException {
-        try (LockCloseable ignored = withLock())  {
+        try (var ignored = withLock())  {
             validateBufferLength(b, off, len);
             if (len == 0) return 0;
             if (minLen <= 0 || minLen > len ) {
@@ -206,9 +208,10 @@ protected int get(final byte[] b, final int off, final int len, final int minLen
                 segmentBuffer.get(b, off + count, dataLength);
                 count += dataLength;
             }
+            throwAndClearDeferredException();
             return count;
         } catch (SQLException e) {
-            exceptionListenerDispatcher.errorOccurred(e);
+            errorOccurred(e);
             throw e;
         }
     }
@@ -219,7 +222,7 @@ private int getBlobBufferSize() {
 
     @Override
     public void put(final byte[] b, final int off, final int len) throws SQLException {
-        try (LockCloseable ignored = withLock()) {
+        try (var ignored = withLock()) {
             validateBufferLength(b, off, len);
             if (len == 0) {
                 throw FbExceptionBuilder.toException(jb_blobPutSegmentEmpty);
@@ -249,26 +252,29 @@ public void put(final byte[] b, final int off, final int len) throws SQLExceptio
                 processStatusVector();
                 count += segmentLength;
             }
+            throwAndClearDeferredException();
         } catch (SQLException e) {
-            exceptionListenerDispatcher.errorOccurred(e);
+            errorOccurred(e);
             throw e;
         }
     }
 
     @Override
     public void seek(int offset, SeekMode seekMode) throws SQLException {
-        try (LockCloseable ignored = withLock()) {
+        try (var ignored = withLock()) {
             checkDatabaseAttached();
             checkTransactionActive();
+            checkBlobOpen();
 
             // result is the current position in the blob (see .NET provider source)
             // We ignore the result TODO check if useful; not used in wire protocol either
             IntByReference result = new IntByReference();
             clientLibrary.isc_seek_blob(statusVector, getJnaHandle(), (short) seekMode.getSeekModeId(), offset,
                     result);
             processStatusVector();
+            throwAndClearDeferredException();
         } catch (SQLException e) {
-            exceptionListenerDispatcher.errorOccurred(e);
+            errorOccurred(e);
             throw e;
         }
     }
@@ -277,20 +283,21 @@ public void seek(int offset, SeekMode seekMode) throws SQLException {
     public byte[] getBlobInfo(byte[] requestItems, int bufferLength) throws SQLException {
         try {
             final ByteBuffer responseBuffer;
-            try (LockCloseable ignored = withLock()) {
+            try (var ignored = withLock()) {
                 responseBuffer = getByteBuffer(bufferLength);
                 checkDatabaseAttached();
+                checkBlobOpen();
                 clientLibrary.isc_blob_info(statusVector, getJnaHandle(),
                         (short) requestItems.length, requestItems,
                         (short) bufferLength, responseBuffer);
                 processStatusVector();
+                throwAndClearDeferredException();
             }
-
             byte[] responseArr = new byte[bufferLength];
             responseBuffer.get(responseArr);
             return responseArr;
         } catch (SQLException e) {
-            exceptionListenerDispatcher.errorOccurred(e);
+            errorOccurred(e);
             throw e;
         }
     }

src/docs/asciidoc/release_notes.adoc

@@ -408,6 +408,24 @@ These were previously not explicitly licensed.
 
 For more information, see: https://github.com/FirebirdSQL/jaybird/blob/master/devdoc/jdp/jdp-2025-01-apply-spdx-license-info-and-comply-with-reuse-specification.adoc[jdp-2025-01: Apply SPDX license info and comply with REUSE specification^]
 
+[#blob-performance]
+=== Blob performance improvements
+
+[#blob-performance-defer-open]
+==== Deferred blob open
+
+In the pure Java implementation, performance of reading and writing blobs was improved by deferring the server-side opening or creating of a blob until an actual server-side operation (putting or getting a segment, or getting blob info).
+The open or create blob request is pipelined with the subsequent operation, avoiding a round trip to the server.
+This is especially noticeable in connections with high latency.
+
+Artificial testing on local WiFi with small blobs shows around 85% increase in throughput (comparing a 6.0.1-SNAPSHOT against 6.0.0).
+
+This optimization is available for Firebird 2.1 and higher, but formally only supported for Firebird 3.0 and higher.
+
+This optimization was backported to Jaybird 5.0.7 and Jaybird 6.0.1.
+
+For native connections, a similar optimization -- but only for reading blobs -- is available when using a Firebird 5.0.2 or higher fbclient, independent of the Jaybird version.
+
 // TODO add major changes
 
 [#other-fixes-and-changes]

src/main/org/firebirdsql/gds/impl/wire/WireProtocolConstants.java

@@ -19,6 +19,14 @@
 @SuppressWarnings({ "unused", "java:S115", "java:S1214" })
 public interface WireProtocolConstants {
 
+    /**
+     * Object handle id that can be used to refer to a just created server-side object (for protocol versions supporting
+     * {@link #ptype_lazy_send}).
+     * <p>
+     * This can be used to pipeline the creation of an object with the subsequent use of that object without waiting on
+     * the server response with the actual handle id.
+     * </p>
+     */
     int INVALID_OBJECT = 0xFFFF;
 
     int op_void = 0;