From 3de5845f5bbe090311266fc66d28930b56f22074 Mon Sep 17 00:00:00 2001 From: "DESKTOP-E7L6HLO\\Noyan" Date: Tue, 9 Jul 2024 15:25:35 +0300 Subject: [PATCH] Task 23 : Add Java Doc information underneath common package --- .../exception/GlobalExceptionHandler.java | 81 +++++++++++++++++++ .../common/model/BaseDomainModel.java | 3 + .../common/model/CustomError.java | 9 +++ .../common/model/CustomPage.java | 15 +++- .../common/model/CustomPaging.java | 8 ++ .../dto/request/CustomPagingRequest.java | 9 +++ .../dto/response/CustomPagingResponse.java | 17 ++++ .../model/dto/response/CustomResponse.java | 16 +++- .../common/model/entity/BaseEntity.java | 12 +++ .../common/model/mapper/BaseMapper.java | 18 +++++ .../common/util/ListUtil.java | 11 +++ 11 files changed, 197 insertions(+), 2 deletions(-) diff --git a/src/main/java/com/security/rolepermissionexample/common/exception/GlobalExceptionHandler.java b/src/main/java/com/security/rolepermissionexample/common/exception/GlobalExceptionHandler.java index 17e0de8..aa27ed1 100644 --- a/src/main/java/com/security/rolepermissionexample/common/exception/GlobalExceptionHandler.java +++ b/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 handleMethodArgumentNotValid(final MethodArgumentNotValidException ex) { @@ -52,6 +61,12 @@ protected ResponseEntity 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 handlePathVariableErrors(final ConstraintViolationException constraintViolationException) { @@ -79,6 +94,12 @@ protected ResponseEntity 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 handlePasswordNotValidException(final PasswordNotValidException ex) { @@ -113,6 +146,12 @@ public ResponseEntity 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 handlePermissionNotFoundException(final PermissionNotFoundException ex) { @@ -125,6 +164,12 @@ public ResponseEntity 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 handleRoleNotFoundException(final RoleNotFoundException ex) { @@ -138,6 +183,12 @@ public ResponseEntity 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 handleTokenAlreadyInvalidatedException(final TokenAlreadyInvalidatedException ex) { CustomError error = CustomError.builder() @@ -150,6 +201,12 @@ public ResponseEntity 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 handleUserAlreadyExistException(final UserAlreadyExistException ex) { CustomError error = CustomError.builder() @@ -161,6 +218,12 @@ public ResponseEntity 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 handleUserNotFoundException(final UserNotFoundException ex) { CustomError error = CustomError.builder() @@ -172,6 +235,12 @@ public ResponseEntity 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 handleUserStatusNotValidException(final UserStatusNotValidException ex) { CustomError error = CustomError.builder() @@ -183,6 +252,12 @@ public ResponseEntity 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 handleProductAlreadyExistException(final ProductAlreadyExistException ex) { CustomError error = CustomError.builder() @@ -195,6 +270,12 @@ public ResponseEntity 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 handleProductNotFoundException(final ProductNotFoundException ex) { CustomError error = CustomError.builder() diff --git a/src/main/java/com/security/rolepermissionexample/common/model/BaseDomainModel.java b/src/main/java/com/security/rolepermissionexample/common/model/BaseDomainModel.java index 1e1b805..71a13b0 100644 --- a/src/main/java/com/security/rolepermissionexample/common/model/BaseDomainModel.java +++ b/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 diff --git a/src/main/java/com/security/rolepermissionexample/common/model/CustomError.java b/src/main/java/com/security/rolepermissionexample/common/model/CustomError.java index 2332e4e..a853f67 100644 --- a/src/main/java/com/security/rolepermissionexample/common/model/CustomError.java +++ b/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 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 { diff --git a/src/main/java/com/security/rolepermissionexample/common/model/CustomPage.java b/src/main/java/com/security/rolepermissionexample/common/model/CustomPage.java index d43615d..5d4afe8 100644 --- a/src/main/java/com/security/rolepermissionexample/common/model/CustomPage.java +++ b/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} containing content and pagination details. + * + * @param the type of content in the page + */ @Getter @Builder @AllArgsConstructor @@ -19,7 +24,15 @@ public class CustomPage { 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 the type of domain model in the page + * @param the type of page + * @return a CustomPage instance mapped from the provided Page + */ public static CustomPage of(final List domainModels, final Page page) { return CustomPage.builder() .content(domainModels) diff --git a/src/main/java/com/security/rolepermissionexample/common/model/CustomPaging.java b/src/main/java/com/security/rolepermissionexample/common/model/CustomPaging.java index e7280b9..3615a54 100644 --- a/src/main/java/com/security/rolepermissionexample/common/model/CustomPaging.java +++ b/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; } diff --git a/src/main/java/com/security/rolepermissionexample/common/model/dto/request/CustomPagingRequest.java b/src/main/java/com/security/rolepermissionexample/common/model/dto/request/CustomPagingRequest.java index 15a9711..fae059e 100644 --- a/src/main/java/com/security/rolepermissionexample/common/model/dto/request/CustomPagingRequest.java +++ b/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()), diff --git a/src/main/java/com/security/rolepermissionexample/common/model/dto/response/CustomPagingResponse.java b/src/main/java/com/security/rolepermissionexample/common/model/dto/response/CustomPagingResponse.java index e58b3ac..bd674ac 100644 --- a/src/main/java/com/security/rolepermissionexample/common/model/dto/response/CustomPagingResponse.java +++ b/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}. + * Contains content list, page number, page size, total element count, and total page count. + * + * @param Type of content in the response. + */ @Getter @Builder public class CustomPagingResponse { @@ -20,8 +26,19 @@ public class CustomPagingResponse { private Integer totalPageCount; + /** + * Builder class for CustomPagingResponse, allowing initialization from a CustomPage object. + * + * @param Type of content in the response. + */ public static class CustomPagingResponseBuilder { + /** + * Initializes the builder with data from a CustomPage object. + * + * @param customPage CustomPage object containing pagination data. + * @return CustomPagingResponseBuilder initialized with pagination details. + */ public CustomPagingResponseBuilder of(final CustomPage customPage) { return CustomPagingResponse.builder() .pageNumber(customPage.getPageNumber()) diff --git a/src/main/java/com/security/rolepermissionexample/common/model/dto/response/CustomResponse.java b/src/main/java/com/security/rolepermissionexample/common/model/dto/response/CustomResponse.java index caf7f9b..ad4f156 100644 --- a/src/main/java/com/security/rolepermissionexample/common/model/dto/response/CustomResponse.java +++ b/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} with standardized fields. + * + * @param Type of the response payload. + */ @Getter @Builder public class CustomResponse { @@ -21,12 +26,21 @@ public class CustomResponse { @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 SUCCESS = CustomResponse.builder() .httpStatus(HttpStatus.OK) .isSuccess(true) .build(); - + /** + * Creates a successful response with the provided payload and HTTP OK status. + * + * @param Type of the response payload. + * @param response Response payload. + * @return CustomResponse instance with success status, HTTP OK, and the provided payload. + */ public static CustomResponse successOf(final T response) { return CustomResponse.builder() .httpStatus(HttpStatus.OK) diff --git a/src/main/java/com/security/rolepermissionexample/common/model/entity/BaseEntity.java b/src/main/java/com/security/rolepermissionexample/common/model/entity/BaseEntity.java index 9771116..360bda8 100644 --- a/src/main/java/com/security/rolepermissionexample/common/model/entity/BaseEntity.java +++ b/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()) diff --git a/src/main/java/com/security/rolepermissionexample/common/model/mapper/BaseMapper.java b/src/main/java/com/security/rolepermissionexample/common/model/mapper/BaseMapper.java index ca90bf2..960f86a 100644 --- a/src/main/java/com/security/rolepermissionexample/common/model/mapper/BaseMapper.java +++ b/src/main/java/com/security/rolepermissionexample/common/model/mapper/BaseMapper.java @@ -3,10 +3,28 @@ import java.util.Collection; import java.util.List; +/** + * Interface for mapping entities or domain models (S) to DTOs (T). + * + * @param the source type to map from + * @param the target type to map to + */ public interface BaseMapper { + /** + * Maps a single source object to a target object. + * + * @param source the source object to map + * @return the mapped target object + */ T map(S source); + /** + * Maps a collection of source objects to a list of target objects. + * + * @param sources the collection of source objects to map + * @return the list of mapped target objects + */ List map(Collection sources); } diff --git a/src/main/java/com/security/rolepermissionexample/common/util/ListUtil.java b/src/main/java/com/security/rolepermissionexample/common/util/ListUtil.java index cb3cb28..f205d1b 100644 --- a/src/main/java/com/security/rolepermissionexample/common/util/ListUtil.java +++ b/src/main/java/com/security/rolepermissionexample/common/util/ListUtil.java @@ -4,9 +4,20 @@ import java.util.List; +/** + * Utility class named {@link ListUtil} for converting objects to lists. + */ @UtilityClass public class ListUtil { + /** + * Converts an object to a list of a specified class type. + * + * @param object The object to convert. + * @param clazz The target class type. + * @param The type of elements in the list. + * @return List of elements of type C. + */ public List to(Object object, Class clazz) { return (List) object; }