add javadoc for solace-broker-api test classes

Author: jrodolfo

solace-broker-api/src/test/java/org/orgname/solace/broker/api/SolaceBrokerAPIApplicationTest.java

@@ -4,6 +4,10 @@
 
 import static org.junit.jupiter.api.Assertions.assertNotNull;
 
+/**
+ * Unit test for {@link SolaceBrokerAPIApplication}.
+ * Verifies that the main application class can be instantiated.
+ */
 class SolaceBrokerAPIApplicationTest {
 
     @Test

solace-broker-api/src/test/java/org/orgname/solace/broker/api/controller/MessageApiContractIntegrationTest.java

@@ -36,6 +36,13 @@
 import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
 import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
 
+/**
+ * Integration tests for the Message API contract.
+ * This class verifies the full flow from the REST controller through the service layer
+ * to the database, ensuring that the API contract is respected and that messages
+ * are correctly persisted and retrieved. It uses an in-memory database and mocks
+ * the Solace broker integration.
+ */
 @SpringBootTest(properties = {
         "spring.datasource.url=jdbc:h2:mem:message-api-contract-test;MODE=MySQL;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=false",
         "spring.datasource.driver-class-name=org.h2.Driver",

solace-broker-api/src/test/java/org/orgname/solace/broker/api/controller/MessageControllerTest.java

@@ -41,6 +41,11 @@
 import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
 import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
 
+/**
+ * Unit tests for {@link MessageController}.
+ * This class uses a {@link MockMvc} setup with {@link StubDatabase} and {@link StubDirectPublisherService}
+ * to verify the controller's behavior, including message retrieval, filtering, and publishing flow.
+ */
 class MessageControllerTest {
 
     private StubDatabase database;
@@ -612,6 +617,10 @@ private static Message storedMessage(String innerMessageId, String destination,
         return message;
     }
 
+    /**
+     * Stub implementation of {@link DirectPublisherService} for testing.
+     * Allows simulating successful or failed message publication to a Solace broker.
+     */
     private static final class StubDirectPublisherService implements DirectPublisherService {
         private PublishMessageResponseDTO response;
         private IllegalArgumentException illegalArgumentException;
@@ -629,6 +638,9 @@ public PublishMessageResponseDTO sendMessage(String topicName, String content, D
         }
     }
 
+    /**
+     * In-memory database stub for testing the controller's logic without a real database.
+     */
     private static final class StubDatabase implements Database {
         private final List<Message> storedMessages = new ArrayList<>();
         private Message lastSavedMessage;

solace-broker-api/src/test/java/org/orgname/solace/broker/api/controller/MessageControllerWebMvcTest.java

@@ -44,6 +44,11 @@
 import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
 import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
 
+/**
+ * Web MVC tests for {@link MessageController}.
+ * This class uses {@link WebMvcTest} to perform integration tests on the web layer,
+ * mocking the service dependencies to verify request mapping, validation, and JSON serialization.
+ */
 @WebMvcTest(controllers = MessageController.class)
 @Import(ApiExceptionHandler.class)
 class MessageControllerWebMvcTest {

solace-broker-api/src/test/java/org/orgname/solace/broker/api/repository/MessageRepositoryDataJpaTest.java

@@ -17,6 +17,11 @@
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
 
+/**
+ * Data JPA tests for {@link MessageRepository}.
+ * This class tests the persistence layer and filtering capabilities of the message repository
+ * using an in-memory H2 database configured to mimic MySQL behavior.
+ */
 @DataJpaTest(properties = {
         "spring.datasource.url=jdbc:h2:mem:message-repository-test;MODE=MySQL;DB_CLOSE_DELAY=-1",
         "spring.datasource.driver-class-name=org.h2.Driver",
@@ -168,6 +173,9 @@ void shouldFilterMessagesByStalePendingOnly() {
         assertEquals(true, response.getItems().getFirst().isStalePending());
     }
 
+    /**
+     * Persists a message with default payload type (BINARY) and status (PUBLISHED).
+     */
     private void persistMessage(
             String innerMessageId,
             String destination,
@@ -177,6 +185,9 @@ private void persistMessage(
         persistMessage(innerMessageId, destination, deliveryMode, PayloadType.BINARY, priority, PublishStatus.PUBLISHED, createdAt);
     }
 
+    /**
+     * Persists a message with the default payload type (BINARY).
+     */
     private void persistMessage(
             String innerMessageId,
             String destination,
@@ -187,6 +198,19 @@ private void persistMessage(
         persistMessage(innerMessageId, destination, deliveryMode, PayloadType.BINARY, priority, publishStatus, createdAt);
     }
 
+    /**
+     * Persists a message to the database for testing purposes.
+     * This method directly interacts with the {@link EntityManager} to ensure that timestamps
+     * are correctly set, as they are often handled by JPA/Hibernate lifecycle events.
+     *
+     * @param innerMessageId the unique identifier for the message
+     * @param destination the Solace topic destination
+     * @param deliveryMode the delivery mode (e.g., PERSISTENT, DIRECT)
+     * @param payloadType the type of payload (e.g., TEXT, JSON, BINARY)
+     * @param priority the message priority
+     * @param publishStatus the current publish status
+     * @param createdAt the creation timestamp
+     */
     private void persistMessage(
             String innerMessageId,
             String destination,

solace-broker-api/src/test/java/org/orgname/solace/broker/api/service/AccessPropertiesImplTest.java

@@ -13,6 +13,11 @@
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertNotNull;
 
+/**
+ * Unit tests for {@link AccessPropertiesImpl}.
+ * Verifies that broker connection properties are correctly extracted from environment variables
+ * or provided parameters.
+ */
 class AccessPropertiesImplTest {
 
     private static final String HOST = "test-host";

solace-broker-api/src/test/java/org/orgname/solace/broker/api/service/DatabaseImplTest.java

@@ -28,6 +28,11 @@
 import static org.mockito.Mockito.mock;
 import static org.mockito.Mockito.when;
 
+/**
+ * Unit tests for {@link DatabaseImpl}.
+ * This class verifies the business logic for message persistence, status updates,
+ * and filtering, mocking the {@link MessageRepository}.
+ */
 class DatabaseImplTest {
 
     private MessageRepository messageRepository;

solace-broker-api/src/test/java/org/orgname/solace/broker/api/service/DirectPublisherServiceImplTest.java

@@ -13,6 +13,11 @@
 import static org.junit.jupiter.api.Assertions.assertThrows;
 import static org.orgname.solace.broker.api.constants.Constants.ERROR_EMPTY_MESSAGE_OR_TOPIC_NAME;
 
+/**
+ * Unit tests for {@link DirectPublisherServiceImpl}.
+ * Verifies message publishing logic, input validation, and configuration handling
+ * for the Solace broker integration.
+ */
 class DirectPublisherServiceImplTest {
 
     private final DirectPublisherServiceImpl directPublisherService = new DirectPublisherServiceImpl(new StubAccessProperties());