Tag: exception hierarchy

Use a Hierarchy of Custom Exceptions with Specific Messages

1. Define a base exception class

Create a generic custom exception that extends RuntimeException (or Exception if you need checked exceptions).

public class ApplicationException extends RuntimeException {
    private final String errorCode;

    public ApplicationException(String message, String errorCode) {
        super(message);
        this.errorCode = errorCode;
    }

    public String getErrorCode() {
        return errorCode;
    }
}

2. Create a few meaningful subclasses for common domains

Use subclasses only for distinct categories, not every input field.

public class ValidationException extends ApplicationException {
    public ValidationException(String message) {
        super(message, "VALIDATION_ERROR");
    }
}

public class ResourceNotFoundException extends ApplicationException {
    public ResourceNotFoundException(String message) {
        super(message, "RESOURCE_NOT_FOUND");
    }
}

3. Throw exceptions with detailed messages

Use informative messages, but reuse exception classes.

if (email == null || !email.contains("@")) {
    throw new ValidationException("Invalid email address: " + email);
}

if (user == null) {
    throw new ResourceNotFoundException("User with ID " + userId + " not found.");
}

4. Centralize exception handling

Use @ControllerAdvice in Spring Boot to map exceptions to HTTP responses.

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(ValidationException.class)
    public ResponseEntity<ApiError> handleValidationException(ValidationException ex) {
        return ResponseEntity.badRequest().body(new ApiError(ex.getErrorCode(), ex.getMessage()));
    }

    @ExceptionHandler(ResourceNotFoundException.class)
    public ResponseEntity<ApiError> handleNotFoundException(ResourceNotFoundException ex) {
        return ResponseEntity.status(HttpStatus.NOT_FOUND)
                             .body(new ApiError(ex.getErrorCode(), ex.getMessage()));
    }
}

---

🔄 Trade-offs

Strategy	Pros	Cons
One Exception per Input	Max granularity	Too many classes, high maintenance
Generic Exception Only	Simple	Hard to trace errors, poor UX/API feedback
Domain-Based Custom Exceptions (✅)	Balanced, readable, scalable	Slightly more boilerplate

---

📌 Summary

• ❌ Don’t create one exception class per field or input.
• ❌ Don’t rely solely on generic exceptions with vague messages.
• ✅ Do create a few well-named custom exceptions per domain concern (validation, business rule, resource not found).
• ✅ Do include specific messages and codes for clarity and front-end/API consumption.

If you’re building APIs, error codes + structured JSON responses improve DX (developer experience) and UX.

Let me know if you want a boilerplate for API exception handling in Spring Boot.

---

Other considerations

There are several important considerations when designing and handling exceptions in Java applications, especially for APIs or enterprise-level systems. Here’s a breakdown of strategic, practical, and technical points beyond the basic structure:

---

🔍 1. Checked vs Unchecked Exceptions

• Checked Exceptions (extends Exception): Force callers to handle or declare them.
  • Good for recoverable errors (e.g. file not found, invalid config).
  • Can pollute method signatures and reduce readability.
• Unchecked Exceptions (extends RuntimeException): Don’t require handling.
  • Better for programming errors, validation failures, or business rules.
  • Preferred in modern Java and frameworks like Spring.

👉 Recommendation: Use unchecked exceptions for business logic and REST APIs unless you’re dealing with truly recoverable scenarios (e.g., IO or external service failures).

---

🧩 2. Message Structure: Human + Machine Friendly

• Provide:
  • A clear human-readable message
  • An error code (short, unique identifier, e.g. USER_NOT_FOUND)
  • Optionally: a field name, if applicable

{
  "error": {
    "code": "EMAIL_INVALID",
    "message": "The email format is invalid",
    "field": "email"
  }
}

This format helps:

• Frontend display and localization
• Developers debugging issues
• Automated systems parsing errors

---

🗂 3. Use of ErrorCode Enum or Registry

Instead of string literals scattered throughout your code, centralize error codes:

public enum ErrorCode {
    INVALID_EMAIL("EMAIL_INVALID"),
    USER_NOT_FOUND("USER_NOT_FOUND");

    private final String code;

    ErrorCode(String code) {
        this.code = code;
    }

    public String getCode() {
        return code;
    }
}

This:

• Prevents duplication
• Enables translation
• Supports analytics/logs

---

📦 4. Payload-rich Exceptions

Sometimes, it’s useful for exceptions to carry more context, like field names, rejected values, etc.

public class FieldValidationException extends ValidationException {
    private final String field;
    private final Object rejectedValue;

    public FieldValidationException(String field, Object rejectedValue, String message) {
        super(message);
        this.field = field;
        this.rejectedValue = rejectedValue;
    }

    // getters
}

You can serialize this in your @ControllerAdvice.

---

🧪 5. Testability and Observability

• Design exceptions so that unit and integration tests can assert them cleanly.
• Log exceptions with structured messages or MDC context (e.g. requestId).
• Use tools like:
  • Sentry, Datadog, or Elastic Stack for centralized logging
  • AOP or HandlerInterceptor to inject context (user ID, trace ID)

---

💡 6. Avoid Swallowing Exceptions

Don’t silently ignore exceptions unless you’re 100% sure it’s safe:

try {
    doSomething();
} catch (Exception e) {
    // ❌ Don't just do nothing or log without action
    logger.error("Something went wrong", e); // ✅
    throw new ApplicationException("Internal processing error", "INTERNAL_ERROR");
}

---

🔒 7. Security and Internal Data

Be cautious not to expose internal details like stack traces, SQL errors, or implementation-specific info in API responses.

✅ Do this:

{
  "code": "INTERNAL_ERROR",
  "message": "Something went wrong. Please contact support."
}

❌ Not this:

{
  "message": "java.sql.SQLIntegrityConstraintViolationException: Duplicate entry 'foo@example.com'..."
}

---

🧘 Final Thoughts

Designing a good exception strategy is about clarity, maintainability, and robustness. A few key principles:

• Be consistent in your error structure.
• Surface enough context for clients to recover or correct input.
• Don’t overdo exception classes, but don’t go fully generic either.
• Integrate with observability tools to monitor exception patterns.