feat: Add BadRequestException for 4xx handler errors

Author: thced

src/main/java/com/retailsvc/http/BadRequestException.java

@@ -0,0 +1,52 @@
+package com.retailsvc.http;
+
+import java.util.Objects;
+import java.util.Optional;
+
+/**
+ * Thrown by user handlers to signal a 4xx client error. The default {@link ExceptionHandler}
+ * renders this as an RFC 7807 {@code application/problem+json} response carrying the supplied
+ * status, detail, and optional JSON-pointer / validation-keyword fields.
+ *
+ * <p>Use for cases like {@code 422 Unprocessable Content} (payload is syntactically valid but
+ * violates a business rule), {@code 409 Conflict}, {@code 412 Precondition Failed}, etc. For 5xx
+ * errors, throw an ordinary {@link RuntimeException} and let the default handler render 500.
+ */
+public final class BadRequestException extends RuntimeException {
+
+  private static final int DEFAULT_STATUS = 400;
+
+  private final int status;
+  private final String pointer;
+  private final String keyword;
+
+  public BadRequestException(String detail) {
+    this(DEFAULT_STATUS, detail, null, null);
+  }
+
+  public BadRequestException(int status, String detail) {
+    this(status, detail, null, null);
+  }
+
+  public BadRequestException(int status, String detail, String pointer, String keyword) {
+    super(Objects.requireNonNull(detail, "detail must not be null"));
+    if (status < 400 || status > 499) {
+      throw new IllegalArgumentException("status must be 4xx, got " + status);
+    }
+    this.status = status;
+    this.pointer = pointer;
+    this.keyword = keyword;
+  }
+
+  public int status() {
+    return status;
+  }
+
+  public Optional<String> pointer() {
+    return Optional.ofNullable(pointer);
+  }
+
+  public Optional<String> keyword() {
+    return Optional.ofNullable(keyword);
+  }
+}

src/test/java/com/retailsvc/http/BadRequestExceptionTest.java

@@ -0,0 +1,52 @@
+package com.retailsvc.http;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+import org.junit.jupiter.api.Test;
+
+class BadRequestExceptionTest {
+
+  @Test
+  void defaultsStatusTo400() {
+    BadRequestException e = new BadRequestException("bad input");
+
+    assertThat(e.status()).isEqualTo(400);
+    assertThat(e.getMessage()).isEqualTo("bad input");
+    assertThat(e.pointer()).isEmpty();
+    assertThat(e.keyword()).isEmpty();
+  }
+
+  @Test
+  void honorsExplicitStatus() {
+    BadRequestException e = new BadRequestException(422, "email taken");
+
+    assertThat(e.status()).isEqualTo(422);
+    assertThat(e.getMessage()).isEqualTo("email taken");
+  }
+
+  @Test
+  void carriesPointerAndKeyword() {
+    BadRequestException e = new BadRequestException(422, "email taken", "/email", "unique");
+
+    assertThat(e.pointer()).contains("/email");
+    assertThat(e.keyword()).contains("unique");
+  }
+
+  @Test
+  void rejectsNon4xxStatus() {
+    assertThatThrownBy(() -> new BadRequestException(500, "boom"))
+        .isInstanceOf(IllegalArgumentException.class)
+        .hasMessageContaining("4xx");
+    assertThatThrownBy(() -> new BadRequestException(399, "x"))
+        .isInstanceOf(IllegalArgumentException.class)
+        .hasMessageContaining("4xx");
+  }
+
+  @Test
+  void rejectsNullDetail() {
+    assertThatThrownBy(() -> new BadRequestException(null))
+        .isInstanceOf(NullPointerException.class)
+        .hasMessageContaining("detail");
+  }
+}