#841 Improve blob performance by combining open and first fetch - backport to Jaybird 5

Author: mrotteveel

src/docs/asciidoc/release_notes.adoc

@@ -29,6 +29,15 @@ Changes per Jaybird 5 release.
 See also <<whats-new-in-jaybird-5>>.
 For known issues, consult <<known-issues>>.
 
+[#jaybird-5-0-7-changelog]
+=== Jaybird 5.0.7
+
+The following has been changed or fixed since Jaybird 5.0.6:
+
+* Improvement: backported deferred blob open optimization from Jaybird 7 (https://github.com/FirebirdSQL/jaybird/issues/841[#841])
++
+See also <<blob-performance-defer-open>>.
+
 [#jaybird-5-0-6-changelog]
 === Jaybird 5.0.6
 
@@ -752,6 +761,24 @@ This is an experimental feature.
 Its API may change in point releases, or it may be removed or replaced entirely in a future major release.
 ====
 
+[#blob-performance]
+=== Blob performance improvements
+
+[#blob-performance-defer-open]
+==== Deferred blob open
+
+Added in: Jaybird 5.0.7, backported from Jaybird 7
+
+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 2.5 and higher.
+
+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.
+
 [#potentially-breaking-changes]
 === Potentially breaking changes
 

src/jna-client/org/firebirdsql/gds/ng/jna/JnaBlob.java

@@ -134,6 +134,7 @@ public void open() throws SQLException {
                 checkDatabaseAttached();
                 checkTransactionActive();
                 checkBlobClosed();
+                clearDeferredException();
 
                 final JnaDatabase db = getDatabase();
                 if (isOutput()) {
@@ -144,11 +145,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;
         }
     }
@@ -185,13 +187,14 @@ public byte[] getSegment(int sizeRequested) throws SQLException {
                 } else if (!(status == 0 || status == ISCConstants.isc_segment)) {
                     processStatusVector();
                 }
+                throwAndClearDeferredException();
             }
             final int actualLengthInt = ((int) actualLength.getValue()) & 0xFFFF;
             final byte[] segment = new byte[actualLengthInt];
             responseBuffer.get(segment);
             return segment;
         } catch (SQLException e) {
-            exceptionListenerDispatcher.errorOccurred(e);
+            errorOccurred(e);
             throw e;
         }
     }
@@ -213,9 +216,10 @@ public void putSegment(byte[] segment) throws SQLException {
 
                 clientLibrary.isc_put_segment(statusVector, getJnaHandle(), (short) segment.length, segment);
                 processStatusVector();
+                throwAndClearDeferredException();
             }
         } catch (SQLException e) {
-            exceptionListenerDispatcher.errorOccurred(e);
+            errorOccurred(e);
             throw e;
         }
     }
@@ -225,15 +229,17 @@ public void seek(int offset, SeekMode seekMode) throws SQLException {
         try (LockCloseable 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;
         }
     }
@@ -245,17 +251,19 @@ public byte[] getBlobInfo(byte[] requestItems, int bufferLength) throws SQLExcep
             try (LockCloseable 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/main/org/firebirdsql/gds/impl/wire/WireProtocolConstants.java

@@ -31,6 +31,14 @@
  */
 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;
 
     /* Operation (packet) types */