From 1fbdaa0c5e1f204cbf027441157e1a99569de704 Mon Sep 17 00:00:00 2001 From: Devon Hillard Date: Wed, 26 Feb 2025 19:15:16 -0700 Subject: [PATCH] Fix inaccurate Javadoc on confirmRegistration method and improve other Javadoc comments MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fixed incorrect description in UserActionController.confirmRegistration - Fixed parameter name in UserVerificationService.getVerificationToken - Updated return type description in UserVerificationService.validateVerificationToken - Removed duplicate class-level Javadoc in UserService - Enhanced Javadoc for key methods with more thorough descriptions - Added security warning to authWithoutPassword method 🤖 Generated with Claude Code Co-Authored-By: Claude --- .../user/controller/UserActionController.java | 12 +++---- .../spring/user/service/UserService.java | 35 ++++++++++--------- .../user/service/UserVerificationService.java | 23 ++++++------ 3 files changed, 37 insertions(+), 33 deletions(-) diff --git a/src/main/java/com/digitalsanctuary/spring/user/controller/UserActionController.java b/src/main/java/com/digitalsanctuary/spring/user/controller/UserActionController.java index 73d2b13..631699e 100644 --- a/src/main/java/com/digitalsanctuary/spring/user/controller/UserActionController.java +++ b/src/main/java/com/digitalsanctuary/spring/user/controller/UserActionController.java @@ -89,13 +89,13 @@ public ModelAndView showChangePasswordPage(final HttpServletRequest request, fin } /** - * Validate a forgot password token link from an email, and if valid, show the - * registration success page. + * Validates a registration token received from an email link, and if valid, + * confirms the user's registration and redirects to the registration success page. * - * @param request the request - * @param model the model - * @param token the token - * @return the model and view + * @param request the HTTP request + * @param model the model map + * @param token the verification token to validate + * @return the model and view for redirection * @throws UnsupportedEncodingException the unsupported encoding exception */ @GetMapping("${user.security.registrationConfirmURI:/user/registrationConfirm}") diff --git a/src/main/java/com/digitalsanctuary/spring/user/service/UserService.java b/src/main/java/com/digitalsanctuary/spring/user/service/UserService.java index 210b909..4d86db1 100644 --- a/src/main/java/com/digitalsanctuary/spring/user/service/UserService.java +++ b/src/main/java/com/digitalsanctuary/spring/user/service/UserService.java @@ -34,17 +34,12 @@ import lombok.extern.slf4j.Slf4j; /** - * Service class for managing users. It includes methods for user authentication, registration, deletion, password management, role assignment, and - * related operations. This class also interacts with the user repository and session registry to perform its tasks. + * Service class for managing users. Provides methods for user registration, authentication, password management, and user-related operations. This + * class is transactional and uses various repositories and services for its operations. * *

* This class is transactional, meaning that any failure causes the entire operation to roll back to the previous state. - * - * @author Devon Hillard - */ -/** - * Service class for managing users. Provides methods for user registration, authentication, password management, and user-related operations. This - * class is transactional and uses various repositories and services for its operations. + *

* *

* Dependencies: @@ -112,6 +107,8 @@ *

  • {@link Transactional}: Indicates that the class or methods should be transactional.
    • *
  • {@link Value}: Injects property values.
    • * + * + * @author Devon Hillard */ @Slf4j @Service @@ -199,10 +196,13 @@ public String getValue() { private boolean sendRegistrationVerificationEmail; /** - * Register new user account. + * Registers a new user account with the provided user data. + * If the email already exists, throws a UserAlreadyExistException. + * If sendRegistrationVerificationEmail is false, the user is enabled immediately. * - * @param newUserDto the new user dto - * @return the user + * @param newUserDto the data transfer object containing the user registration information + * @return the newly created user entity + * @throws UserAlreadyExistException if an account with the same email already exists */ public User registerNewUserAccount(final UserDto newUserDto) { TimeLogger timeLogger = new TimeLogger(log, "UserService.registerNewUserAccount"); @@ -371,12 +371,15 @@ public List getUsersFromSessionRegistry() { } /** - * Authenticates the given user without a password. The user is authenticated by loading their details, generating their authorities from their - * roles and privileges, and storing these details in the security context and session. This is a potentially dangerous method to call, as it will - * authenticate the user without requiring a password!!! We are using it here to allow us to authenticate a user after they have registered, - * without requiring them to log in again. + * Authenticates the given user without requiring a password. This method loads the user's details, + * generates their authorities from their roles and privileges, and stores these details in the + * security context and session. + * + *

    SECURITY WARNING: This is a potentially dangerous method as it authenticates + * a user without password verification. This method should only be used in specific controlled scenarios, + * such as after successful email verification or OAuth authentication.

    * - * @param user The user to authenticate. + * @param user The user to authenticate without password verification */ public void authWithoutPassword(User user) { log.debug("UserService.authWithoutPassword: authenticating user: {}", user); diff --git a/src/main/java/com/digitalsanctuary/spring/user/service/UserVerificationService.java b/src/main/java/com/digitalsanctuary/spring/user/service/UserVerificationService.java index 5874e83..7077375 100644 --- a/src/main/java/com/digitalsanctuary/spring/user/service/UserVerificationService.java +++ b/src/main/java/com/digitalsanctuary/spring/user/service/UserVerificationService.java @@ -43,20 +43,21 @@ public User getUserByVerificationToken(final String verificationToken) { } /** - * Gets the verification token. + * Gets the verification token by its string value. * - * @param VerificationToken the verification token - * @return the verification token + * @param verificationToken the verification token string + * @return the verification token entity */ - public VerificationToken getVerificationToken(final String VerificationToken) { - return tokenRepository.findByToken(VerificationToken); + public VerificationToken getVerificationToken(final String verificationToken) { + return tokenRepository.findByToken(verificationToken); } /** - * Generate new verification token. + * Generates a new verification token to replace an existing one. + * Useful for extending verification periods or re-sending verification emails. * - * @param existingVerificationToken the existing verification token - * @return the verification token + * @param existingVerificationToken the existing verification token string to replace + * @return the updated verification token entity with a new token value */ public VerificationToken generateNewVerificationToken(final String existingVerificationToken) { VerificationToken vToken = tokenRepository.findByToken(existingVerificationToken); @@ -77,10 +78,10 @@ public void createVerificationTokenForUser(final User user, final String token) } /** - * Validate verification token. + * Validates a user verification token. * - * @param token the token - * @return the string + * @param token the token to validate + * @return the token validation result (VALID, INVALID_TOKEN, or EXPIRED) */ public UserService.TokenValidationResult validateVerificationToken(String token) { final VerificationToken verificationToken = tokenRepository.findByToken(token);