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
@@ -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}