docs(global): Optimised javadocs.

2023-09-15 15:36:25 +08:00
parent baa91f626a
commit 6549373e8d
46 changed files with 177 additions and 214 deletions
@@ -39,6 +39,7 @@ import java.util.UUID;
 *
 * @author hubin@baomidou
 * @since 1.1.0
+ * @version 1.1.0
 */
@Slf4j
 public final class AesUtil {
@@ -22,18 +22,15 @@ import java.nio.charset.StandardCharsets;
 import java.util.Base64;

 /**
- * <p>
 * The {@code Base64Util} class provides static methods to encode and decode
 * strings using Base64 encoding. It utilizes the {@link Base64} class from the
 * Java standard library for performing the encoding and decoding operations.
 * This utility class offers convenient methods to encode and decode strings
 * with different character sets.
- * 
 * <p>
 * This class is designed as a final class with a private constructor to
 * prevent instantiation. All methods in this class are static, allowing easy
 * access to the Base64 encoding and decoding functionality.
- * 
 * <p>
 * Example usage:
 * <pre>
@@ -47,15 +44,13 @@ import java.util.Base64;
 * String decoded = Base64Util.decode(encoded);
 * System.out.println("Decoded string: " + decoded);
 * </pre>
- *
 * <p>
 * <b>Note:</b> This utility class uses the default charset (UTF-8) if no
 * specific charset is provided. It is recommended to specify the charset
 * explicitly to ensure consistent encoding and decoding.
 *
- *
 * @author Zihlu Wang
- * @version 1.0.0
+ * @version 1.1.0
 * @since 1.0.0
 */
 public final class Base64Util {
@@ -23,19 +23,14 @@ import java.util.function.BooleanSupplier;
 import java.util.function.Supplier;

 /**
- * <p>
 * The BranchUtil class provides static methods to simplify conditional logic
 * in Java development by leveraging lambda expressions. It offers convenient
 * methods to replace verbose if...else statements with more concise and
 * expressive functional constructs.
- *
- *
 * <p>
 * Developers can use the methods in this utility class to streamline their
 * code, enhance readability, and promote a more functional style of
 * programming when dealing with branching logic and conditional statements.
- *
- *
 * <p>
 * <b>Example:</b>
 * <pre>
@@ -67,7 +62,6 @@ import java.util.function.Supplier;
 *         // do something
 *     });
 * </pre>
- *
 * <p>
 * <b>Note:</b>
 * The {@link #and(Boolean...)} and {@link #or(Boolean...)} methods accept any
@@ -75,7 +69,7 @@ import java.util.function.Supplier;
 *
 * @param <T> the type of the result to be handled by the methods
 * @author Zihlu Wang
- * @version 1.0.0
+ * @version 1.1.0
 * @see java.util.function.Supplier
 * @see java.util.function.BooleanSupplier
 * @see java.lang.Runnable
@@ -164,15 +158,12 @@ public final class BranchUtil<T> {
    }

    /**
-     * <p>
     * Handles the result of the boolean expressions by executing the
     * appropriate handler based on the result.
-     *
     * <p>
     * If the result is {@code true}, the {@code ifHandler} is executed. If the
     * result is {@code false} and an {@code elseHandler} is provided, it is
     * executed.
-     *
     * <p>
     * Returns the result of the executed handler.
     *
@@ -181,7 +172,8 @@ public final class BranchUtil<T> {
     * @param elseHandler the handler to be executed if the result is
     *                    {@code false} (optional)
     * @return the result of the executed handler, or {@code null} if no
-     * {@code elseHandler} is provided
+     * {@code elseHandler} is provided and the result of the evaluation is
+     * {@code false}
     */
    public T handle(Supplier<T> ifHandler, Supplier<T> elseHandler) {
        if (this.result && Objects.nonNull(ifHandler)) {
@@ -196,26 +188,23 @@ public final class BranchUtil<T> {
    }

    /**
-     * <p>
     * Handles the result of the boolean expressions by executing the provided
     * handler if the result is {@code true}.
-     *
     * <p>
     * Returns the result of the executed handler.
     *
     * @param ifHandler the handler to be executed if the result is
     *                  {@code true}
-     * @return the result of the executed handler
+     * @return the result of the executed handler, or {@code null} if result of
+     * evaluation is {@code false}
     */
    public T handle(Supplier<T> ifHandler) {
        return handle(ifHandler, null);
    }

    /**
-     * <p>
     * Handles the result of the boolean expressions by executing the
     * appropriate handler based on the result.
-     *
     * <p>
     * If the result is {@code true}, the {@code ifHandler} is executed. If the
     * result is {@code false} and an {@code elseHandler} is provided, it is
@@ -17,6 +17,8 @@

 package cn.org.codecrafters.devkit.utils;

+import lombok.Getter;
+
 import java.math.BigDecimal;
 import java.math.RoundingMode;
 import java.util.Objects;
@@ -24,10 +26,7 @@ import java.util.function.BiFunction;
 import java.util.function.Function;

 /**
- * <p>
 * Utility class for chained high-precision calculations using BigDecimal.
- *
- *
 * <p>
 * The ChainedCalcUtil class provides a convenient way to perform chained
 * high-precision calculations using BigDecimal. It allows users to perform
@@ -35,8 +34,6 @@ import java.util.function.Function;
 * and division with customizable precision and scale. By using this utility
 * class, developers can achieve accurate results and avoid precision loss
 * in their calculations.
- *
- *
 * <p>
 * <b>Usage:</b>
 * <pre>
@@ -85,7 +82,6 @@ import java.util.function.Function;
 *  </pre>
 * The above expressions perform various mathematical calculations using the
 * ChainedCalcUtil class.
- *
 * <p>
 * <b>Note:</b>
 * The ChainedCalcUtil class internally uses BigDecimal to handle
@@ -94,12 +90,17 @@ import java.util.function.Function;
 * for extremely large numbers or complex calculations.
 *
 * @author sunzsh
- * @version 1.0.0
+ * @version 1.1.0
 * @see java.math.BigDecimal
- * @since 9 Jul 2023
+ * @since 1.0.0
 */
+@Getter
 public final class ChainedCalcUtil {

+    /**
+     * -- GETTER --
+     * Returns the current value as a BigDecimal.
+     */
    private BigDecimal value;

    /**
@@ -234,15 +235,6 @@ public final class ChainedCalcUtil {
        return baseOperator(otherValue -> this.value.divide(otherValue, scale, RoundingMode.HALF_UP), other, beforeOperateScale);
    }

-    /**
-     * Returns the current value as a BigDecimal.
-     *
-     * @return the current value as a BigDecimal
-     */
-    public BigDecimal getValue() {
-        return value;
-    }
-
    /**
     * Returns the current value as a BigDecimal with the specified scale.
     *
@@ -25,15 +25,12 @@ import java.util.Objects;
 import java.util.Optional;

 /**
- * <p>
 * Utility class for performing hash operations on strings.
- *
 * <p>
 * The HashUtil class provides convenient methods for calculating various hash
 * functions on strings, including MD2, MD5, SHA-1, SHA-224, SHA-256, SHA-384,
 * and SHA-512. It allows developers to easily obtain the hash value of a given
 * string using different algorithms.
- *
 * <p>
 * Example usage:
 * <pre>
@@ -60,7 +57,6 @@ import java.util.Optional;
 * </pre>
 * The above examples demonstrate how to use the HashUtil class to calculate
 * hash values for a given string using different algorithms.
- *
 * <p>
 * <b>Note:</b>
 * The hash functions provided by the HashUtil class are one-way hash
@@ -69,7 +65,7 @@ import java.util.Optional;
 * password storage, but they should not be used for encryption purposes.
 *
 * @author Zihlu Wang
- * @version 1.0.0
+ * @version 1.1.0
 * @see java.security.MessageDigest
 * @since 1.0.0
 */
@@ -24,17 +24,15 @@ import java.util.HashMap;
 import java.util.Map;

 /**
- * <p>
 * MapUtil is a utility class that provides methods for converting objects to
 * maps and maps to objects.
- *
 * <p>
 * It also provides methods for getting and setting field values using
 * reflection.
 *
 * @author Zihlu Wang
- * @version 1.0.0
- * @since 16 Jul 2023
+ * @version 1.1.0
+ * @since 1.0.0
 */
@Slf4j
 public final class MapUtil {
@@ -18,17 +18,14 @@
 package cn.org.codecrafters.guid;

 /**
- * <p>
 * The {@code GuidCreator} is a generic interface for generating globally unique
 * identifiers (GUIDs) of a specific type.
- * 
 * <p>
 * The type of ID is determined by the class implementing this interface.
 *
- *
 * @param <IdType> this represents the type of the Global Unique Identifier
 * @author Zihlu Wang
- * @version 1.0.0
+ * @version 1.1.0
 * @since 1.0.0
 */
 public interface GuidCreator<IdType> {
@@ -23,9 +23,7 @@ import java.time.LocalDateTime;
 import java.time.ZoneOffset;

 /**
- * <p>
 * SnowflakeGuidCreator - GUID generator based on the Snowflake algorithm.
- *
 * <p>
 * The SnowflakeGuidCreator generates unique identifiers using the Snowflake
 * algorithm, which combines a timestamp, worker ID, and data center ID to
@@ -38,7 +36,6 @@ import java.time.ZoneOffset;
 *     <li>5 bits for worker ID</li>
 *     <li>12 bits for sequence number (per millisecond)</li>
 * </ul>
- *
 * <p>
 * When initializing the SnowflakeGuidCreator, you must provide the worker ID
 * and data center ID, ensuring they are within the valid range defined by the
@@ -48,7 +45,7 @@ import java.time.ZoneOffset;
 * repeated timestamps.
 *
 * @author Zihlu Wang
- * @version 1.0.0
+ * @version 1.1.0
 * @since 1.0.0
 */
 public final class SnowflakeGuidCreator implements GuidCreator<Long> {
@@ -18,28 +18,23 @@
 package cn.org.codecrafters.guid.exceptions;

 /**
- * <p>
 * The TimingException class represents an exception that is thrown when there
 * is an error related to time sequence.
- * 
 * <p>
 * This class extends the RuntimeException class, which means that instances of
 * TimingException do not need to be declared in a method or constructor's
 * throws clause.
- * 
 * <p>
 * Instances of TimingException can be created with or without a message and a
 * cause. The message provides a description of the exception, while the cause
 * represents the underlying cause of the exception and provides additional
 * information about the error.
- * 
 * <p>
 * TimingException is typically used to handle exceptions related to timing,
 * such as timeouts or synchronization issues. It is a subclass of
 * RuntimeException, which means it is an unchecked exception and does not need
 * to be caught or declared.
 *
- *
 * @author Zihlu Wang
 * @since 1.0.0
 */
@@ -16,17 +16,14 @@
 */

 /**
- * <p>
 * This package contains the custom exception classes related to GUID
 * generation. These exceptions are thrown when there are issues or errors
 * during the generation or processing of global unique identifiers (GUIDs).
- *
 * <p>
 * The main exception class in this package is {@link
 * cn.org.codecrafters.guid.exceptions.TimingException}, which is a runtime
 * exception and serves as the base exception for all other custom exceptions
 * related to GUID generation.
- *
 * <p>
 * Custom exceptions in this package provide specific information about the
 * type of error that occurred during GUID generation, making it easier for
@@ -34,7 +31,6 @@
 * GUIDs. They are designed to enhance the robustness and reliability of the
 * GUID generation process by providing clear and meaningful error messages to
 * the developers.
- *
 * <p>
 * Developers using the GUID generation module should be aware of the possible
 * exceptions that can be thrown and handle them appropriately to ensure smooth
@@ -16,15 +16,12 @@
 */

 /**
- * <p>
 * The package provides a set of tools for generating globally unique
 * identifiers (GUIDs).
- * 
 * <p>
 * The goal of this library is to provide an efficient, reliable way to
 * generate globally unique identifiers without requiring any specific
 * environment or configuration.
- * 
 * <p>
 * Key features include:
 * <ul>
@@ -55,7 +55,9 @@ import java.util.Optional;
 * The prefix to specify the encrypted value is {@code pg}.
 *
 * @author hubin@baomidou
+ * @version 1.1.0
 * @see org.springframework.boot.env.EnvironmentPostProcessor
+ * @since 1.1.0 (3.3.2 of MyBatis-Plus)
 */
 public class PropertyGuard implements EnvironmentPostProcessor {

@@ -39,19 +39,16 @@ import java.time.ZoneId;
 import java.util.*;

 /**
- * <p>
 * The {@code AuthzeroTokenResolver} class is an implementation of the {@link
 * cn.org.codecrafters.simplejwt.TokenResolver} interface. It uses the {@code
 * com.auth0:java-jwt} library to handle JSON Web Token (JWT) resolution. This
 * resolver provides functionality to create, extract, verify, and renew JWT
 * tokens using various algorithms and custom payload data.
- *
 * <p>
 * <b>Dependencies:</b>
 * This implementation relies on the {@code com.auth0:java-jwt} library. Please
 * ensure you have added this library as a dependency to your project before
 * using this resolver.
- *
 * <p>
 * <b>Usage:</b>
 * To use the {@code AuthzeroTokenResolver}, first, create an instance of this
@@ -63,11 +60,9 @@ import java.util.*;
 *                               "Token Issuer",
 *                               "Token Secret");
 * }</pre>
- *
 * <p>
 * Then, you can utilize the various methods provided by this resolver to
 * handle JWT tokens:
- *
 * <pre>{@code
 * // Creating a new JWT token
 * String token =
@@ -84,7 +79,6 @@ import java.util.*;
 * String renewedToken =
 *     tokenResolver.renew(token, Duration.ofMinutes(30), customPayloads);
 * }</pre>
- *
 * <p>
 * <b>Note:</b>
 * It is essential to configure the appropriate algorithms, secret, and issuer
@@ -93,7 +87,7 @@ import java.util.*;
 * correctly configured in your project's dependencies.
 *
 * @author Zihlu Wang
- * @version 1.0.0
+ * @version 1.1.0
 * @see GuidCreator
 * @see Algorithm
 * @see JWTVerifier
@@ -37,7 +37,6 @@ import java.util.function.Function;
 * the specific algorithms used by the Auth0 Java JWT library, which is the
 * underlying library used by AuthzeroTokenResolver to handle JSON Web Tokens
 * (JWTs).
- *
 * <p>
 * <b>Algorithm Mapping:</b>
 * The AuthzeroTokenResolverConfig class allows specifying the relationship
@@ -47,7 +46,6 @@ import java.util.function.Function;
 * keys are the standard TokenAlgorithm instances, and the values represent the
 * algorithm functions used by Auth0 Java JWT library for each corresponding
 * key.
- *
 * <p>
 * <b>Note:</b>
 * The provided algorithm mapping should be consistent with the actual
@@ -56,7 +54,7 @@ import java.util.function.Function;
 * and processing within the AuthzeroTokenResolver.
 *
 * @author Zihlu Wang
- * @version 1.0.0
+ * @version 1.1.0
 * @since 1.0.0
 */
 public final class AuthzeroTokenResolverConfig implements TokenResolverConfig<Function<String, Algorithm>> {
@@ -16,17 +16,14 @@
 */

 /**
- * <p>
 * The package {@code cn.org.codecrafters.simplejwt.authzero.config} contains
 * configuration classes related to the {@link
 * cn.org.codecrafters.simplejwt.authzero.AuthzeroTokenResolver}
 * implementation.
- *
 * <p>
 * The classes in this package provide configuration options and settings for
 * the {@link cn.org.codecrafters.simplejwt.authzero.AuthzeroTokenResolver},
 * which is used for resolving JSON Web Tokens (JWT) using the Auth0 library.
- *
 * <p>
 * The {@link
 * cn.org.codecrafters.simplejwt.authzero.config.AuthzeroTokenResolverConfig}
@@ -37,7 +34,6 @@
 * JWT algorithms. It enables developers to specify and customize the
 * algorithm functions according to the chosen JWT algorithm and the library
 * being used.
- *
 * <p>
 * The configuration options in this package help developers integrate and
 * configure the {@link
@@ -45,7 +41,6 @@
 * into their Spring Boot applications. Developers can fine-tune the token
 * resolution process and customize algorithm handling to align with their
 * specific requirements and desired level of security.
- *
 * <p>
 * It is recommended to explore the classes in this package to understand how
 * to configure and use the {@link
@@ -23,7 +23,6 @@
 * solutions for web and mobile applications. The classes in this package
 * provide the necessary functionality to handle JSON Web Tokens (JWTs) using
 * the {@code com.auth0:java-jwt} library.
- *
 * <p>
 * The main class in this package is the {@link
 * cn.org.codecrafters.simplejwt.authzero.AuthzeroTokenResolver}, which
@@ -33,14 +32,12 @@
 * {@code com.auth0:java-jwt} library. Developers can use this class as the
 * main token resolver in the Simple JWT project when integrating {@code
 * com.auth0:java-jwt} as the JWT management library.
- *
 * <p>
 * The {@code AuthzeroTokenResolver} relies on the {@code com.auth0:java-jwt}
 * library to handle the underlying JWT operations, including token creation,
 * validation, and extraction. It utilizes the {@code com.auth0:java-jwt}
 * {@code Algorithm} class to define and use different algorithms for JWT
 * signing and verification.
- *
 * <p>
 * To use the {@code AuthzeroTokenResolver}, developers must provide the
 * necessary configurations and dependencies, such as the {@code GuidCreator}
@@ -48,7 +45,6 @@
 * issuer name, and the secret key used for token signing and validation. The
 * {@code AuthzeroTokenResolverConfig} class provides a convenient way to
 * configure these dependencies.
- *
 * <p>
 * Developers using the {@code com.auth0:java-jwt} integration should be
 * familiar with the concepts and usage of the {@code com.auth0:java-jwt}
@@ -27,7 +27,7 @@ import java.util.Random;
 * passwords for various security-sensitive purposes.
 *
 * @author Zihlu Wang
- * @version 1.0.0
+ * @version 1.1.0
 * @since 1.0.0
 */
 public final class SecretCreator {
@@ -45,8 +45,8 @@ import java.util.Map;
 * }
 * </pre>
 *
+ * @version 1.1.0
 * @since 1.0.0
- * @version 1.0.0
 */
 public interface TokenPayload {

@@ -22,25 +22,21 @@ import java.time.Duration;
 import java.util.Map;

 /**
- * <p>
 * The {@code TokenResolver} interface defines methods for creating,
 * extracting, and renewing tokens, particularly JSON Web Tokens (JWTs). It
 * provides a set of methods to generate tokens with various payload
 * configurations, extract payload from tokens, and renew expired tokens.
- *
 * <p>
 * <b>Token Creation:</b>
 * The interface provides overloaded methods for creating tokens with different
 * payload configurations, including expiration time, audience, subject, and
 * custom payload data. Clients can choose the appropriate method based on
 * their specific token requirements.
- *
 * <p>
 * <b>Token Extraction:</b>
 * The interface includes methods to extract payload information from a given
 * token. Clients can use these methods to obtain the payload data encoded in
 * the token.
- *
 * <p>
 * <b>Token Renewal:</b>
 * The interface also offers methods for token renewal. Clients can renew an
@@ -50,7 +46,7 @@ import java.util.Map;
 * @param <ResolvedTokenType> the type of the result obtained by the
 *                            third-party library when parsing JWTs
 * @author Zihlu Wang
- * @version 1.0.0
+ * @version 1.1.0
 * @since 1.0.0
 */
 public interface TokenResolver<ResolvedTokenType> {
@@ -28,9 +28,8 @@ import java.lang.annotation.Target;
 * excluded from being automatically injected into the JSON Web Token (JWT)
 * payload during token generation. When a property is annotated with this
 * annotation, it will not be included as part of the JWT payload.
- *
- *
- * <p><b>Usage:</b>
+ * <p>
+ * <b>Usage:</b>
 * To exclude a property from the JWT payload, annotate the property with
 * {@code @ExcludeFromPayload}:
 *
@@ -45,14 +44,15 @@ import java.lang.annotation.Target;
 *     // Getters and setters...
 * }
 * }</pre>
- *
- * <p><b>Note:</b>
+ * <p>
+ * <b>Note:</b>
 * This annotation should be used only on properties that are not intended to
 * be included in the JWT payload due to their sensitive nature or for other
 * reasons. It is important to carefully choose which properties are excluded
 * from the payload to ensure the JWT remains secure and efficient.
 *
- * @version 1.0.0
+ * @author Zihlu Wang
+ * @version 1.1.0
 * @since 1.0.0
 */
@Retention(RetentionPolicy.RUNTIME)
@@ -22,7 +22,6 @@
 * properties of a data class to exclude them from being included as part
 * of the JWT payload.
 *
- * @version 1.0.0
 * @since 1.0.0
 */
 package cn.org.codecrafters.simplejwt.annotations;
@@ -20,10 +20,8 @@ package cn.org.codecrafters.simplejwt.config;
 import cn.org.codecrafters.simplejwt.constants.TokenAlgorithm;

 /**
- * <p>
 * The TokenResolverConfig interface provides a mechanism to configure a
 * TokenResolver with algorithm functions.
- *
 * <p>
 * This generic interface is used to define the configuration details for a
 * TokenResolver that utilizes algorithm functions. The interface allows for
@@ -16,12 +16,10 @@
 */

 /**
- * <p>
 * The classes in this package provide configuration options and settings for
 * the Simple JWT library. They are used to customize the behavior of the
 * library and allow developers to fine-tune various aspects of JWT generation
 * and validation.
- *
 * <p>
 * Other configuration classes may be added in the future to support additional
 * customization options and features. Developers using the Simple JWT library
@@ -23,8 +23,8 @@ import java.util.List;
 * The {@code PredefinedKeys} class contains constants for standard JSON Web Token (JWT) claims. These constants
 * represent the names of the standard claims that can be included in a JWT payload. Developers can use these constants
 * when working with JWTs to ensure consistent naming of the claims.
- *
- * <p>The class provides the following standard JWT claim constants:
+ * <p>
+ * The class provides the following standard JWT claim constants:
 * <ul>
 *     <li>{@link #ISSUER}: Represents the "iss" (Issuer) claim.</li>
 *     <li>{@link #SUBJECT}: Represents the "sub" (Subject) claim.</li>
@@ -34,13 +34,14 @@ import java.util.List;
 *     <li>{@link #ISSUED_AT}: Represents the "iat" (Issued At) claim.</li>
 *     <li>{@link #JWT_ID}: Represents the "jti" (JWT ID) claim.</li>
 * </ul>
- *
- * <p>The class also contains a list of all the standard claim constants, accessible via the {@link #KEYS} field. This
+ * <p>
+ * The class also contains a list of all the standard claim constants, accessible via the {@link #KEYS} field. This
 * list can be useful for iterating through all the standard claims or checking for the presence of specific claims.
- *
- * <p>Note: This class is final and cannot be instantiated. It only serves as a utility class to hold the standard JWT
+ * <p>
+ * Note: This class is final and cannot be instantiated. It only serves as a utility class to hold the standard JWT
 * claim constants.
 *
+ * @version 1.1.0
 * @since 1.0.0
 */
 public final class PredefinedKeys {
@@ -25,7 +25,6 @@ import lombok.Getter;
 * cryptographic algorithms to be used for secure token generation and
 * validation. This enum provides a list of supported algorithms to ensure
 * consistent usage and avoid potential security issues.
- *
 * <p><b>Supported Algorithms:</b>
 * This enum includes the following supported algorithms:
 * <ul>
@@ -40,7 +39,7 @@ import lombok.Getter;
 *     <li>{@link TokenAlgorithm#ES512}: ECDSA with SHA-512</li>
 * </ul>
 *
- * @version 1.0.0
+ * @version 1.1.0
 * @since 1.0.0
 */
@Getter
@@ -22,6 +22,5 @@
 * configuration parameters.
 *
 * @since 1.0.0
- * @version 1.0.0
 */
 package cn.org.codecrafters.simplejwt.constants;
@@ -18,15 +18,14 @@
 package cn.org.codecrafters.simplejwt.exceptions;

 /**
- * <p>
 * This {@code UnsupportedAlgorithmException} is to indicates that the given
 * algorithm is not supported by TokenResolver yet.
- * 
 * <p>
 * To support a specified algorithm, you could
 *
- *
 * @author Zihlu Wang
+ * @version 1.1.0
+ * @since 1.0.0
 */
 public class UnsupportedAlgorithmException extends RuntimeException {

@@ -51,15 +50,13 @@ public class UnsupportedAlgorithmException extends RuntimeException {
    }

    /**
-     * <p>
     * Constructs a new runtime exception with the specified detail message and
     * cause.
-     * 
-     * <p>Note that the detail message associated with
+     * <p>
+     * Note that the detail message associated with
     * {@code cause} is <i>not</i> automatically incorporated in
     * this runtime exception's detail message.
     *
-     *
     * @param message the detail message (which is saved for later retrieval
     *                by the {@link #getMessage()} method).
     * @param cause   the cause (which is saved for later retrieval by the
@@ -95,13 +92,12 @@ public class UnsupportedAlgorithmException extends RuntimeException {
     * stack trace enabled or disabled.
     *
     * @param message            the detail message.
-     * @param cause              the cause.  (A {@code null} value is permitted,
-     *                           and indicates that the cause is nonexistent or unknown.)
-     * @param enableSuppression  whether or not suppression is enabled
-     *                           or disabled
-     * @param writableStackTrace whether or not the stack trace should
-     *                           be writable
-     * @since 1.7
+     * @param cause              the cause (A {@code null} value is permitted,
+     *                           and indicates that the cause is nonexistent or
+     *                           unknown.)
+     * @param enableSuppression  whether suppression is enabled or disabled
+     * @param writableStackTrace whether the stack trace should be writable
+     * @since 1.0.0
     */
    public UnsupportedAlgorithmException(String message, Throwable cause, boolean enableSuppression, boolean writableStackTrace) {
        super(message, cause, enableSuppression, writableStackTrace);
@@ -18,9 +18,12 @@
 package cn.org.codecrafters.simplejwt.exceptions;

 /**
- * WeakSecretException
+ * This Exception indicates that your secret is too weak to be used in signing
+ * JWTs.
 *
 * @author Zihlu Wang
+ * @version 1.1.0
+ * @since 1.0.0
 */
 public class WeakSecretException extends RuntimeException {

@@ -16,13 +16,10 @@
 */

 /**
- * <p>
 * The {@code cn.org.codecrafters.simplejwt.exceptions} package contains
 * custom exception classes related to the Simple JWT library. These
 * exceptions are thrown when there are issues or errors during the generation
 * , validation, or processing of JSON Web Tokens (JWTs) in Java applications.
- *
- *
 * <p>
 * Custom exception classes in this package are designed to enhance the
 * robustness and reliability of the JWT handling process by providing clear
@@ -30,8 +27,6 @@
 * identify and troubleshoot issues related to JWT generation, validation, or
 * extraction and ensure smooth operation and error handling in their
 * applications.
- *
- *
 * <p>
 * Developers using the Simple JWT library should be aware of the possible
 * exceptions that can be thrown and handle them appropriately to ensure secure
@@ -16,7 +16,6 @@
 */

 /**
- * <p>
 * The {@code cn.org.codecrafters.simplejwt} package is the core package of the
 * Simple JWT project, which provides a lightweight and easy-to-use library for
 * working with JSON Web Tokens (JWTs) in Java applications. JWT is a
@@ -24,16 +23,12 @@
 * used to secure web and mobile applications. This library aims to simplify
 * the JWT handling process and provide convenient abstractions for JWT
 * generation, validation, and extraction.
- * 
- *
 * <p>
 * The Simple JWT library is designed to be flexible and customizable, allowing
 * developers to use different algorithms, token resolvers, and token payload
 * classes based on their specific application requirements. It aims to
 * simplify the JWT handling process while maintaining security and best
 * practices for working with JWTs.
- * 
- *
 * <p>
 * Developers should refer to the official documentation and examples for the
 * Simple JWT project to understand how to use the library effectively and
@@ -43,9 +43,61 @@ import java.util.Map;
 import java.util.UUID;

 /**
- * JjwtTokenResolver
+ * The {@link JjwtTokenResolver} class is an implementation of the {@link
+ * cn.org.codecrafters.simplejwt.TokenResolver} interface. It uses the {@code
+ * io.jsonwebtoken:jjwt} library to handle JSON Web Token (JWT) resolution.
+ * This resolver provides functionality to create, extract, verify, and renew
+ * JWT tokens using various algorithms and custom payload data.
+ * <p>
+ * <b>Dependencies:</b>
+ * This implementation relies on the {@code io.jsonwebtoken:jjwt} library. Please
+ * ensure you have added this library as a dependency to your project before
+ * using this resolver.
+ * <p>
+ * <b>Usage:</b>
+ * To use the {@code JjwtTokenResolver}, first, create an instance of this
+ * class:
+ * <pre>{@code
+ *   TokenResolver<DecodedJWT> tokenResolver =
+ *       new JjwtTokenResolver(TokenAlgorithm.HS256,
+ *                                 "Token Subject",
+ *                                 "Token Issuer",
+ *                                 "Token Secret");
+ *   }</pre>
+ * <p>
+ * Then, you can utilize the various methods provided by this resolver to
+ * handle JWT tokens:
+ * <pre>{@code
+ *   // Creating a new JWT token
+ *   String token =
+ *       tokenResolver.createToken(Duration.ofHours(1),
+ *                                 "your_subject",
+ *                                 "your_audience",
+ *                                 customPayloads);
+ *
+ *   // Extracting payload data from a JWT token
+ *   DecodedJWT decodedJWT = tokenResolver.resolve(token);
+ *   T payloadData = decodedJWT.extract(token, T.class);
+ *
+ *   // Renewing an existing JWT token
+ *   String renewedToken =
+ *       tokenResolver.renew(token, Duration.ofMinutes(30), customPayloads);
+ *   }</pre>
+ * <p>
+ * <b>Note:</b>
+ * It is essential to configure the appropriate algorithms, secret, and issuer
+ * according to your specific use case when using this resolver.
+ * Additionally, ensure that the {@code io.jsonwebtoken:jjwt} library is
+ * correctly configured in your project's dependencies.
 *
 * @author Zihlu Wang
+ * @version 1.1.0
+ * @see Claims
+ * @see Jws
+ * @see Jwts
+ * @see SignatureAlgorithm
+ * @see Keys
+ * @since 1.0.0
 */
@Slf4j
 public class JjwtTokenResolver implements TokenResolver<Jws<Claims>> {
@@ -67,11 +119,11 @@ public class JjwtTokenResolver implements TokenResolver<Jws<Claims>> {

        if (secret.length() <= 32) {
            log.error("""
-                    The provided secret which owns {} characters is too weak. Please replace it with a stronger one.
-                    """, secret.length());
+                            The provided secret which owns {} characters is too weak. Please replace it with a stronger one.""",
+                    secret.length());
            throw new WeakSecretException("""
-                    The provided secret which owns %s characters is too weak. Please replace it with a stronger one.
-                    """.formatted(secret.length()));
+                    The provided secret which owns %s characters is too weak. Please replace it with a stronger one."""
+                    .formatted(secret.length()));
        }

        this.jtiCreator = jtiCreator;
@@ -86,12 +138,12 @@ public class JjwtTokenResolver implements TokenResolver<Jws<Claims>> {
        }

        if (secret.length() <= 32) {
-            log.error("""
-                    The provided secret which owns {} characters is too weak. Please replace it with a stronger one.
-                    """, secret.length());
-            throw new WeakSecretException("""
-                    The provided secret which owns %s characters is too weak. Please replace it with a stronger one.
-                    """.formatted(secret.length()));
+            log.error(
+                    "The provided secret which owns {} characters is too weak. Please replace it with a stronger one.",
+                    secret.length());
+            throw new WeakSecretException(
+                    "The provided secret which owns %s characters is too weak. Please replace it with a stronger one."
+                            .formatted(secret.length()));
        }

        this.jtiCreator = UUID::randomUUID;
@@ -106,12 +158,12 @@ public class JjwtTokenResolver implements TokenResolver<Jws<Claims>> {
        }

        if (secret.length() <= 32) {
-            log.error("""
-                    The provided secret which owns {} characters is too weak. Please replace it with a stronger one.
-                    """, secret.length());
-            throw new WeakSecretException("""
-                    The provided secret which owns %s characters is too weak. Please replace it with a stronger one.
-                    """.formatted(secret.length()));
+            log.error(
+                    "The provided secret which owns {} characters is too weak. Please replace it with a stronger one.",
+                    secret.length());
+            throw new WeakSecretException(
+                    "The provided secret which owns %s characters is too weak. Please replace it with a stronger one."
+                            .formatted(secret.length()));
        }

        this.jtiCreator = UUID::randomUUID;
@@ -20,19 +20,45 @@ package cn.org.codecrafters.simplejwt.jjwt.config;
 import cn.org.codecrafters.simplejwt.config.TokenResolverConfig;
 import cn.org.codecrafters.simplejwt.constants.TokenAlgorithm;
 import cn.org.codecrafters.simplejwt.exceptions.UnsupportedAlgorithmException;
+import cn.org.codecrafters.simplejwt.jjwt.JjwtTokenResolver;
 import io.jsonwebtoken.SignatureAlgorithm;

 import java.util.HashMap;
 import java.util.Map;

 /**
- * JjwtTokenResolverConfig
+ * The JjwtTokenResolverConfig class provides the configuration for the
+ * JjwtTokenResolverConfig.
+ * <p>
+ * This configuration class is used to establish the mapping between the
+ * standard TokenAlgorithm defined within the JjwtTokenResolverConfig and
+ * the specific algorithms used by the {@code io.jsonwebtoken:jjwt} library,
+ * which is the underlying library used by JjwtTokenResolverConfig to handle
+ * JSON Web Tokens (JWTs).
+ * <p>
+ * <b>Algorithm Mapping:</b>
+ * The JjwtTokenResolverConfig class allows specifying the relationship
+ * between the standard TokenAlgorithm instances supported by
+ * JjwtTokenResolverConfig and the corresponding algorithms used by the
+ * {@code io.jsonwebtoken:jjwt} library. The mapping is achieved using a Map,
+ * where the keys are the standard TokenAlgorithm instances, and the values
+ * represent the algorithm functions used by {@code io.jsonwebtoken:jjwt}
+ * library for each corresponding key.
+ * <p>
+ * <b>Note:</b>
+ * The provided algorithm mapping should be consistent with the actual
+ * algorithms supported and used by the {@code io.jsonwebtoken:jjwt} library.
+ * It is crucial to ensure that the mapping is accurate to enable proper token
+ * validation and processing within the {@link JjwtTokenResolver}.
 *
 * @author Zihlu Wang
+ * @version 1.1.0
+ * @since 1.0.0
 */
 public final class JjwtTokenResolverConfig implements TokenResolverConfig<SignatureAlgorithm> {

-    private JjwtTokenResolverConfig() {}
+    private JjwtTokenResolverConfig() {
+    }

    private static final Map<TokenAlgorithm, SignatureAlgorithm> SUPPORTED_ALGORITHMS = new HashMap<>() {{
        put(TokenAlgorithm.HS256, SignatureAlgorithm.HS256);
@@ -16,17 +16,14 @@
 */

 /**
- * <p>
 * The package {@code cn.org.codecrafters.simplejwt.jjwt.config} contains
 * configuration classes related to the {@link
 * cn.org.codecrafters.simplejwt.jjwt.JjwtTokenResolver}
 * implementation.
- *
 * <p>
 * The classes in this package provide configuration options and settings for
 * the {@link cn.org.codecrafters.simplejwt.jjwt.JjwtTokenResolver},
 * which is used for resolving JSON Web Tokens (JWT) using the Auth0 library.
- *
 * <p>
 * The {@link
 * cn.org.codecrafters.simplejwt.jjwt.config.JjwtTokenResolverConfig}
@@ -37,7 +34,6 @@
 * JWT algorithms. It enables developers to specify and customize the
 * algorithm functions according to the chosen JWT algorithm and the library
 * being used.
- *
 * <p>
 * The configuration options in this package help developers integrate and
 * configure the {@link
@@ -45,7 +41,6 @@
 * into their Spring Boot applications. Developers can fine-tune the token
 * resolution process and customize algorithm handling to align with their
 * specific requirements and desired level of security.
- *
 * <p>
 * It is recommended to explore the classes in this package to understand how
 * to configure and use the {@link
@@ -23,7 +23,6 @@
 * solutions for web and mobile applications. The classes in this package
 * provide the necessary functionality to handle JSON Web Tokens (JWTs) using
 * the {@code io.jsonwebtoken:jjwt-api} library.
- *
 * <p>
 * The main class in this package is the {@link
 * cn.org.codecrafters.simplejwt.jjwt.JjwtTokenResolver}, which
@@ -33,14 +32,12 @@
 * JWTs using the {@code io.jsonwebtoken:jjwt-api} library. Developers can use
 * this class as the main token resolver in the Simple JWT project when
 * integrating {@code io.jsonwebtoken:jjwt-api} as the JWT management library.
- *
 * <p>
 * The {@code JjwtTokenResolver} relies on the {@code io.jsonwebtoken:jjwt-api}
 * library to handle the underlying JWT operations, including token creation,
 * validation, and extraction. It utilizes the {@code io.jsonwebtoken:jjwt-api}
 * {@code Algorithm} class to define and use different algorithms for JWT
 * signing and verification.
- *
 * <p>
 * To use the {@code JjwtTokenResolver}, developers must provide the necessary
 * configurations and dependencies, such as the {@code GuidCreator} for
@@ -48,7 +45,6 @@
 * issuer name, and the secret key used for token signing and validation. The
 * {@code JjwtTokenResolverConfig} class provides a convenient way to configure
 * these dependencies.
- *
 * <p>
 * Developers using the {@code io.jsonwebtoken:jjwt-api} integration should be
 * familiar with the concepts and usage of the {@code io.jsonwebtoken:jjwt-api}
@@ -34,26 +34,22 @@ import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.DependsOn;

 /**
- * <p>
 * SimpleJwtAutoConfiguration is responsible for automatically configuring the
 * Simple JWT library with {@code com.auth0:java-jwt} when used in a Spring
 * Boot application. It provides default settings and configurations to ensure
 * that the library works smoothly without requiring manual configuration.
- *
 * <p>
- * This auto-configuration class sets up the necessary beans and components
+ * This autoconfiguration class sets up the necessary beans and components
 * required for JWT generation and validation. It automatically creates and
 * configures the {@link TokenResolver} bean based on the available options and
 * properties.
- *
 * <p>
 * Developers using the Simple JWT library with Spring Boot do not need to
- * explicitly configure the library, as the auto-configuration takes care of
+ * explicitly configure the library, as the autoconfiguration takes care of
 * setting up the necessary components and configurations automatically.
 * However, developers still have the flexibility to customize the behavior of
 * the library by providing their own configurations and properties.
 *
- *
 * @author Zihlu Wang
 * @version 1.0.0
 * @since 1.0.0
@@ -29,9 +29,11 @@ import org.springframework.context.annotation.Conditional;
 import java.util.UUID;

 /**
- * GuidAutoConfiguration
+ * Autoconfiguration for injecting a {@code GuidCreator} for generating jwt id.
 *
 * @author Zihlu Wang
+ * @version 1.1.0
+ * @since 1.0.0
 */
@Slf4j
@AutoConfiguration
@@ -34,28 +34,25 @@ import org.springframework.boot.context.properties.EnableConfigurationProperties
 import org.springframework.context.annotation.Bean;

 /**
- * <p>
 * JjwtTokenResolverAutoConfiguration is responsible for automatically
 * configuring the Simple JWT library with {@code io.jsonwebtoken:jjwt-api}
 * when used in a Spring Boot application. It provides default settings and
 * configurations to ensure that the library works smoothly without requiring
 * manual configuration.
- *
 * <p>
- * This auto-configuration class sets up the necessary beans and components
+ * This autoconfiguration class sets up the necessary beans and components
 * required for JWT generation and validation. It automatically creates and
 * configures the {@link TokenResolver} bean based on the available options and
 * properties.
- *
 * <p>
 * Developers using the Simple JWT library with Spring Boot do not need to
- * explicitly configure the library, as the auto-configuration takes care of
+ * explicitly configure the library, as the autoconfiguration takes care of
 * setting up the necessary components and configurations automatically.
 * However, developers still have the flexibility to customize the behavior of
 * the library by providing their own configurations and properties.
 *
 * @author Zihlu Wang
- * @version 1.0.0
+ * @version 1.1.0
 * @since 1.0.0
 */
@Slf4j
@@ -9,11 +9,11 @@ import org.springframework.core.type.AnnotatedTypeMetadata;
 import java.util.Objects;

 /**
- * GuidCreatorCondition
- * <p>
- * Created on 28 Aug 2023
+ * The condition to create bean {@code jtiCreator}.
 *
 * @author Zihlu Wang
+ * @version 1.1.0
+ * @since 1.0.0
 */
@Slf4j
 public class GuidCreatorCondition implements Condition {
@@ -24,28 +24,24 @@ import lombok.Data;
 import org.springframework.boot.context.properties.ConfigurationProperties;

 /**
- * <p>
 * {@code SimpleJwtProperties} is a configuration properties class used to
 * store the properties related to Simple JWT library configuration. These
 * properties can be configured in the application's properties file (e.g.,
 * application.properties) with the prefix "code-crafters.simple-jwt".
- * 
- *
 * <p>
 * SimpleJwtProperties provides configuration options for the JWT algorithm,
 * issuer, and secret. The properties are used by the {@link
- * AuthzeroTokenResolverAutoConfiguration}
- * class to set up the necessary configurations for JWT generation and
- * validation.
- * 
- *
+ * AuthzeroTokenResolverAutoConfiguration} and {@link
+ * cn.org.codecrafters.simplejwt.jjwt.JjwtTokenResolver} to set up the
+ * necessary configurations for JWT generation and validation.
 * <p>
 * Developers can customize the JWT algorithm, issuer, and secret by setting
 * the corresponding properties in the application's properties file. The
 * SimpleJwtAutoConfiguration class reads these properties and uses them to
 * create the TokenResolver bean with the desired configuration.
 *
- *
+ * @author Zihlu Wang
+ * @version 1.1.0
 * @since 1.0.0
 */
@Data
@@ -16,15 +16,12 @@
 */

 /**
- * <p>
 * The "cn.org.codecrafters.simplejwt.autoconfiguration.properties" package
 * contains configuration properties classes used for Simple JWT library
- * auto-configuration. These classes define the properties that can be
+ * autoconfiguration. These classes define the properties that can be
 * configured in the application's properties file (e.g.,
 * application.properties) to customize the behavior and settings of the Simple
 * JWT library.
- *
- *
 * <p>
 * Developers can customize the JWT algorithm, issuer, and secret by setting
 * the corresponding properties in the application's properties file with the
@@ -22,11 +22,9 @@ import java.util.List;

 /**
 * The WebCalendar class represents a web calendar in iCalendar format.
- *
 * <p>
 * It allows users to create and customize calendar components and events and
 * generate an iCalendar string containing all the calendar information.
- *
 * <p>Usage Example:
 * <pre>
 * WebCalendar calendar = new WebCalendar()
@@ -39,14 +37,13 @@ import java.util.List;
 *         .addEvent(event2);
 * String iCalendarString = calendar.resolve();
 * </pre>
- *
 * <p>
 * The WebCalendar class is designed to generate an iCalendar string conforming
 * to the iCalendar specification, which can be used to share calendar data
 * with other calendar applications or services.
 *
 * @author Zihlu Wang
- * @version 1.0.0
+ * @version 1.1.0
 * @since 1.0.0
 */
 public final class WebCalendar {
@@ -41,7 +41,7 @@ import java.util.UUID;
 * iCalendar content for the event.
 *
 * @author Zihlu Wang
- * @version 1.0.0
+ * @version 1.1.0
 * @since 1.0.0
 */
 public final class WebCalendarEvent extends WebCalendarNode {
@@ -35,7 +35,7 @@ import java.util.List;
 * component or event.
 *
 * @author Zihlu Wang
- * @version 1.0.0
+ * @version 1.1.0
 * @since 1.0.0
 */
 public abstract sealed class WebCalendarNode
@@ -22,7 +22,6 @@ import lombok.Getter;
 /**
 * The Classification enum represents the classification levels of calendar
 * content based on RFC 5545.
- *
 * <p>
 * Calendar events or components can be classified as one of the following
 * levels:
@@ -42,7 +41,7 @@ import lombok.Getter;
 * </ul>
 *
 * @author Zihlu Wang
- * @version 1.0.0
+ * @version 1.1.0
 * @since 1.0.0
 */
@Getter
@@ -50,7 +49,6 @@ public enum Classification {

    /**
     * Public classification level.
-     *
     * <p>
     * Indicates that the calendar content is public and can be freely
     * distributed.
@@ -59,7 +57,6 @@ public enum Classification {

    /**
     * Private classification level.
-     *
     * <p>
     * Indicates that the calendar content is private and should not be shared
     * with others.
@@ -68,7 +65,6 @@ public enum Classification {

    /**
     * Confidential classification level.
-     *
     * <p>
     * Indicates that the calendar content is confidential and should be kept
     * strictly private.
@@ -79,8 +75,6 @@ public enum Classification {
    /**
     * -- GETTER --
     * Get the string representation of the classification level.
-     *
-     * @return the string representation of the classification level
     */
    private final String classification;

@@ -20,7 +20,6 @@
 * the configuration and settings of the web calendar module. It provides
 * various configurations and constants used in the generation and resolution
 * of iCalendar content.
- *
 * <p>The classes in this package include:</p>
 * <ul>
 *     <li>
@@ -19,7 +19,6 @@
 * The package {@code cn.org.codecrafters.webcal} contains classes and modules
 * related to web calendar generation and resolution. It provides functionality
 * to create and manage iCalendar content for web-based calendar applications.
- *
 * <p>
 * The main classes and modules in this package include:
 * <ul>