doc(backend)/add-javadoc

backend/discovery-service/src/main/java/com/swyth/discoveryservice/DiscoveryServiceApplication.java

@@ -4,6 +4,17 @@
 import org.springframework.boot.autoconfigure.SpringBootApplication;
 import org.springframework.cloud.netflix.eureka.server.EnableEurekaServer;
 
+/**
+ * DiscoveryServiceApplication is the entry point for the Discovery Service application.
+ * This application acts as a Eureka Server for service discovery, allowing microservices
+ * to register themselves and discover other registered services.
+ *
+ * This class is annotated with:
+ * - @SpringBootApplication: Indicates a Spring Boot application.
+ * - @EnableEurekaServer: Activates the Netflix Eureka Server for service discovery capabilities.
+ *
+ * The main method initializes and runs the Spring Boot application.
+ */
 @SpringBootApplication
 @EnableEurekaServer
 public class DiscoveryServiceApplication {

backend/emergency-service/pom.xml

@@ -33,6 +33,12 @@
 		<sonar.host.url>https://sonarcloud.io</sonar.host.url>
 	</properties>
 	<dependencies>
+		<!-- https://mvnrepository.com/artifact/org.apache.maven.plugins/maven-javadoc-plugin -->
+		<dependency>
+			<groupId>org.apache.maven.plugins</groupId>
+			<artifactId>maven-javadoc-plugin</artifactId>
+			<version>3.11.2</version>
+		</dependency>
 		<dependency>
 			<groupId>org.springframework.boot</groupId>
 			<artifactId>spring-boot-starter-data-jpa</artifactId>

backend/emergency-service/src/main/java/com/swyth/emergencyservice/EmergencyServiceApplication.java

@@ -5,6 +5,19 @@
 import org.springframework.cloud.client.discovery.EnableDiscoveryClient;
 import org.springframework.cloud.openfeign.EnableFeignClients;
 
+/**
+ * The EmergencyServiceApplication class serves as the entry point for the Emergency Service
+ * application. It configures the Spring Boot application as a discovery client
+ * and enables Feign clients for declarative REST client functionality.
+ *
+ * Annotations:
+ * - @SpringBootApplication: Marks this as a Spring Boot application.
+ * - @EnableFeignClients: Enables the detection of Feign clients in the application.
+ * - @EnableDiscoveryClient: Configures the application to register itself as a discovery client
+ *   in a service registry, allowing it to interact with other services.
+ *
+ * The main method initializes and runs the Spring Boot application.
+ */
 @SpringBootApplication
 @EnableFeignClients
 @EnableDiscoveryClient

backend/emergency-service/src/main/java/com/swyth/emergencyservice/config/CustomErrorDecoder.java

@@ -10,6 +10,12 @@
 import java.io.InputStream;
 import java.util.Map;
 
+/**
+ * CustomErrorDecoder is an implementation of the ErrorDecoder interface
+ * used to decode and handle HTTP error responses in a Feign client.
+ * It parses the error details from the response body and maps specific
+ * HTTP status codes to custom exceptions.
+ */
 public class CustomErrorDecoder implements ErrorDecoder {
 
     // Jackson ObjectMapper to parse JSON

backend/emergency-service/src/main/java/com/swyth/emergencyservice/config/FeignConfig.java

@@ -9,6 +9,14 @@
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 
+/**
+ * FeignConfig class provides the configuration for Feign clients in the application.
+ *
+ * This class customizes the Feign client by registering beans for request and response
+ * encoding/decoding and error handling. The configurations ensure that Feign clients
+ * can seamlessly integrate with the application's data format and handle errors
+ * appropriately.
+ */
 @Configuration
 public class FeignConfig {
 

backend/emergency-service/src/main/java/com/swyth/emergencyservice/config/FeignReactiveConfig.java

@@ -6,6 +6,13 @@
 import reactor.core.scheduler.Schedulers;
 import java.util.concurrent.Executors;
 
+/**
+ * Configuration class for setting up reactive Feign components.
+ *
+ * This class defines custom configurations required for reactive Feign,
+ * including a scheduler for managing blocking operations in a reactive context, that fixed
+ * a blocking single thread operation error.
+ */
 @Configuration
 public class FeignReactiveConfig {
 

backend/emergency-service/src/main/java/com/swyth/emergencyservice/controller/BedReservationController.java

@@ -10,13 +10,40 @@
 import org.springframework.web.bind.annotation.*;
 import reactor.core.publisher.Mono;
 
+/**
+ * Rest Controller handling bed reservation-related operations.
+ *
+ * The BedReservationController manages endpoints for creating bed reservations
+ * and retrieving information about existing reservations. It interacts with
+ * the {@link BedReservationService} to perform the necessary business logic and
+ * return results as HTTP responses.
+ *
+ * Endpoints:
+ * - GET /v1/bed-reservations/{id}: Retrieves details of a bed reservation by its unique ID.
+ * - POST /v1/bed-reservations: Creates a new bed reservation with the provided details.
+ *
+ * Dependencies:
+ * - {@link BedReservationService}: The service layer responsible for bed reservation operations.
+ *
+ * Validation and Exceptions:
+ * - Handles input validation for creating bed reservations using {@link BedReservationDTO}.
+ * - Throws {@link BedUnavailableException} if no bed is available for the requested criteria.
+ */
 @Controller
 @RestController
 @RequestMapping("/v1/bed-reservations")
-//@CrossOrigin(origins = "*", allowedHeaders = "*") //TODO: don't let it like that in Production env
 public class BedReservationController {
     private final BedReservationService bedReservationService;
 
+    /**
+     * Constructs the BedReservationController with a BedReservationService dependency.
+     *
+     * This constructor initializes the controller with the specified service, which provides
+     * the business logic for handling bed reservation-related operations such as creation
+     * and retrieval of bed reservations.
+     *
+     * @param bedReservationService the service responsible for managing bed reservation logic
+     */
     public BedReservationController(BedReservationService bedReservationService) {
         this.bedReservationService = bedReservationService;
     }

backend/emergency-service/src/main/java/com/swyth/emergencyservice/dto/BedReservationDTO.java

@@ -5,7 +5,16 @@
 import jakarta.validation.constraints.Pattern;
 import lombok.Data;
 
-// TODO: refactor to bed reservation Request/Payload
+/**
+ * Data Transfer Object for handling bed reservation requests.
+ *
+ * This class encapsulates the details required to create a bed reservation for a specific hospital
+ * and medical specialization. It includes information about the hospital, medical specialization,
+ * and the personal details of the individual making the reservation.
+ *
+ * Validation annotations are included for ensuring the integrity and correctness
+ * of the data provided in the request.
+ */
 @Data
 public class BedReservationDTO {
 

backend/emergency-service/src/main/java/com/swyth/emergencyservice/dto/BedReservationResponseDTO.java

@@ -6,7 +6,24 @@
 import lombok.AllArgsConstructor;
 import lombok.Data;
 
-// TODO : Refactor to BedReservation
+/**
+ * Data Transfer Object representing a response for a bed reservation.
+ *
+ * This class is used to encapsulate the response details of a bed reservation,
+ * including the reservation's ID, the associated hospital and medical specialization IDs,
+ * as well as the personal and contact details of the individual for whom the reservation is made.
+ * This DTO is intended for use in response payloads within applications, enabling
+ * a clear separation between internal domain models and API responses.
+ *
+ * Fields:
+ * - id: The unique identifier for the bed reservation.
+ * - hospitalId: The identifier of the hospital where the reservation is made.
+ * - medicalSpecializationId: The identifier of the medical specialization associated with the reservation.
+ * - reservationFirstName: The first name of the person for whom the reservation is made.
+ * - reservationLastName: The last name of the person for whom the reservation is made.
+ * - reservationEmail: The email address of the person for whom the reservation is made.
+ * - reservationPhoneNumber: The phone number of the person for whom the reservation is made.
+ */
 @Data
 @AllArgsConstructor
 public class BedReservationResponseDTO {

backend/emergency-service/src/main/java/com/swyth/emergencyservice/dto/BedReservationResponseDtoMapper.java

@@ -2,11 +2,21 @@
 
 import com.swyth.emergencyservice.entity.BedReservation;
 
+/**
+ * This class provides mapping functionality to convert a {@code BedReservation} entity
+ * into a {@code BedReservationResponseDTO}.
+ *
+ * The purpose of the {@code BedReservationResponseDtoMapper} is to extract
+ * relevant fields from the {@code BedReservation} entity and package them
+ * into a data transfer object ({@code BedReservationResponseDTO})
+ * for use in external layers such as APIs or client responses.
+ *
+ * The mapper ensures consistency and reduces the complexity of
+ * transforming domain objects into DTOs by providing a dedicated method
+ * for the transformation process.
+ */
 public class BedReservationResponseDtoMapper {
 
-    public BedReservationResponseDtoMapper() {
-    }
-
     public static BedReservationResponseDTO convertToDTO(BedReservation reservation) {
         return new BedReservationResponseDTO(
                 reservation.getId(),

backend/emergency-service/src/main/java/com/swyth/emergencyservice/entity/BedReservation.java

@@ -11,6 +11,20 @@
 import lombok.Data;
 import lombok.NoArgsConstructor;
 
+/**
+ * Represents a bed reservation for a specific hospital and medical specialization.
+ * This class is used to store and manage information about reservations made for hospital beds.
+ *
+ * An instance of `BedReservation` contains the necessary information about
+ * the reservation, including personal details of the individual making the reservation
+ * and the hospital/medical specialization relating to the reservation.
+ *
+ * The class includes fields to store the reservation's details and two transient fields
+ * to optionally hold instances of {@code Hospital} and {@code MedicalSpecialization}.
+ *
+ * The class is marked as a JPA entity and includes annotations for
+ * automatic generation of boilerplate code such as getters, setters, and constructors.
+ */
 @Entity
 @Data
 @NoArgsConstructor
@@ -41,7 +55,16 @@ public class BedReservation {
     @Pattern(regexp = "\\+?[1-9]\\d{1,14}", message = "Invalid phone number format") // E.164 International Format pattern
     private String reservationPhoneNumber;
 
-    // Constructor to initialize all fields
+    /**
+     * Constructs a new instance of BedReservation with the specified parameters.
+     *
+     * @param hospitalId the unique identifier of the hospital where the reservation is being made
+     * @param medicalSpecializationId the unique identifier of the medical specialization for which the bed reservation is requested
+     * @param reservationFirstName the first name of the individual for whom the bed reservation is being made
+     * @param reservationLastName the last name of the individual for whom the bed reservation is being made
+     * @param reservationEmail the email address of the individual for whom the bed reservation is being made
+     * @param reservationPhoneNumber the phone number of the individual for whom the bed reservation is being made
+     */
     public BedReservation(Long hospitalId, Long medicalSpecializationId, String reservationFirstName, String reservationLastName, String reservationEmail, String reservationPhoneNumber) {
         this.hospitalId = hospitalId;
         this.medicalSpecializationId = medicalSpecializationId;

backend/emergency-service/src/main/java/com/swyth/emergencyservice/exception/BedUnavailableException.java

@@ -1,5 +1,21 @@
 package com.swyth.emergencyservice.exception;
 
+/**
+ * BedUnavailableException is a custom runtime exception that is thrown
+ * when no available beds are found in a hospital for a specific medical
+ * specialization.
+ *
+ * This exception typically represents a scenario where the requested
+ * resource (e.g., hospital bed) is not available, and can be utilized in
+ * applications to provide meaningful error messages and responses for clients.
+ *
+ * The exception can be handled globally or at a method level, providing
+ * additional context such as timestamps, HTTP status codes, and error messages.
+ *
+ * Constructors:
+ * - BedUnavailableException(String message): Constructs the exception with a
+ *   specific detail message about the unavailability of resources.
+ */
 public class BedUnavailableException extends RuntimeException {
     public BedUnavailableException(String message) {
         super(message);

backend/emergency-service/src/main/java/com/swyth/emergencyservice/exception/GlobalExceptionHandler.java

@@ -14,9 +14,19 @@
 import java.util.LinkedHashMap;
 import java.util.Map;
 
+/**
+ * GlobalExceptionHandler is a centralized exception handler class that provides
+ * consistent error responses for exceptions occurring throughout the application.
+ *
+ * This class uses the @ControllerAdvice annotation to enable global exception
+ * handling across the application's controllers. It contains methods annotated
+ * with @ExceptionHandler to handle specific exceptions and tailor the error
+ * responses accordingly.
+ */
 @ControllerAdvice
 public class GlobalExceptionHandler {
 
+
     // Handle bad formatted requests
     @ExceptionHandler(WebExchangeBindException.class)
     public ResponseEntity<Map<String, Object>> handleWebExchangeBindException(WebExchangeBindException ex, ServerWebExchange exchange) {

backend/emergency-service/src/main/java/com/swyth/emergencyservice/feign/HospitalBedAvailabilityRestClient.java

@@ -12,6 +12,20 @@
 
 import java.net.http.HttpResponse;
 
+/**
+ * Feign client interface for interacting with the hospital-service API to check bed availability.
+ *
+ * This interface defines a method to communicate with the hospital-service endpoint
+ * responsible for verifying availability of hospital beds based on the provided hospital ID
+ * and medical specialization ID. The underlying HTTP call is made using Feign, and
+ * request/response handling is configured with the FeignConfig class.
+ *
+ * The method in this interface sends an HTTP POST request to the /v1/bed-availabilities/check endpoint
+ * and expects a response indicating whether a bed is available or not.
+ *
+ * The Feign client is annotated with @FeignClient to mark it as a declarative REST client, and
+ * utilizes configurations from the FeignConfig class for decoding, encoding, and error handling.
+ */
 @FeignClient(name = "hospital-service", configuration = FeignConfig.class)
 public interface HospitalBedAvailabilityRestClient {
     @RequestMapping(method = RequestMethod.POST, value = "/v1/bed-availabilities/check", consumes = "application/json")

backend/emergency-service/src/main/java/com/swyth/emergencyservice/model/Hospital.java

@@ -2,6 +2,18 @@
 
 import lombok.Data;
 
+/**
+ * Represents a hospital entity with relevant details such as its name, address,
+ * location coordinates, and other identifying attributes.
+ *
+ * This class is used to model and store information about hospitals. It primarily
+ * acts as a data container to keep track of a hospital's detailed attributes,
+ * such as its unique identifier, geographical location, and address.
+ *
+ * Instances of this class can be used in various contexts, such as hospital
+ * management systems, medical reservation systems, and location-based healthcare
+ * services.
+ */
 @Data
 public class Hospital {
     private Long id;

backend/emergency-service/src/main/java/com/swyth/emergencyservice/model/HospitalMedicalSpecializationAvailability.java

@@ -2,6 +2,12 @@
 
 import lombok.Data;
 
+/**
+ * Represents the availability of a specific medical specialization in a hospital.
+ * This class encapsulates information about a hospital, including its location,
+ * address, available beds, and other details related to the availability of
+ * medical services.
+ */
 @Data
 public class HospitalMedicalSpecializationAvailability {
     private Long id;

backend/emergency-service/src/main/java/com/swyth/emergencyservice/model/MedicalSpecialization.java

@@ -4,6 +4,21 @@
 
 import java.util.Collection;
 
+/**
+ * Represents a specific medical specialization, such as Cardiology, Neurology, or Pediatrics.
+ * This class is used to encapsulate information about a particular specialization,
+ * grouping common medical practices and facilitating the organization of healthcare services.
+ *
+ * Instances of this class are used to identify and manage various medical specializations.
+ * They are also associated with the availability of these specializations in hospitals.
+ *
+ * Fields of this class include:
+ * - An identifier for the specialization.
+ * - A name that describes the specialization.
+ * - A group to categorize the specialization.
+ * - A collection of hospital specialization availability references, which provide
+ *   details about the availability of this specialization in different hospitals.
+ */
 @Data
 public class MedicalSpecialization {
     private Long id;

backend/emergency-service/src/main/java/com/swyth/emergencyservice/repository/BedReservationRepository.java

@@ -4,6 +4,24 @@
 import org.springframework.data.jpa.repository.JpaRepository;
 import org.springframework.stereotype.Repository;
 
+/**
+ * Repository interface for managing {@link BedReservation} entities.
+ *
+ * This interface provides CRUD operations and additional query methods for
+ * accessing and manipulating the `BedReservation` data in the underlying database.
+ * It extends {@link JpaRepository}, inheriting a comprehensive set of persistence and
+ * query capabilities including methods for saving, updating, deleting, and retrieving
+ * `BedReservation` entities.
+ *
+ * The repository is marked with the {@link Repository} annotation, indicating its role
+ * as a data access component in the Spring Data JPA framework.
+ *
+ * Typical use cases include:
+ * - Storing newly created bed reservations.
+ * - Retrieving specific reservations by their ID or other criteria.
+ * - Removing outdated or canceled reservations.
+ * - Updating details of existing reservations.
+ */
 @Repository
 public interface BedReservationRepository extends JpaRepository<BedReservation, Long> {
 }