#842 Improve blob performance by combining open and first fetch - backport to Jaybird 6

Author: mrotteveel

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

@@ -27,7 +27,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;
@@ -132,10 +131,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()) {
@@ -146,11 +146,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;
         }
     }
@@ -162,7 +163,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)
@@ -173,11 +174,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;
         }
     }
@@ -199,7 +201,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 ) {
@@ -222,9 +224,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;
         }
     }
@@ -235,7 +238,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);
@@ -265,26 +268,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;
         }
     }
@@ -293,20 +299,22 @@ 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

@@ -37,7 +37,9 @@ For known issues, consult <<known-issues>>.
 
 The following was fixed or changed since Jaybird 6.0.0:
 
-* ...
+* Improvement: backported deferred blob open optimization from Jaybird 7 (https://github.com/FirebirdSQL/jaybird/issues/842[#842])
++
+See also <<blob-performance-defer-open>>.
 
 === Jaybird 6.0.0
 
@@ -774,6 +776,21 @@ If the length is larger than the maximum segment size, or if the offset is non-z
 
 Similar to the improvements for reading, we were also able to realise some other optimizations (in both pure Java and JNA), by avoiding allocation of a number of intermediate objects, but this has only marginal effects on the throughput.
 
+[#blob-performance-defer-open]
+==== Deferred blob open
+
+Added in: Jaybird 6.0.1, 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 3.0 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.
+
 [#blob-performance-min-buf]
 ==== Minimum `blobBufferSize` 512 bytes
 

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

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