add utility for nullchecking

Author: SirCotare

src/main/java/it/aboutbits/springboot/toolbox/util/NullUtil.java

@@ -0,0 +1,24 @@
+package it.aboutbits.springboot.toolbox.util;
+
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
+
+@NullMarked
+public final class NullUtil {
+    private NullUtil() {
+    }
+
+    public static <T> T nonNullOrFail(@Nullable T x) {
+        if (x == null) {
+            throw new IllegalStateException("Required non-null value, but got null.");
+        }
+        return x;
+    }
+
+    public static <T> T nonNullOrFail(@Nullable T x, String failureMessage) {
+        if (x == null) {
+            throw new IllegalStateException(failureMessage);
+        }
+        return x;
+    }
+}

src/test/java/it/aboutbits/springboot/toolbox/util/NullUtilTest.java

@@ -0,0 +1,84 @@
+package it.aboutbits.springboot.toolbox.util;
+
+import org.jspecify.annotations.NullMarked;
+import org.junit.jupiter.api.Test;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatIllegalStateException;
+
+@NullMarked
+class NullUtilTest {
+
+    @Test
+    void nonNullOrFail_givenNonNullValue_shouldReturnValue() {
+        // given
+        var value = "test";
+
+        // when
+        var result = NullUtil.nonNullOrFail(value);
+
+        // then
+        assertThat(result).isEqualTo(value);
+    }
+
+    @Test
+    void nonNullOrFail_givenNullValue_shouldThrowIllegalStateException() {
+        // given
+        String value = null;
+
+        // then
+        assertThatIllegalStateException()
+                .isThrownBy(() -> /* when */ NullUtil.nonNullOrFail(value))
+                .withMessage("Required non-null value, but got null.");
+    }
+
+    @Test
+    void nonNullOrFailWithMessage_givenNonNullValue_shouldReturnValue() {
+        // given
+        var value = "test";
+        var message = "Custom error message";
+
+        // when
+        var result = NullUtil.nonNullOrFail(value, message);
+
+        // then
+        assertThat(result).isEqualTo(value);
+    }
+
+    @Test
+    void nonNullOrFailWithMessage_givenNullValue_shouldThrowIllegalStateExceptionWithCustomMessage() {
+        // given
+        String value = null;
+        var message = "Custom error message";
+
+        // then
+        assertThatIllegalStateException()
+                .isThrownBy(() -> /* when */ NullUtil.nonNullOrFail(value, message))
+                .withMessage(message);
+    }
+
+    @Test
+    void nonNullOrFail_givenNonNullObject_shouldReturnSameInstance() {
+        // given
+        var value = new Object();
+
+        // when
+        var result = NullUtil.nonNullOrFail(value);
+
+        // then
+        assertThat(result).isSameAs(value);
+    }
+
+    @Test
+    void nonNullOrFailWithMessage_givenNonNullObject_shouldReturnSameInstance() {
+        // given
+        var value = new Object();
+        var message = "Custom error message";
+
+        // when
+        var result = NullUtil.nonNullOrFail(value, message);
+
+        // then
+        assertThat(result).isSameAs(value);
+    }
+}