Task 23 : Add Java Doc information underneath common package

src/main/java/com/security/rolepermissionexample/common/exception/GlobalExceptionHandler.java

@@ -20,9 +20,18 @@
 import java.util.List;
 import java.util.Map;
 
+/**
+ * Global exception handler named {@link GlobalExceptionHandler} for handling various types of exceptions in the application.
+ */
 @RestControllerAdvice
 public class GlobalExceptionHandler {
 
+    /**
+     * Handles MethodArgumentNotValidException thrown when validation on an argument annotated with @Valid fails.
+     *
+     * @param ex The MethodArgumentNotValidException instance.
+     * @return ResponseEntity with CustomError containing details of validation errors.
+     */
     @ExceptionHandler(MethodArgumentNotValidException.class)
     protected ResponseEntity<Object> handleMethodArgumentNotValid(final MethodArgumentNotValidException ex) {
 
@@ -52,6 +61,12 @@ protected ResponseEntity<Object> handleMethodArgumentNotValid(final MethodArgume
 
     }
 
+    /**
+     * Handles ConstraintViolationException thrown when a bean validation constraint is violated.
+     *
+     * @param constraintViolationException The ConstraintViolationException instance.
+     * @return ResponseEntity with CustomError containing details of constraint violations.
+     */
     @ExceptionHandler(ConstraintViolationException.class)
     protected ResponseEntity<Object> handlePathVariableErrors(final ConstraintViolationException constraintViolationException) {
 
@@ -79,6 +94,12 @@ protected ResponseEntity<Object> handlePathVariableErrors(final ConstraintViolat
 
     }
 
+    /**
+     * Handles RuntimeException thrown for general runtime exceptions.
+     *
+     * @param runtimeException The RuntimeException instance.
+     * @return ResponseEntity with CustomError containing details of the runtime exception.
+     */
     @ExceptionHandler(RuntimeException.class)
     protected ResponseEntity<?> handleRuntimeException(final RuntimeException runtimeException) {
         CustomError customError = CustomError.builder()
@@ -90,6 +111,12 @@ protected ResponseEntity<?> handleRuntimeException(final RuntimeException runtim
         return new ResponseEntity<>(customError, HttpStatus.NOT_FOUND);
     }
 
+    /**
+     * Handles AccessDeniedException thrown when access to a resource is denied due to insufficient permissions.
+     *
+     * @param accessDeniedException The AccessDeniedException instance.
+     * @return ResponseEntity with CustomError indicating access denial.
+     */
     @ExceptionHandler(AccessDeniedException.class)
     protected ResponseEntity<?> handleAccessDeniedException(final AccessDeniedException accessDeniedException) {
         CustomError customError = CustomError.builder()
@@ -101,6 +128,12 @@ protected ResponseEntity<?> handleAccessDeniedException(final AccessDeniedExcept
         return new ResponseEntity<>(customError, HttpStatus.FORBIDDEN);
     }
 
+    /**
+     * Handles PasswordNotValidException thrown when a password does not meet validation criteria.
+     *
+     * @param ex The PasswordNotValidException instance.
+     * @return ResponseEntity with CustomError indicating password validation failure.
+     */
     @ExceptionHandler(PasswordNotValidException.class)
     public ResponseEntity<CustomError> handlePasswordNotValidException(final PasswordNotValidException ex) {
 
@@ -113,6 +146,12 @@ public ResponseEntity<CustomError> handlePasswordNotValidException(final Passwor
         return new ResponseEntity<>(error, HttpStatus.BAD_REQUEST);
     }
 
+    /**
+     * Handles PermissionNotFoundException thrown when a requested permission is not found.
+     *
+     * @param ex The PermissionNotFoundException instance.
+     * @return ResponseEntity with CustomError indicating permission not found.
+     */
     @ExceptionHandler(PermissionNotFoundException.class)
     public ResponseEntity<CustomError> handlePermissionNotFoundException(final PermissionNotFoundException ex) {
 
@@ -125,6 +164,12 @@ public ResponseEntity<CustomError> handlePermissionNotFoundException(final Permi
         return new ResponseEntity<>(error, HttpStatus.NOT_FOUND);
     }
 
+    /**
+     * Handles RoleNotFoundException thrown when a requested role is not found.
+     *
+     * @param ex The RoleNotFoundException instance.
+     * @return ResponseEntity with CustomError indicating role not found.
+     */
     @ExceptionHandler(RoleNotFoundException.class)
     public ResponseEntity<CustomError> handleRoleNotFoundException(final RoleNotFoundException ex) {
 
@@ -138,6 +183,12 @@ public ResponseEntity<CustomError> handleRoleNotFoundException(final RoleNotFoun
         return new ResponseEntity<>(error, HttpStatus.NOT_FOUND);
     }
 
+    /**
+     * Handles TokenAlreadyInvalidatedException thrown when an attempt is made to use an already invalidated token.
+     *
+     * @param ex The TokenAlreadyInvalidatedException instance.
+     * @return ResponseEntity with CustomError indicating token already invalidated.
+     */
     @ExceptionHandler(TokenAlreadyInvalidatedException.class)
     public ResponseEntity<CustomError> handleTokenAlreadyInvalidatedException(final TokenAlreadyInvalidatedException ex) {
         CustomError error = CustomError.builder()
@@ -150,6 +201,12 @@ public ResponseEntity<CustomError> handleTokenAlreadyInvalidatedException(final
         return new ResponseEntity<>(error, HttpStatus.BAD_REQUEST);
     }
 
+    /**
+     * Handles UserAlreadyExistException thrown when an attempt is made to register a user with an existing email.
+     *
+     * @param ex The UserAlreadyExistException instance.
+     * @return ResponseEntity with CustomError indicating user already exists.
+     */
     @ExceptionHandler(UserAlreadyExistException.class)
     public ResponseEntity<CustomError> handleUserAlreadyExistException(final UserAlreadyExistException ex) {
         CustomError error = CustomError.builder()
@@ -161,6 +218,12 @@ public ResponseEntity<CustomError> handleUserAlreadyExistException(final UserAlr
         return new ResponseEntity<>(error, HttpStatus.CONFLICT);
     }
 
+    /**
+     * Handles UserNotFoundException thrown when a requested user is not found.
+     *
+     * @param ex The UserNotFoundException instance.
+     * @return ResponseEntity with CustomError indicating user not found.
+     */
     @ExceptionHandler(UserNotFoundException.class)
     public ResponseEntity<CustomError> handleUserNotFoundException(final UserNotFoundException ex) {
         CustomError error = CustomError.builder()
@@ -172,6 +235,12 @@ public ResponseEntity<CustomError> handleUserNotFoundException(final UserNotFoun
         return new ResponseEntity<>(error, HttpStatus.NOT_FOUND);
     }
 
+    /**
+     * Handles UserStatusNotValidException thrown when a user status is not valid for an operation.
+     *
+     * @param ex The UserStatusNotValidException instance.
+     * @return ResponseEntity with CustomError indicating invalid user status.
+     */
     @ExceptionHandler(UserStatusNotValidException.class)
     public ResponseEntity<CustomError> handleUserStatusNotValidException(final UserStatusNotValidException ex) {
         CustomError error = CustomError.builder()
@@ -183,6 +252,12 @@ public ResponseEntity<CustomError> handleUserStatusNotValidException(final UserS
         return new ResponseEntity<>(error, HttpStatus.BAD_REQUEST);
     }
 
+    /**
+     * Handles ProductAlreadyExistException thrown when an attempt is made to create a product that already exists.
+     *
+     * @param ex The ProductAlreadyExistException instance.
+     * @return ResponseEntity with CustomError indicating product already exists.
+     */
     @ExceptionHandler(ProductAlreadyExistException.class)
     public ResponseEntity<CustomError> handleProductAlreadyExistException(final ProductAlreadyExistException ex) {
         CustomError error = CustomError.builder()
@@ -195,6 +270,12 @@ public ResponseEntity<CustomError> handleProductAlreadyExistException(final Prod
         return new ResponseEntity<>(error, HttpStatus.CONFLICT);
     }
 
+    /**
+     * Handles ProductNotFoundException thrown when a requested product is not found.
+     *
+     * @param ex The ProductNotFoundException instance.
+     * @return ResponseEntity with CustomError indicating product not found.
+     */
     @ExceptionHandler(ProductNotFoundException.class)
     public ResponseEntity<CustomError> handleProductNotFoundException(final ProductNotFoundException ex) {
         CustomError error = CustomError.builder()

src/main/java/com/security/rolepermissionexample/common/model/BaseDomainModel.java

@@ -10,6 +10,9 @@
 
 import java.time.LocalDateTime;
 
+/**
+ * Base class named {@link BaseDomainModel} for domain models with common audit fields.
+ */
 @Getter
 @Setter
 @SuperBuilder

src/main/java/com/security/rolepermissionexample/common/model/CustomError.java

@@ -9,6 +9,9 @@
 import java.time.LocalDateTime;
 import java.util.List;
 
+/**
+ * Represents a custom error response named {@link CustomError} structure for REST APIs.
+ */
 @Getter
 @Builder
 public class CustomError {
@@ -29,6 +32,9 @@ public class CustomError {
     @JsonInclude(JsonInclude.Include.NON_NULL)
     private List<CustomSubError> subErrors;
 
+    /**
+     * Represents a sub-error with specific details as {@link CustomSubError}.
+     */
     @Getter
     @Builder
     public static class CustomSubError {
@@ -45,6 +51,9 @@ public static class CustomSubError {
 
     }
 
+    /**
+     * Enumerates common error headers for categorizing errors as {@link Header}.
+     */
     @Getter
     @RequiredArgsConstructor
     public enum Header {

src/main/java/com/security/rolepermissionexample/common/model/CustomPage.java

@@ -5,6 +5,11 @@
 
 import java.util.List;
 
+/**
+ * Represents a paginated response named {@link CustomPage<T>} containing content and pagination details.
+ *
+ * @param <T> the type of content in the page
+ */
 @Getter
 @Builder
 @AllArgsConstructor
@@ -19,7 +24,15 @@ public class CustomPage<T> {
 
     private Integer totalPageCount;
 
-
+    /**
+     * Constructs a CustomPage instance from a domain model page.
+     *
+     * @param domainModels the list of domain models in the page
+     * @param page         the Page object containing pagination information
+     * @param <C>          the type of domain model in the page
+     * @param <X>          the type of page
+     * @return a CustomPage instance mapped from the provided Page
+     */
     public static <C, X> CustomPage<C> of(final List<C> domainModels, final Page<X> page) {
         return CustomPage.<C>builder()
                 .content(domainModels)

src/main/java/com/security/rolepermissionexample/common/model/CustomPaging.java

@@ -7,6 +7,9 @@
 import lombok.Setter;
 import lombok.experimental.SuperBuilder;
 
+/**
+ * Represents pagination parameters for querying data as {@link CustomPaging}.
+ */
 @Getter
 @Setter
 @NoArgsConstructor
@@ -19,6 +22,11 @@ public class CustomPaging {
     @Min(value = 1, message = "Page size must be bigger than 0")
     private Integer pageSize;
 
+    /**
+     * Returns the zero-based page number for internal processing.
+     *
+     * @return the zero-based page number derived from the specified page number
+     */
     public Integer getPageNumber() {
         return pageNumber - 1;
     }

src/main/java/com/security/rolepermissionexample/common/model/dto/request/CustomPagingRequest.java

@@ -8,6 +8,10 @@
 import org.springframework.data.domain.PageRequest;
 import org.springframework.data.domain.Pageable;
 
+/**
+ * Represents a request object named {@link CustomPagingRequest} for custom paging configuration.
+ * Includes pagination details using CustomPaging.
+ */
 @Getter
 @Setter
 @SuperBuilder
@@ -16,6 +20,11 @@ public class CustomPagingRequest {
 
     private CustomPaging pagination;
 
+    /**
+     * Converts CustomPagingRequest to a Pageable object used for pagination in queries.
+     *
+     * @return Pageable object configured with page number and page size.
+     */
     public Pageable toPageable() {
         return PageRequest.of(
                 Math.toIntExact(pagination.getPageNumber()),

src/main/java/com/security/rolepermissionexample/common/model/dto/response/CustomPagingResponse.java

@@ -6,6 +6,12 @@
 
 import java.util.List;
 
+/**
+ * Represents a response object for custom paging named {@link CustomPagingResponse<T>}.
+ * Contains content list, page number, page size, total element count, and total page count.
+ *
+ * @param <T> Type of content in the response.
+ */
 @Getter
 @Builder
 public class CustomPagingResponse<T> {
@@ -20,8 +26,19 @@ public class CustomPagingResponse<T> {
 
     private Integer totalPageCount;
 
+    /**
+     * Builder class for CustomPagingResponse, allowing initialization from a CustomPage object.
+     *
+     * @param <T> Type of content in the response.
+     */
     public static class CustomPagingResponseBuilder<T> {
 
+        /**
+         * Initializes the builder with data from a CustomPage object.
+         *
+         * @param customPage CustomPage object containing pagination data.
+         * @return CustomPagingResponseBuilder initialized with pagination details.
+         */
         public <C> CustomPagingResponseBuilder<T> of(final CustomPage<C> customPage) {
             return CustomPagingResponse.<T>builder()
                     .pageNumber(customPage.getPageNumber())

src/main/java/com/security/rolepermissionexample/common/model/dto/response/CustomResponse.java

@@ -7,6 +7,11 @@
 
 import java.time.LocalDateTime;
 
+/**
+ * Represents a generic response object named {@link CustomResponse<T>} with standardized fields.
+ *
+ * @param <T> Type of the response payload.
+ */
 @Getter
 @Builder
 public class CustomResponse<T> {
@@ -21,12 +26,21 @@ public class CustomResponse<T> {
     @JsonInclude(JsonInclude.Include.NON_NULL)
     private T response;
 
+    /**
+     * Default successful response with HTTP OK status and success indicator set to true.
+     */
     public static final CustomResponse<Void> SUCCESS = CustomResponse.<Void>builder()
             .httpStatus(HttpStatus.OK)
             .isSuccess(true)
             .build();
 
-
+    /**
+     * Creates a successful response with the provided payload and HTTP OK status.
+     *
+     * @param <T>      Type of the response payload.
+     * @param response Response payload.
+     * @return CustomResponse instance with success status, HTTP OK, and the provided payload.
+     */
     public static <T> CustomResponse<T> successOf(final T response) {
         return CustomResponse.<T>builder()
                 .httpStatus(HttpStatus.OK)

src/main/java/com/security/rolepermissionexample/common/model/entity/BaseEntity.java

@@ -17,6 +17,10 @@
 import java.time.LocalDateTime;
 import java.util.Optional;
 
+/**
+ * Base entity class named {@link BaseEntity} with common fields for audit tracking and lifecycle management.
+ * Provides automatic population of audit fields using JPA lifecycle annotations.
+ */
 @Getter
 @Setter
 @SuperBuilder
@@ -37,6 +41,10 @@ public class BaseEntity {
     @Column(name = "UPDATED_BY")
     private String updatedBy;
 
+    /**
+     * Sets the createdBy and createdAt fields before persisting the entity.
+     * If no authenticated user is found, sets createdBy to "anonymousUser".
+     */
     @PrePersist
     public void prePersist() {
         this.createdBy = Optional.ofNullable(SecurityContextHolder.getContext().getAuthentication())
@@ -48,6 +56,10 @@ public void prePersist() {
         this.createdAt = LocalDateTime.now();
     }
 
+    /**
+     * Sets the updatedBy and updatedAt fields before updating the entity.
+     * If no authenticated user is found, sets updatedBy to "anonymousUser".
+     */
     @PreUpdate
     public void preUpdate() {
         this.updatedBy = Optional.ofNullable(SecurityContextHolder.getContext().getAuthentication())