doc(backend): document hospital-service with javadoc

Author: swyth-dev

backend/hospital-service/src/main/java/com/swyth/hospitalservice/controller/HospitalBedAvailabilityController.java

@@ -8,17 +8,61 @@
 import org.springframework.stereotype.Controller;
 import org.springframework.web.bind.annotation.*;
 
+/**
+ * Controller class for managing hospital bed availability.
+ *
+ * This class defines endpoints for checking the availability of hospital beds for
+ * a specific medical specialization in a given hospital. It interacts with the
+ * {@code HospitalBedAvailabilityService} to perform the required operations.
+ *
+ * Features:
+ * - Defines RESTful endpoint for checking bed availability.
+ * - Handles required request parameters and delegates processing to the service layer.
+ *
+ * Endpoint Mapping:
+ * - Base URL: /v1/bed-availabilities
+ *
+ * Functionalities:
+ * - Verifies hospital bed availability for the given medical specialization and hospital ID.
+ * - Throws appropriate exceptions when no beds are available.
+ *
+ * Annotations:
+ * - {@code @Controller}: Identifies this class as a Spring Controller.
+ * - {@code @ResponseBody}: Indicates that the return value of the methods will be serialized
+ *   directly into the HTTP response body.
+ * - {@code @RequestMapping}: Maps incoming web requests to specific controller methods.
+ *
+ * Constructor:
+ * - Accepts a {@code HospitalBedAvailabilityService} for managing bed availability data.
+ *
+ * Exceptions:
+ * - Throws {@code BedUnavailableException} if no beds are available for the specified
+ *   inputs.
+ */
 @Controller
 @ResponseBody
 @RequestMapping("/v1/bed-availabilities")
-//@CrossOrigin(origins = "*", allowedHeaders = "*") //TODO: don't let it like that in Production env
 public class HospitalBedAvailabilityController {
     private final HospitalBedAvailabilityService hospitalBedAvailabilityService;
 
     public HospitalBedAvailabilityController(HospitalBedAvailabilityService hospitalBedAvailabilityService) {
         this.hospitalBedAvailabilityService = hospitalBedAvailabilityService;
     }
 
+    /**
+     * Checks the availability of hospital beds for a specified medical specialization
+     * in a given hospital.
+     *
+     * This endpoint queries the hospital bed availability service to determine if there are
+     * available beds for the provided medical specialization and hospital ID. If no beds
+     * are available, a {@code BedUnavailableException} is thrown.
+     *
+     * @param medicalSpecializationId the unique identifier of the medical specialization
+     * @param hospitalId the unique identifier of the hospital
+     * @return a {@code ResponseEntity} containing a boolean value indicating whether at least
+     *         one bed is available
+     * @throws BedUnavailableException if no beds are available for the specified medical specialization and hospital
+     */
     @PostMapping("/check")
     public ResponseEntity<Boolean> checkBedAvailability(
             @NotNull @RequestParam("medicalSpecializationId") Long medicalSpecializationId,

backend/hospital-service/src/main/java/com/swyth/hospitalservice/controller/HospitalController.java

@@ -13,10 +13,26 @@
 
 import java.util.List;
 
+/**
+ * Controller for managing hospital-related endpoints.
+ *
+ * This controller serves as the entry point for hospital-related API requests,
+ * such as fetching details about all hospitals, retrieving a specific hospital by ID,
+ * and finding the nearest hospital based on a given location and medical specialization.
+ * It interacts with the service layer {@link HospitalService} to fetch and process hospital data.
+ *
+ * Endpoints:
+ * - GET /v1/hospitals: Retrieves a list of all hospitals.
+ * - GET /v1/hospitals/{id}: Fetches details of a specific hospital by its ID.
+ * - POST /v1/hospitals/nearest: Finds the nearest hospital based on location and specialization.
+ *
+ * Annotations:
+ * - {@code @Controller} and {@code @RestController}: Indicates this is a Spring controller for REST APIs.
+ * - {@code @RequestMapping("/v1/hospitals")}: Maps all endpoints to the base path.
+ */
 @Controller
 @RestController
 @RequestMapping("/v1/hospitals")
-//@CrossOrigin(origins = "*", allowedHeaders = "*") //TODO: don't let it like that in Production env
 public class HospitalController {
     private final HospitalService hospitalService;
 

backend/hospital-service/src/main/java/com/swyth/hospitalservice/controller/MedicalSpecializationController.java

@@ -9,25 +9,56 @@
 
 import java.util.List;
 
+/**
+ * Controller for managing medical specializations.
+ *
+ * This controller provides RESTful endpoints for retrieving information about
+ * medical specializations. It acts as an entry point for client requests related
+ * to medical specialization data. The controller delegates business logic
+ * operations to the {@code MedicalSpecializationService}.
+ *
+ * Mappings and Responsibilities:
+ * - Handles HTTP GET requests for retrieving all medical specializations.
+ * - Handles HTTP GET requests for retrieving a specific medical specialization by ID.
+ *
+ * Exceptions:
+ * - Throws {@code ResourceNotFoundException} when no specializations are found or
+ *   the requested specialization ID does not exist.
+ *
+ * Dependencies:
+ * - {@code MedicalSpecializationService}: Used to perform business logic and
+ *   interact with the underlying data repository.
+ *
+ * Typical Use Cases:
+ * - Listing all available medical specializations.
+ * - Fetching details of a specific medical specialization identified by its ID.
+ *
+ * Annotations:
+ * - {@code @Controller}: Indicates that this class serves as a web controller.
+ * - {@code @RestController}: Combines {@code @Controller} and {@code @ResponseBody},
+ *   providing convenient configuration for REST APIs.
+ * - {@code @RequestMapping}: Maps HTTP requests to methods within this controller.
+ */
 @Controller
 @RestController
 @RequestMapping("/v1/specializations")
-//@CrossOrigin(origins = "*", allowedHeaders = "*") //TODO: don't let it like that in Production env
 public class MedicalSpecializationController {
     private final MedicalSpecializationService medicalSpecializationService;
 
     public MedicalSpecializationController(MedicalSpecializationService medicalSpecializationService) {
         this.medicalSpecializationService = medicalSpecializationService;
     }
 
-    /*
-    - Get all specializations
-    - Get nearest hospital (param : spec id & son adresse) -> Hopital le plus proche
-    - Check if bed availabe for specialization and hospital id
-    - Reserver le lit (param : spec id & hospital id) -> Reservation (id reservation, info hopital, info specialization)
-
-    Endpoints en plus :
-
+    /**
+     * Retrieves a list of all available medical specializations.
+     *
+     * This method handles HTTP GET requests to fetch all medical specializations
+     * from the system. It uses the {@code MedicalSpecializationService} to retrieve the data.
+     * If no specializations are found, a {@code ResourceNotFoundException} is thrown.
+     *
+     * @return A {@code ResponseEntity} containing a list of {@code MedicalSpecializationDTO} objects,
+     * representing the details of all medical specializations available in the system.
+     * If no data is found, it throws a {@code ResourceNotFoundException}.
      */
     @GetMapping("")
     public ResponseEntity<List<MedicalSpecializationDTO>> getMedicalSpecializations() {

backend/hospital-service/src/main/java/com/swyth/hospitalservice/dto/BedReservationDTO.java

@@ -2,6 +2,30 @@
 
 import lombok.Data;
 
+/**
+ * Represents a Data Transfer Object (DTO) for reserving hospital beds.
+ *
+ * This class encapsulates the details required for reserving a hospital bed
+ * associated with a specific hospital and medical specialization. It serves
+ * as an intermediary object for transferring data between layers, such as
+ * between a client and service, or a service and repository.
+ *
+ * Attributes:
+ * - id: The unique identifier for the bed reservation.
+ * - hospitalId: The unique identifier of the hospital where the bed reservation is being made.
+ * - medicalSpecializationId: The unique identifier of the medical specialization related to the bed reservation.
+ *
+ * Usage Context:
+ * - This DTO is used primarily in operations that involve updating or querying
+ *   hospital bed availability for specific medical specializations and hospitals.
+ * - It facilitates the transfer of the required data without exposing the complete
+ *   internal details of the entities involved, such as hospital or specialization objects.
+ *
+ * Features:
+ * - Encapsulates the key details required for reserving a hospital bed.
+ * - Works with service methods that update or check hospital bed availability.
+ * - Simplifies service method inputs by wrapping necessary identifiers into a single object.
+ */
 @Data
 public class BedReservationDTO {
     private Long id;

backend/hospital-service/src/main/java/com/swyth/hospitalservice/dto/EmergencyLocationDTO.java

@@ -3,6 +3,26 @@
 import jakarta.validation.constraints.NotNull;
 import lombok.Data;
 
+/**
+ * The EmergencyLocationDTO class is a data transfer object used to encapsulate the location
+ * and medical specialization information required for identifying the nearest hospital.
+ *
+ * It contains the following fields:
+ * - medicalSpecializationId: Represents the unique identifier for a specific medical specialization.
+ * - latitude: Specifies the latitude coordinate of the location.
+ * - longitude: Specifies the longitude coordinate of the location.
+ *
+ * This class provides the necessary data for operations such as calculating proximity to
+ * hospitals based on geographical coordinates and filtering by medical specialization.
+ *
+ * Validation annotations are applied to ensure that the fields are not null when the object
+ * is used in service or controller layers. This helps prevent invalid or incomplete data
+ * from being processed.
+ *
+ * The class is typically utilized as an input parameter in API endpoints that deal with
+ * location-based querying, such as finding the nearest hospital with available beds for
+ * a specified medical specialty.
+ */
 @Data
 public class EmergencyLocationDTO {
     @NotNull(message = "Medical specialization ID must not be null")

backend/hospital-service/src/main/java/com/swyth/hospitalservice/dto/HospitalDTO.java

@@ -7,6 +7,29 @@
 
 import java.util.List;
 
+/**
+ * Data Transfer Object (DTO) for representing hospital information.
+ *
+ * This class is used to encapsulate and transfer hospital data between layers of the
+ * application, typically from the service layer to the presentation layer. The DTO includes
+ * details about the hospital such as its name, location, and available specializations with
+ * their corresponding bed counts.
+ *
+ * Attributes:
+ * - id: Unique identifier for the hospital.
+ * - name: Name of the hospital.
+ * - address: Address of the hospital.
+ * - postCode: Postal code of the hospital's location.
+ * - city: City where the hospital is located.
+ * - latitude: Geographical latitude coordinate of the hospital.
+ * - longitude: Geographical longitude coordinate of the hospital.
+ * - specializations: List of medical specializations available in the hospital along with
+ *   the number of beds available for each specialization.
+ *
+ * Annotations:
+ * - The class is annotated with Lombok annotations (@Data, @NoArgsConstructor, @AllArgsConstructor)
+ *   to auto-generate getters, setters, equals, hashCode, and constructors.
+ */
 @Data
 @NoArgsConstructor
 @AllArgsConstructor

backend/hospital-service/src/main/java/com/swyth/hospitalservice/dto/HospitalDtoMapper.java

@@ -7,6 +7,34 @@
 import java.util.Set;
 import java.util.stream.Collectors;
 
+/**
+ * Utility class for mapping Hospital entities to their corresponding HospitalDTO representations.
+ *
+ * This class provides static methods for converting Hospital entities and collections of Hospital
+ * entities to data transfer objects (DTOs), making it easier to transfer data between application
+ * layers while decoupling the internal entity model from external representations.
+ *
+ * Features:
+ * - Converts a single Hospital entity to a HospitalDTO.
+ * - Converts a collection of Hospital entities (Set) to a list of HospitalDTOs, sorted by hospital ID.
+ *
+ * Methods:
+ * - The conversion process includes mapping hospital attributes (ID, name, address, etc.) and
+ *   available bed information for each medical specialization into the DTO.
+ * - Ensures the output DTOs are sorted by unique identifiers for consistency in representation.
+ *
+ * Annotations:
+ * - The class is utilitarian in purpose and is marked with a private constructor to prevent
+ *   instantiation.
+ *
+ * Usage:
+ * - The methods are designed to be used statically in services or business logic handling hospital
+ *   data transformation.
+ *
+ * Purpose:
+ * - Centralizes and standardizes the entity-to-DTO conversion logic, reducing code duplication
+ *   and ensuring consistency across the application.
+ */
 public class HospitalDtoMapper {
 
     private HospitalDtoMapper() {

backend/hospital-service/src/main/java/com/swyth/hospitalservice/dto/MedicalSpecializationDTO.java

@@ -7,6 +7,26 @@
 
 import java.util.List;
 
+/**
+ * Data Transfer Object (DTO) for representing information about a medical specialization.
+ *
+ * This class is designed to facilitate the transfer of data between layers in the application by encapsulating
+ * information about a medical specialization. It includes details about the specialization itself and
+ * a list of associated hospital availability details.
+ *
+ * Attributes:
+ * - id: The unique identifier of the medical specialization.
+ * - name: The name of the medical specialization (e.g., Cardiology, Neurology).
+ * - group: The category or group to which the specialization belongs.
+ * - hospitals: A list of hospital availability information associated with this specialization. This includes
+ *   details about hospitals, such as name, address, geographic location, and bed availability.
+ *
+ * Annotations:
+ * - Lombok annotations are used to simplify the code:
+ *      - @Data: Generates getters, setters, and other utility methods.
+ *      - @NoArgsConstructor: Generates a no-argument constructor.
+ *      - @AllArgsConstructor: Generates an all-argument constructor.
+ */
 @Data
 @NoArgsConstructor
 @AllArgsConstructor

backend/hospital-service/src/main/java/com/swyth/hospitalservice/dto/MedicalSpecializationDtoMapper.java

@@ -12,6 +12,16 @@ public class MedicalSpecializationDtoMapper {
     private MedicalSpecializationDtoMapper() {
     }
 
+    /**
+     * Converts a {@link MedicalSpecialization} entity to a {@link MedicalSpecializationDTO}.
+     *
+     * This method transforms a {@link MedicalSpecialization} object into its corresponding
+     * Data Transfer Object (DTO), encapsulating details such as the specialization's ID,
+     * name, group, and associated hospital availability information.
+     *
+     * @param specialization the {@link MedicalSpecialization} entity to be converted
+     * @return the corresponding {@link MedicalSpecializationDTO} containing the transformed data
+     */
     public static MedicalSpecializationDTO convertToDTO(MedicalSpecialization specialization) {
         return new MedicalSpecializationDTO(
                 specialization.getId(),

backend/hospital-service/src/main/java/com/swyth/hospitalservice/dto/NearestHospitalDTO.java

@@ -4,6 +4,26 @@
 import lombok.Data;
 import lombok.NoArgsConstructor;
 
+/**
+ * Data Transfer Object (DTO) representing the nearest hospital.
+ * This class is used for encapsulating details of the nearest hospital such as its
+ * identification, name, address, location, and geographic coordinates.
+ *
+ * Fields:
+ * - id: Unique identifier of the hospital.
+ * - name: Name of the hospital.
+ * - address: Complete address of the hospital.
+ * - postCode: Postal code of the hospital location.
+ * - city: City where the hospital is located.
+ * - latitude: Geographical latitude coordinate of the hospital.
+ * - longitude: Geographical longitude coordinate of the hospital.
+ *
+ * Commonly used for transferring data related to the nearest hospital, especially in
+ * scenarios involving hospital search functionalities.
+ *
+ * Includes default no-argument constructor, all-arguments constructor, as well as
+ * getter and setter methods for all fields, enabled by the Lombok annotations.
+ */
 @Data
 @NoArgsConstructor
 @AllArgsConstructor