From d64548d2f79c08b602339fddcbf1474b9d734e33 Mon Sep 17 00:00:00 2001
From: Scott Leberknight <174812+sleberknight@users.noreply.github.com>
Date: Sun, 8 Oct 2023 12:01:33 -0400
Subject: [PATCH] Add method to KiwiJdbc to get trimmed 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 after trimming any leading or trailing whitespace.

Closes #1048
---
 .../java/org/kiwiproject/jdbc/KiwiJdbc.java   | 15 ++++++++
 .../org/kiwiproject/jdbc/KiwiJdbcTest.java    | 37 +++++++++++++++++++
 2 files changed, 52 insertions(+)

diff --git a/src/main/java/org/kiwiproject/jdbc/KiwiJdbc.java b/src/main/java/org/kiwiproject/jdbc/KiwiJdbc.java
index 64ce1f94..87a5e9af 100644
--- a/src/main/java/org/kiwiproject/jdbc/KiwiJdbc.java
+++ b/src/main/java/org/kiwiproject/jdbc/KiwiJdbc.java
@@ -378,6 +378,21 @@ public static String stringOrNullIfBlank(ResultSet rs, String columnName) throws
         return stringOrNullIfBlank(rs, columnName, StringTrimOption.PRESERVE);
     }
 
+    /**
+     * Returns a String from the specified column in the {@link ResultSet}, trimming leading and trailing
+     * whitespace. 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 with leading and trailing whitespace removed, 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 trimmedStringOrNullIfBlank(ResultSet rs, String columnName) throws SQLException {
+        return stringOrNullIfBlank(rs, columnName, StringTrimOption.REMOVE);
+    }
+
     /**
      * 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 c70e9dab..c88455ac 100644
--- a/src/test/java/org/kiwiproject/jdbc/KiwiJdbcTest.java
+++ b/src/test/java/org/kiwiproject/jdbc/KiwiJdbcTest.java
@@ -686,6 +686,43 @@ void shouldReturn_ExactStringValue_FromResultSet(String phrase) throws SQLExcept
         }
     }
 
+    @Nested
+    class TrimmedStringOrNullIfBlank {
+
+        @ParameterizedTest
+        @BlankStringSource
+        void shouldReturnNull_WhenValue_IsBlank(String value) throws SQLException {
+            var resultSet = newMockResultSet();
+            when(resultSet.getString(anyString())).thenReturn(value);
+
+            assertThat(KiwiJdbc.trimmedStringOrNullIfBlank(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_TrimmedStringValue_FromResultSet(String phrase) throws SQLException {
+            var resultSet = newMockResultSet();
+            when(resultSet.getString(anyString())).thenReturn(phrase);
+
+            var trimmed = phrase.strip();
+            assertThat(KiwiJdbc.trimmedStringOrNullIfBlank(resultSet, "phrase")).isEqualTo(trimmed);
+
+            verify(resultSet).getString("phrase");
+            verifyNoMoreInteractions(resultSet);
+        }
+    }
+
     @Nested
     class StringOrNullIfBlankWithTrimOption {