Add method to KiwiJdbc to get string values or null when blank (#1060)

Add stringOrNullIfBlank method to KiwiJdbc. If the value returned
from the database is null or blank (whitespace only), this method
returns null. If the value from the database is not blank, the
string is returned as-is.

Closes #1047

src/main/java/org/kiwiproject/jdbc/KiwiJdbc.java

@@ -364,6 +364,20 @@ public static boolean booleanFromInt(ResultSet rs, String columnName, BooleanCon
         return KiwiPrimitives.booleanFromInt(rs.getInt(columnName), option);
     }
 
+    /**
+     * Returns a String from the specified column in the {@link ResultSet}. When the database value
+     * is {@code NULL} or contains only whitespace, returns {@code null}.
+     *
+     * @param rs         the ResultSet
+     * @param columnName the date column name
+     * @return the String value, or {@code null} if the column was blank or {@code NULL}
+     * @throws SQLException if there is any error getting the value from the database
+     */
+    @Nullable
+    public static String stringOrNullIfBlank(ResultSet rs, String columnName) throws SQLException {
+        return stringOrNullIfBlank(rs, columnName, StringTrimOption.PRESERVE);
+    }
+
     /**
      * Enum representing options for trimming strings.
      */

src/test/java/org/kiwiproject/jdbc/KiwiJdbcTest.java

@@ -650,6 +650,42 @@ void shouldConvert_WithBooleanConversionOption(int value,
         }
     }
 
+    @Nested
+    class StringOrNullIfBlank {
+
+        @ParameterizedTest
+        @BlankStringSource
+        void shouldReturnNull_WhenValue_IsBlank(String value) throws SQLException {
+            var resultSet = newMockResultSet();
+            when(resultSet.getString(anyString())).thenReturn(value);
+
+            assertThat(KiwiJdbc.stringOrNullIfBlank(resultSet, "comment")).isNull();
+
+            verify(resultSet).getString("comment");
+            verifyNoMoreInteractions(resultSet);
+        }
+
+        @ParameterizedTest
+        @ValueSource(strings = {
+                "alice",
+                "Sphinx of black quartz, judge my vow",
+                "  that was a pangram",
+                "and so is this...   ",
+                "  The five boxing\r\nwizards jump quickly  ",
+                "  and also this one \r\n ",
+                "Pack my box\r\nwith five dozen\r\nliquor jugs"
+        })
+        void shouldReturn_ExactStringValue_FromResultSet(String phrase) throws SQLException {
+            var resultSet = newMockResultSet();
+            when(resultSet.getString(anyString())).thenReturn(phrase);
+
+            assertThat(KiwiJdbc.stringOrNullIfBlank(resultSet, "phrase")).isEqualTo(phrase);
+
+            verify(resultSet).getString("phrase");
+            verifyNoMoreInteractions(resultSet);
+        }
+    }
+
     @Nested
     class StringOrNullIfBlankWithTrimOption {
 
@@ -698,7 +734,7 @@ void shouldReturn_ExactString_WhenStringTrimOption_Is_PRESERVE(String phrase) th
                 "\t\tthe lazy\t\r\n",
                 "   \tdog\r\n\r\n  "
         })
-        void shouldReturn_StrippedString_WhenStringTrimOption_Is_REMOVE(String phrase) throws SQLException {
+        void shouldReturn_TrimmedString_WhenStringTrimOption_Is_REMOVE(String phrase) throws SQLException {
             var resultSet = newMockResultSet();
             when(resultSet.getString(anyString())).thenReturn(phrase);