Add nullability to FBCachedBlob

Author: mrotteveel

src/docs/asciidoc/release_notes.adoc

@@ -868,6 +868,8 @@ use constructor `RowDescriptor(List<FieldDescriptor>, DatatypeCoder)`
 * `RowDescriptorBuilder`
 ** `toRowDescriptor()` can no longer build an incomplete row descriptor, and throws an `IllegalStateException` if one or more fields have not been defined.
 There is no replacement to build incomplete row descriptors.
+* `FBCachedBlob`
+** Constructor `FBCachedBlob(byte[])` no longer accepts `null`.
 
 [#breaking-changes-unlikely]
 === Unlikely breaking changes

src/main/org/firebirdsql/jdbc/FBCachedBlob.java

@@ -1,19 +1,22 @@
 /*
  SPDX-FileCopyrightText: Copyright 2002-2003 Blas Rodriguez Somoza
  SPDX-FileCopyrightText: Copyright 2003-2007 Roman Rokytskyy
- SPDX-FileCopyrightText: Copyright 2014-2024 Mark Rotteveel
+ SPDX-FileCopyrightText: Copyright 2014-2026 Mark Rotteveel
  SPDX-License-Identifier: LGPL-2.1-or-later
 */
 package org.firebirdsql.jdbc;
 
 import org.firebirdsql.gds.JaybirdErrorCodes;
 import org.firebirdsql.gds.ng.FbExceptionBuilder;
 import org.firebirdsql.util.InternalApi;
+import org.jspecify.annotations.NullMarked;
 
 import java.sql.SQLException;
 import java.sql.Blob;
 import java.io.*;
 
+import static java.util.Objects.requireNonNull;
+
 /**
  * This class represents a cached blob field.
  * <p>
@@ -22,6 +25,7 @@
  * </p>
  */
 @InternalApi
+@NullMarked
 public final class FBCachedBlob implements FirebirdBlob {
 
     // NOTE: Do not assign ByteArrayHelper.empty(), as this must be a unique instance
@@ -35,15 +39,15 @@ public final class FBCachedBlob implements FirebirdBlob {
      * Create an instance using the cached data.
      *
      * @param data
-     *            array of bytes containing the cached data.
+     *         array of bytes containing the cached data
      */
     public FBCachedBlob(byte[] data) {
-        blobData = data;
+        blobData = requireNonNull(data, "data");
     }
 
     @Override
     public FirebirdBlob detach() throws SQLException {
-        checkClosed();
+        checkOpen();
         return new FBCachedBlob(blobData);
     }
 
@@ -55,23 +59,22 @@ public FirebirdBlob detach() throws SQLException {
      */
     @Override
     public boolean isSegmented() throws SQLException {
-        checkClosed();
+        checkOpen();
         return false;
     }
 
     /**
      * Get the length of the cached blob field.
      *
-     * @return length of the cached blob field or -1 if the field is null.
+     * @return length of the cached blob field
      */
     @Override
     public long length() throws SQLException {
-        checkClosed();
-        return blobData != null ? blobData.length : -1;
+        checkOpen();
+        return blobData.length;
     }
 
     @Override
-    @SuppressWarnings("java:S1168")
     public byte[] getBytes(long pos, int length) throws SQLException {
         if (pos < 1) {
             throw new SQLException("Expected value of pos > 0, got " + pos,
@@ -81,8 +84,7 @@ public byte[] getBytes(long pos, int length) throws SQLException {
             throw new SQLException("Expected value of length >= 0, got " + length,
                     SQLStateConstants.SQL_STATE_INVALID_STRING_LENGTH);
         }
-        checkClosed();
-        if (blobData == null) return null;
+        checkOpen();
 
         // TODO What if pos or length are beyond blobData
         byte[] result = new byte[length];
@@ -92,8 +94,8 @@ public byte[] getBytes(long pos, int length) throws SQLException {
 
     @Override
     public byte[] getBytes() throws SQLException {
-        checkClosed();
-        return blobData != null ? blobData.clone() : null;
+        checkOpen();
+        return blobData.clone();
     }
 
     /**
@@ -120,9 +122,7 @@ public long position(Blob pattern, long start) throws SQLException {
 
     @Override
     public InputStream getBinaryStream() throws SQLException {
-        checkClosed();
-        if (blobData == null) return null;
-
+        checkOpen();
         return new ByteArrayInputStream(blobData);
     }
 
@@ -180,7 +180,7 @@ public void free() throws SQLException {
         blobData = FREED_MARKER;
     }
 
-    private void checkClosed() throws SQLException {
+    private void checkOpen() throws SQLException {
         if (blobData == FREED_MARKER) {
             throw FbExceptionBuilder.toException(JaybirdErrorCodes.jb_blobClosed);
         }

src/test/org/firebirdsql/jdbc/FBCachedBlobTest.java

@@ -1,4 +1,4 @@
-// SPDX-FileCopyrightText: Copyright 2014-2023 Mark Rotteveel
+// SPDX-FileCopyrightText: Copyright 2014-2026 Mark Rotteveel
 // SPDX-License-Identifier: LGPL-2.1-or-later
 package org.firebirdsql.jdbc;
 
@@ -45,14 +45,10 @@ void testIsSegmented() throws Exception {
         assertFalse(blob.isSegmented(), "FBCachedBlob.isSegmented() should return false");
     }
 
-    /**
-     * Test if {@link FBCachedBlob#length()} returns {@code -1} if data is {@code null}.
-     */
     @Test
-    void testLength_null() throws Exception {
-        FBCachedBlob blob = new FBCachedBlob(null);
-
-        assertEquals(-1, blob.length(), "Unexpected length for null data");
+    @SuppressWarnings("DataFlowIssue")
+    void createBlobWithNull_notAllowed() {
+        assertThrows(NullPointerException.class, () -> new FBCachedBlob(null));
     }
 
     /**
@@ -120,19 +116,6 @@ void testGetBytes_length0() throws Exception {
         assertEquals(0, data.length, "Expected empty (zero-length) array");
     }
 
-    /**
-     * Test if {@link FBCachedBlob#getBytes(long, int)} returns {@code null} if data is null.
-     * <p>
-     * TODO: Not certain if this behavior is allowed!
-     * </p>
-     */
-    @Test
-    void testGetBytes_long_int_null() throws Exception {
-        FBCachedBlob blob = new FBCachedBlob(null);
-
-        assertNull(blob.getBytes(1, 1));
-    }
-
     /**
      * Test {@link FBCachedBlob#getBytes(long, int)}.
      */
@@ -157,19 +140,6 @@ void testGetBytes() throws Exception {
         assertNotSame(input, data, "Expected copy of input, not same object");
     }
 
-    /**
-     * Test if {@link FBCachedBlob#getBytes()} returns {@code null} if data is null.
-     * <p>
-     * TODO: Not certain if this behavior is allowed!
-     * </p>
-     */
-    @Test
-    void testGetBytes_null() throws Exception {
-        var blob = new FBCachedBlob(null);
-
-        assertNull(blob.getBytes());
-    }
-
     /**
      * Test if {@link FBCachedBlob#position(byte[], long)} throws SQLFeatureNotSupportedException.
      */
@@ -190,16 +160,6 @@ void testPosition_Blob_long() {
         assertThrows(SQLFeatureNotSupportedException.class, () -> blob.position(blob, 1));
     }
 
-    /**
-     * Test if {@link FBCachedBlob#getBinaryStream()} returns {@code null} when data is {@code null}.
-     */
-    @Test
-    void testGetBinaryStream_null() throws Exception {
-        FBCachedBlob blob = new FBCachedBlob(null);
-
-        assertNull(blob.getBinaryStream());
-    }
-
     /**
      * Test if {@link FBCachedBlob#getBinaryStream()} returns stream with all data.
      */