From 06837f0d2ce30d1211039c4f63dbf3c0e601fc2d Mon Sep 17 00:00:00 2001
From: Scott Leberknight <174812+sleberknight@users.noreply.github.com>
Date: Sun, 8 Oct 2023 11:33:06 -0400
Subject: [PATCH] Add method to KiwiJdbc to get string values or null when
 blank

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
---
 .../java/org/kiwiproject/jdbc/KiwiJdbc.java   | 14 +++++++
 .../org/kiwiproject/jdbc/KiwiJdbcTest.java    | 38 ++++++++++++++++++-
 2 files changed, 51 insertions(+), 1 deletion(-)

diff --git a/src/main/java/org/kiwiproject/jdbc/KiwiJdbc.java b/src/main/java/org/kiwiproject/jdbc/KiwiJdbc.java
index 4000cd7e..64ce1f94 100644
--- a/src/main/java/org/kiwiproject/jdbc/KiwiJdbc.java
+++ b/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.
      */
diff --git a/src/test/java/org/kiwiproject/jdbc/KiwiJdbcTest.java b/src/test/java/org/kiwiproject/jdbc/KiwiJdbcTest.java
index c651309b..c70e9dab 100644
--- a/src/test/java/org/kiwiproject/jdbc/KiwiJdbcTest.java
+++ b/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);