Add verifyExistenceAndReturn methods to KiwiResources

src/main/java/org/kiwiproject/jaxrs/KiwiResources.java

@@ -60,6 +60,20 @@ public static <T> void verifyExistence(T resourceEntity) {
         verifyExistence(resourceEntity, null);
     }
 
+    /**
+     * Verifies that {@code resourceEntity} is not null and returns it,
+     * otherwise throws a {@link JaxrsNotFoundException}.
+     *
+     * @param resourceEntity the resource entity to verify
+     * @param <T>            the object type
+     * @return the entity, if it is not null
+     * @throws JaxrsNotFoundException if the entity is null
+     */
+    @NonNull
+    public static <T> T verifyExistenceAndReturn(T resourceEntity) {
+        return verifyExistence(Optional.ofNullable(resourceEntity));
+    }
+
     /**
      * Verifies that {@code resourceEntity} contains a value, otherwise throws a {@link JaxrsNotFoundException}.
      *
@@ -89,6 +103,21 @@ public static <T> void verifyExistence(T resourceEntity, Class<T> entityType, Ob
         verifyExistence(resourceEntity, notFoundMessage);
     }
 
+    /**
+     * Verifies that {@code resourceEntity} is not null and returns it,
+     * otherwise throws a {@link JaxrsNotFoundException}.
+     *
+     * @param resourceEntity the resource entity to verify
+     * @param entityType     a Class representing the entity type, used in error messages
+     * @param identifier     the unique identifier of the resource identity
+     * @param <T>            the object type
+     * @return the entity, if it is not null
+     * @throws JaxrsNotFoundException if the entity is null
+     */
+    public static <T> T verifyExistenceAndReturn(T resourceEntity, Class<T> entityType, Object identifier) {
+        return verifyExistence(Optional.ofNullable(resourceEntity), entityType, identifier);
+    }
+
     /**
      * Verifies that {@code resourceEntity} contains a value, otherwise throws {@link JaxrsNotFoundException}.
      *
@@ -121,6 +150,37 @@ public static <T> void verifyExistence(T resourceEntity, String notFoundMessage)
         }
     }
 
+    /**
+     * Verifies that {@code resourceEntity} is not null and returns it,
+     * otherwise throws {@link JaxrsNotFoundException}.
+     *
+     * @param resourceEntity  the resource entity to verify
+     * @param notFoundMessage the error message to include in the response entity
+     * @param <T>             the object type
+     * @return the entity, if it is not null
+     * @throws JaxrsNotFoundException if the entity is null
+     */
+    @NonNull
+    public static <T> T verifyExistenceAndReturn(T resourceEntity, String notFoundMessage) {
+        return verifyExistence(Optional.ofNullable(resourceEntity), notFoundMessage);
+    }
+
+    /**
+     * Verifies that {@code resourceEntity} contains a value, otherwise throws {@link JaxrsNotFoundException}.
+     *
+     * @param resourceEntity  the resource entity to verify
+     * @param notFoundMessage the error message to include in the response entity
+     * @param <T>             the object type
+     * @return the entity if the Optional contains a value
+     * @throws JaxrsNotFoundException if the entity is empty
+     */
+    @NonNull
+    public static <T> T verifyExistence(Optional<T> resourceEntity, String notFoundMessage) {
+        verifyExistence(resourceEntity.orElse(null), notFoundMessage);
+
+        return resourceEntity.orElseThrow();
+    }
+
     /**
      * Verifies that {@code resourceEntity} is not null, otherwise throws {@link JaxrsNotFoundException}.
      *
@@ -140,19 +200,21 @@ public static <T> void verifyExistence(T resourceEntity, String notFoundMessageT
     }
 
     /**
-     * Verifies that {@code resourceEntity} contains a value, otherwise throws {@link JaxrsNotFoundException}.
+     * Verifies that {@code resourceEntity} is not null and returns it,
+     * otherwise throws {@link JaxrsNotFoundException}.
      *
-     * @param resourceEntity  the resource entity to verify
-     * @param notFoundMessage the error message to include in the response entity
-     * @param <T>             the object type
-     * @return the entity if the Optional contains a value
+     * @param resourceEntity          the resource entity to verify
+     * @param notFoundMessageTemplate template for the error message to include in the response entity; uses
+     *                                {@link KiwiStrings#format(String, Object...) KiwiStrings.format}
+     *                                to construct the message
+     * @param args                    the arguments to be substituted into the message template
+     * @param <T>                     the object type
+     * @return the entity, if it is not null
      * @throws JaxrsNotFoundException if the entity is empty
      */
     @NonNull
-    public static <T> T verifyExistence(Optional<T> resourceEntity, String notFoundMessage) {
-        verifyExistence(resourceEntity.orElse(null), notFoundMessage);
-
-        return resourceEntity.orElseThrow();
+    public static <T> T verifyExistenceAndReturn(T resourceEntity, String notFoundMessageTemplate, Object... args) {
+        return verifyExistence(Optional.ofNullable(resourceEntity), notFoundMessageTemplate, args);
     }
 
     /**

src/test/java/org/kiwiproject/jaxrs/KiwiResourcesTest.java

@@ -216,6 +216,81 @@ void shouldThrow_WhenOptionalIsEmpty(String template) {
         }
     }
 
+    @Nested
+    class VerifyExistenceAndReturn {
+
+        @Nested
+        class EntityArgument {
+
+            @Test
+            void shouldReturnEntity_WhenEntityNotNull() {
+                assertThat(KiwiResources.verifyExistenceAndReturn(ENTITY)).isSameAs(ENTITY);
+            }
+
+            @Test
+            void shouldThrow_WhenEntityIsNull() {
+                assertThatThrownBy(() -> KiwiResources.verifyExistenceAndReturn(NULL_ENTITY))
+                        .isExactlyInstanceOf(JaxrsNotFoundException.class)
+                        .hasMessage(defaultNotFoundMessage());
+            }
+        }
+
+        @Nested
+        class EntityTypeAndIdentifier {
+
+            @Test
+            void shouldReturnEntity_WhenEntityNotNull() {
+                assertThat(KiwiResources.verifyExistenceAndReturn(ENTITY, MyEntity.class, ID)).isSameAs(ENTITY);
+            }
+
+            @Test
+            void shouldThrow_WhenEntityIsNull() {
+                var message = JaxrsNotFoundException.buildMessage("MyEntity", ID);
+
+                assertThatThrownBy(() -> KiwiResources.verifyExistenceAndReturn((MyEntity) null, MyEntity.class, ID))
+                        .isExactlyInstanceOf(JaxrsNotFoundException.class)
+                        .hasMessage(message);
+            }
+        }
+
+        @Nested
+        class EntityAndNotFoundMessage {
+
+            @Test
+            void shouldReturnEntity_WhenEntityNotNull() {
+                assertThat(KiwiResources.verifyExistenceAndReturn(ENTITY, ENTITY_NOT_FOUND_MESSAGE)).isSameAs(ENTITY);
+            }
+
+            @Test
+            void shouldThrow_WhenEntityIsNull() {
+                assertThatThrownBy(() -> KiwiResources.verifyExistenceAndReturn(NULL_ENTITY, ENTITY_NOT_FOUND_MESSAGE))
+                        .isExactlyInstanceOf(JaxrsNotFoundException.class)
+                        .hasMessage(ENTITY_NOT_FOUND_MESSAGE);
+            }
+        }
+
+        @Nested
+        class EntityAndNotFoundMessageTemplateWithArgs {
+
+            @Test
+            void shouldReturnEntity_WhenEntityNotNull() {
+                assertThat(KiwiResources.verifyExistenceAndReturn(ENTITY, ENTITY_NOT_FOUND_MESSAGE_TEMPLATE_1, 42)).isSameAs(ENTITY);
+            }
+
+            @ParameterizedTest
+            @ValueSource(strings = {
+                    ENTITY_NOT_FOUND_MESSAGE_TEMPLATE_1,
+                    ENTITY_NOT_FOUND_MESSAGE_TEMPLATE_2
+            })
+            void shouldThrow_WhenEntityIsNull(String template) {
+                var arg = 84;
+                assertThatThrownBy(() -> KiwiResources.verifyExistenceAndReturn(NULL_ENTITY, template, arg))
+                        .isExactlyInstanceOf(JaxrsNotFoundException.class)
+                        .hasMessage(f(template, arg));
+            }
+        }
+    }
+
     @Nested
     class NewResponse {