add javadoc for solace-broker-api.exception

Author: jrodolfo

solace-broker-api/src/main/java/org/orgname/solace/broker/api/exception/ApiExceptionHandler.java

@@ -15,9 +15,23 @@
 import java.util.LinkedHashMap;
 import java.util.Map;
 
+/**
+ * Global exception handler for the Solace Broker API.
+ * <p>
+ * This class intercepts various exceptions thrown by the application and transforms them
+ * into standardized {@link ErrorMessage} responses with appropriate HTTP status codes.
+ * It handles validation errors, message parsing issues, and broker-specific exceptions.
+ */
 @RestControllerAdvice
 public class ApiExceptionHandler {
 
+    /**
+     * Handles {@link MethodArgumentNotValidException} which occurs when request body validation fails.
+     *
+     * @param exception the exception containing validation results
+     * @param request the current HTTP request
+     * @return a {@code 400 Bad Request} response with field-level error details
+     */
     @ExceptionHandler(MethodArgumentNotValidException.class)
     public ResponseEntity<ErrorMessage> handleValidation(MethodArgumentNotValidException exception, HttpServletRequest request) {
         Map<String, String> validationErrors = new LinkedHashMap<>();
@@ -32,6 +46,17 @@ public ResponseEntity<ErrorMessage> handleValidation(MethodArgumentNotValidExcep
         );
     }
 
+    /**
+     * Handles {@link HttpMessageNotReadableException} which occurs when the request body is malformed
+     * or contains invalid values for enums.
+     * <p>
+     * Specifically handles validation for {@code message.deliveryMode} and {@code message.payload.type}
+     * when they don't match expected Solace or application-specific values.
+     *
+     * @param exception the exception containing parsing details
+     * @param request the current HTTP request
+     * @return a {@code 400 Bad Request} response with specific error details if available
+     */
     @ExceptionHandler(HttpMessageNotReadableException.class)
     public ResponseEntity<ErrorMessage> handleUnreadableMessage(HttpMessageNotReadableException exception, HttpServletRequest request) {
         Throwable cause = exception.getCause();
@@ -66,31 +91,75 @@ public ResponseEntity<ErrorMessage> handleUnreadableMessage(HttpMessageNotReadab
         return buildResponse(HttpStatus.BAD_REQUEST, "Request body could not be parsed", request.getRequestURI(), null);
     }
 
+    /**
+     * Handles {@link BadRequestException} thrown for custom business logic validation failures.
+     *
+     * @param exception the exception containing the error message
+     * @param request the current HTTP request
+     * @return a {@code 400 Bad Request} response
+     */
     @ExceptionHandler(BadRequestException.class)
     public ResponseEntity<ErrorMessage> handleBadRequest(BadRequestException exception, HttpServletRequest request) {
         return buildResponse(HttpStatus.BAD_REQUEST, exception.getMessage(), request.getRequestURI(), null);
     }
 
+    /**
+     * Handles {@link BrokerConfigurationException} thrown when there are issues with Solace broker settings.
+     *
+     * @param exception the exception containing configuration error details
+     * @param request the current HTTP request
+     * @return a {@code 500 Internal Server Error} response
+     */
     @ExceptionHandler(BrokerConfigurationException.class)
     public ResponseEntity<ErrorMessage> handleBrokerConfiguration(BrokerConfigurationException exception, HttpServletRequest request) {
         return buildResponse(HttpStatus.INTERNAL_SERVER_ERROR, exception.getMessage(), request.getRequestURI(), null);
     }
 
+    /**
+     * Handles {@link BrokerConnectionException} thrown when connection to Solace broker fails.
+     *
+     * @param exception the exception containing connection error details
+     * @param request the current HTTP request
+     * @return a {@code 503 Service Unavailable} response
+     */
     @ExceptionHandler(BrokerConnectionException.class)
     public ResponseEntity<ErrorMessage> handleBrokerConnection(BrokerConnectionException exception, HttpServletRequest request) {
         return buildResponse(HttpStatus.SERVICE_UNAVAILABLE, exception.getMessage(), request.getRequestURI(), null);
     }
 
+    /**
+     * Handles exceptions related to message publishing failures on the Solace broker.
+     *
+     * @param exception the exception (either {@link BrokerPublishFailureException} or {@link BrokerPublishException})
+     * @param request the current HTTP request
+     * @return a {@code 502 Bad Gateway} response
+     */
     @ExceptionHandler({BrokerPublishFailureException.class, BrokerPublishException.class})
     public ResponseEntity<ErrorMessage> handleBrokerPublish(RuntimeException exception, HttpServletRequest request) {
         return buildResponse(HttpStatus.BAD_GATEWAY, exception.getMessage(), request.getRequestURI(), null);
     }
 
+    /**
+     * Fallback handler for any unexpected exceptions not specifically covered.
+     *
+     * @param exception the unexpected exception
+     * @param request the current HTTP request
+     * @return a {@code 500 Internal Server Error} response
+     */
     @ExceptionHandler(Exception.class)
     public ResponseEntity<ErrorMessage> handleUnexpected(Exception exception, HttpServletRequest request) {
         return buildResponse(HttpStatus.INTERNAL_SERVER_ERROR, exception.getMessage(), request.getRequestURI(), null);
     }
 
+    /**
+     * Helper method to construct the {@link ResponseEntity} with the {@link ErrorMessage} body.
+     *
+     * @param status the HTTP status to return
+     * @param message the error message
+     * @param path the request path
+     * @param validationErrors optional map of validation errors
+     * @return the formatted response entity
+     */
     private ResponseEntity<ErrorMessage> buildResponse(HttpStatus status, String message, String path, Map<String, String> validationErrors) {
         ErrorMessage body = new ErrorMessage(
                 Instant.now(),

solace-broker-api/src/main/java/org/orgname/solace/broker/api/exception/BadRequestException.java

@@ -1,11 +1,27 @@
 package org.orgname.solace.broker.api.exception;
 
+/**
+ * Exception thrown when a request is malformed or contains invalid parameters.
+ * <p>
+ * This exception results in a {@code 400 Bad Request} response to the client.
+ */
 public class BadRequestException extends RuntimeException {
 
+    /**
+     * Constructs a new {@code BadRequestException} with the specified detail message.
+     *
+     * @param message the detail message
+     */
     public BadRequestException(String message) {
         super(message);
     }
 
+    /**
+     * Constructs a new {@code BadRequestException} with the specified detail message and cause.
+     *
+     * @param message the detail message
+     * @param cause the cause of the exception
+     */
     public BadRequestException(String message, Throwable cause) {
         super(message, cause);
     }

solace-broker-api/src/main/java/org/orgname/solace/broker/api/exception/BrokerConfigurationException.java

@@ -1,11 +1,29 @@
 package org.orgname.solace.broker.api.exception;
 
+/**
+ * Exception thrown when there is an issue with the Solace broker configuration.
+ * <p>
+ * This typically indicates that the application is unable to correctly interpret
+ * or apply the provided broker settings, preventing successful integration with
+ * the Solace PubSub+ Broker.
+ */
 public class BrokerConfigurationException extends RuntimeException {
 
+    /**
+     * Constructs a new {@code BrokerConfigurationException} with the specified detail message.
+     *
+     * @param message the detail message
+     */
     public BrokerConfigurationException(String message) {
         super(message);
     }
 
+    /**
+     * Constructs a new {@code BrokerConfigurationException} with the specified detail message and cause.
+     *
+     * @param message the detail message
+     * @param cause the cause of the exception
+     */
     public BrokerConfigurationException(String message, Throwable cause) {
         super(message, cause);
     }

solace-broker-api/src/main/java/org/orgname/solace/broker/api/exception/BrokerConnectionException.java

@@ -1,7 +1,19 @@
 package org.orgname.solace.broker.api.exception;
 
+/**
+ * Exception thrown when a connection to the Solace PubSub+ Broker cannot be established or is lost.
+ * <p>
+ * This exception indicates a connectivity issue between the API and the broker,
+ * often resulting in a {@code 503 Service Unavailable} response.
+ */
 public class BrokerConnectionException extends RuntimeException {
 
+    /**
+     * Constructs a new {@code BrokerConnectionException} with the specified detail message and cause.
+     *
+     * @param message the detail message
+     * @param cause the cause of the exception
+     */
     public BrokerConnectionException(String message, Throwable cause) {
         super(message, cause);
     }

solace-broker-api/src/main/java/org/orgname/solace/broker/api/exception/BrokerPublishException.java

@@ -1,7 +1,20 @@
 package org.orgname.solace.broker.api.exception;
 
+/**
+ * Exception thrown when an error occurs during the message publishing process to the Solace broker.
+ * <p>
+ * This is a general exception for publishing failures. For specific failures reported by
+ * the broker (e.g., NACK), {@link BrokerPublishFailureException} might be used instead.
+ * This typically results in a {@code 502 Bad Gateway} response.
+ */
 public class BrokerPublishException extends RuntimeException {
 
+    /**
+     * Constructs a new {@code BrokerPublishException} with the specified detail message and cause.
+     *
+     * @param message the detail message
+     * @param cause the cause of the exception
+     */
     public BrokerPublishException(String message, Throwable cause) {
         super(message, cause);
     }

solace-broker-api/src/main/java/org/orgname/solace/broker/api/exception/BrokerPublishFailureException.java

@@ -1,7 +1,21 @@
 package org.orgname.solace.broker.api.exception;
 
+/**
+ * Exception thrown when the Solace broker explicitly rejects a message publishing attempt.
+ * <p>
+ * This often corresponds to a Negative Acknowledgment (NACK) from the broker, indicating
+ * that the message was received but could not be accepted (e.g., due to permission issues,
+ * full queues, or invalid destination).
+ * This typically results in a {@code 502 Bad Gateway} response.
+ */
 public class BrokerPublishFailureException extends RuntimeException {
 
+    /**
+     * Constructs a new {@code BrokerPublishFailureException} with the specified detail message and cause.
+     *
+     * @param message the detail message
+     * @param cause the cause of the exception
+     */
     public BrokerPublishFailureException(String message, Throwable cause) {
         super(message, cause);
     }

solace-broker-api/src/main/java/org/orgname/solace/broker/api/exception/ErrorMessage.java

@@ -7,14 +7,44 @@
 import java.time.Instant;
 import java.util.Map;
 
+/**
+ * Represents a standardized error response body for the Solace Broker API.
+ * <p>
+ * This class captures essential details about an error, including the timestamp,
+ * HTTP status, a descriptive message, the request path, and any specific validation errors.
+ */
 @NoArgsConstructor
 @AllArgsConstructor
 @Data
 public class ErrorMessage {
+    /**
+     * The timestamp when the error occurred.
+     */
     private Instant timestamp;
+
+    /**
+     * The HTTP status code (e.g., 400, 500).
+     */
     private int status;
+
+    /**
+     * The short name of the HTTP error (e.g., "Bad Request").
+     */
     private String error;
+
+    /**
+     * A detailed message explaining the error.
+     */
     private String message;
+
+    /**
+     * The URI path where the error occurred.
+     */
     private String path;
+
+    /**
+     * A map of field-specific validation errors, if applicable.
+     * The key is the field name and the value is the error message.
+     */
     private Map<String, String> validationErrors;
 }