* The {@code NotImplementedException} class is a custom runtime exception * that represents a situation where a particular method or functionality is - * not implemented or is currently unavailable in the codebase. It extends the - * standard {@code RuntimeException} class, making it an unchecked exception. - * + * not implemented or is currently unavailable in the codebase. *
* This exception is typically thrown when developers need to indicate that a * specific part of the code is incomplete or requires further implementation. * It serves as a placeholder to highlight unfinished sections of the * application during development and testing phases. - * *
* Usage Example: - * *
* public void someMethod() {
* // Some code...
* throw new NotImplementedException("""
- * This feature will be implemented in a future release.
- * """);
+ * This feature will be implemented in a future release.""");
* }
*
- *
* Contact
* * JDevKit is designed to be modular, and other specific feature modules within * the library may rely on these exceptions from the core package. - * *
* For more information and the latest version of JDevKit, please visit our * website codecrafters.org.cn. - * *
* Contact *
* For more information and the latest version of JDevKit, please visit our
* website codecrafters.org.cn.
diff --git a/devkit-utils/pom.xml b/devkit-utils/pom.xml
index 348d4c8..f99e4f7 100644
--- a/devkit-utils/pom.xml
+++ b/devkit-utils/pom.xml
@@ -6,7 +6,7 @@
- * The {@code Base64Util} class provides static methods to encode and decode - * strings using Base64 encoding. It utilizes the {@link Base64} class from the + * The {@link Base64Util} class provides static methods to encode and decode + * strings with 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. - * *
* 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. - * *
* Example usage: *
@@ -47,19 +45,45 @@ import java.util.Base64;
* String decoded = Base64Util.decode(encoded);
* System.out.println("Decoded string: " + decoded);
*
- *
* * Note: 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 { + private static Base64.Encoder encoder; + + private static Base64.Decoder decoder; + + /** + * Ensure that there is only one Base64 Encoder. + * + * @return the {@link Base64.Encoder} instance + */ + private static Base64.Encoder getEncoder() { + if (Objects.isNull(encoder)) { + encoder = Base64.getEncoder(); + } + return encoder; + } + + /** + * Ensure that there is only one Base64 Encoder. + * + * @return the {@link Base64.Encoder} instance + */ + private static Base64.Decoder getDecoder() { + if (Objects.isNull(decoder)) { + decoder = Base64.getDecoder(); + } + return decoder; + } + /** * Private constructor to prevent instantiation of the class. */ @@ -74,8 +98,7 @@ public final class Base64Util { * @return the Base64 encoded string */ public static String encode(String value, Charset charset) { - var encoder = Base64.getEncoder(); - var encoded = encoder.encode(value.getBytes(charset)); + var encoded = getEncoder().encode(value.getBytes(charset)); return new String(encoded); } @@ -98,8 +121,7 @@ public final class Base64Util { * @return the decoded string */ public static String decode(String value, Charset charset) { - var decoder = Base64.getDecoder(); - var decoded = decoder.decode(value.getBytes(charset)); + var decoded = getDecoder().decode(value.getBytes(charset)); return new String(decoded); } diff --git a/devkit-utils/src/main/java/cn/org/codecrafters/devkit/utils/BranchUtil.java b/devkit-utils/src/main/java/cn/org/codecrafters/devkit/utils/BranchUtil.java index 6e242b1..6b9b760 100644 --- a/devkit-utils/src/main/java/cn/org/codecrafters/devkit/utils/BranchUtil.java +++ b/devkit-utils/src/main/java/cn/org/codecrafters/devkit/utils/BranchUtil.java @@ -23,29 +23,24 @@ import java.util.function.BooleanSupplier; import java.util.function.Supplier; /** + * The {@link BranchUtil} class provides static methods to simplify conditional + * logic in Java development by leveraging lambda expressions. It offers + * convenient methods to replace verbose {@code if...else} statements with more + * concise and expressive functional constructs. *
- * 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. - * - * - *
- * 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. - * - * + * Developers can use 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. *
* Example: *
* // If you want to simplify an if (exp1 || exp2), you can use the * // following code: - * var r1 = BranchUtil.or(1 == 1, 2 == 1) + * String r1 = BranchUtil.or(1 == 1, 2 == 1) * .handle(() -> "1 is equal to 1 or 2 is equal to 1."); * * // If you have an else branch, you can use the following code: - * var r2 = BranchUtil.or(1 == 1, 2 == 1) + * String r2 = BranchUtil.or(1 == 1, 2 == 1) * .handle(() -> "1 is equal to 1 or 2 is equal to 1.", * () -> "1 is not equal to 1 and 2 is not equal to 1."); * @@ -67,7 +62,6 @@ import java.util.function.Supplier; * // do something * }); *- * *
* Note:
* The {@link #and(Boolean...)} and {@link #or(Boolean...)} methods accept any
@@ -75,7 +69,7 @@ import java.util.function.Supplier;
*
* @param
* Handles the result of the boolean expressions by executing the
* appropriate handler based on the result.
- *
*
* 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.
- *
*
* Returns the result of the executed handler.
*
@@ -181,7 +172,8 @@ public final class BranchUtil
* Handles the result of the boolean expressions by executing the provided
* handler if the result is {@code true}.
- *
*
* 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
* Handles the result of the boolean expressions by executing the
* appropriate handler based on the result.
- *
*
* 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
diff --git a/devkit-utils/src/main/java/cn/org/codecrafters/devkit/utils/ChainedCalcUtil.java b/devkit-utils/src/main/java/cn/org/codecrafters/devkit/utils/ChainedCalcUtil.java
index 5817d88..fc2358c 100644
--- a/devkit-utils/src/main/java/cn/org/codecrafters/devkit/utils/ChainedCalcUtil.java
+++ b/devkit-utils/src/main/java/cn/org/codecrafters/devkit/utils/ChainedCalcUtil.java
@@ -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,19 +26,12 @@ import java.util.function.BiFunction;
import java.util.function.Function;
/**
- *
- * Utility class for chained high-precision calculations using BigDecimal.
- *
- *
- *
- * The ChainedCalcUtil class provides a convenient way to perform chained
- * high-precision calculations using BigDecimal. It allows users to perform
- * mathematical operations such as addition, subtraction, multiplication,
- * and division with customizable precision and scale. By using this utility
- * class, developers can achieve accurate results and avoid precision loss
- * in their calculations.
- *
- *
+ * The {@code ChainedCalcUtil} class provides a convenient way to perform
+ * chained high-precision calculations using {@link BigDecimal}. It allows
+ * users to perform mathematical operations such as addition, subtraction,
+ * multiplication, and division with customisable precision and scale. By using
+ * this utility class, developers can achieve accurate results and avoid
+ * precision loss in their calculations.
*
* Usage:
*
* Note:
- * The ChainedCalcUtil class internally uses BigDecimal to handle
- * high-precision calculations. It is important to note that BigDecimal
- * operations can be memory-intensive and may have performance implications
- * for extremely large numbers or complex calculations.
+ * The {@code ChainedCalcUtil} class internally uses {@link BigDecimal} to
+ * handle high-precision calculations. It is important to note that {@link
+ * BigDecimal} operations can be memory-intensive and may have performance
+ * implications 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;
/**
- * Creates a ChainedCalcUtil instance with the specified initial value.
+ * Creates a {@code ChainedCalcUtil} instance with the specified initial
+ * value.
*
* @param value the initial value for the calculation
*/
@@ -115,7 +115,7 @@ public final class ChainedCalcUtil {
* Starts a chained calculation with the specified initial value.
*
* @param value the initial value for the calculation
- * @return a ChainedCalcUtil instance for performing chained calculations
+ * @return a {@code ChainedCalcUtil} instance for performing chained calculations
*/
public static ChainedCalcUtil startWith(Number value) {
return new ChainedCalcUtil(value);
@@ -125,7 +125,7 @@ public final class ChainedCalcUtil {
* Adds the specified value to the current value.
*
* @param other the value to be added
- * @return a ChainedCalcUtil instance with the updated value
+ * @return a {@code ChainedCalcUtil} instance with the updated value
*/
public ChainedCalcUtil add(Number other) {
return operator(BigDecimal::add, other);
@@ -137,7 +137,7 @@ public final class ChainedCalcUtil {
*
* @param other the value to be added
* @param beforeOperateScale the scale to be applied before the operation
- * @return a ChainedCalcUtil instance with the updated value
+ * @return a {@code ChainedCalcUtil} instance with the updated value
*/
public ChainedCalcUtil add(Number other, Integer beforeOperateScale) {
return operator(BigDecimal::add, other, beforeOperateScale);
@@ -147,7 +147,7 @@ public final class ChainedCalcUtil {
* Subtracts the specified value from the current value.
*
* @param other the value to be subtracted
- * @return a ChainedCalcUtil instance with the updated value
+ * @return a {@code ChainedCalcUtil} instance with the updated value
*/
public ChainedCalcUtil subtract(Number other) {
return operator(BigDecimal::subtract, other);
@@ -159,7 +159,7 @@ public final class ChainedCalcUtil {
*
* @param other the value to be subtracted
* @param beforeOperateScale the scale to be applied before the operation
- * @return a ChainedCalcUtil instance with the updated value
+ * @return a {@code ChainedCalcUtil} instance with the updated value
*/
public ChainedCalcUtil subtract(Number other, Integer beforeOperateScale) {
return operator(BigDecimal::subtract, other, beforeOperateScale);
@@ -169,7 +169,7 @@ public final class ChainedCalcUtil {
* Multiplies the current value by the specified value.
*
* @param other the value to be multiplied by
- * @return a ChainedCalcUtil instance with the updated value
+ * @return a {@code ChainedCalcUtil} instance with the updated value
*/
public ChainedCalcUtil multiply(Number other) {
return operator(BigDecimal::multiply, other);
@@ -181,7 +181,7 @@ public final class ChainedCalcUtil {
*
* @param other the value to be multiplied by
* @param beforeOperateScale the scale to be applied before the operation
- * @return a ChainedCalcUtil instance with the updated value
+ * @return a {@code ChainedCalcUtil} instance with the updated value
*/
public ChainedCalcUtil multiply(Number other, Integer beforeOperateScale) {
return operator(BigDecimal::multiply, other, beforeOperateScale);
@@ -191,7 +191,7 @@ public final class ChainedCalcUtil {
* Divides the current value by the specified value.
*
* @param other the value to divide by
- * @return a ChainedCalcUtil instance with the updated value
+ * @return a {@code ChainedCalcUtil} instance with the updated value
*/
public ChainedCalcUtil divide(Number other) {
return operator(BigDecimal::divide, other);
@@ -203,7 +203,7 @@ public final class ChainedCalcUtil {
*
* @param other the value to divide by
* @param beforeOperateScale the scale to be applied before the operation
- * @return a ChainedCalcUtil instance with the updated value
+ * @return a {@code ChainedCalcUtil} instance with the updated value
*/
public ChainedCalcUtil divide(Number other, Integer beforeOperateScale) {
return operator(BigDecimal::divide, other, beforeOperateScale);
@@ -214,7 +214,7 @@ public final class ChainedCalcUtil {
*
* @param other the value to divide by
* @param scale the scale for the result
- * @return a ChainedCalcUtil instance with the updated value
+ * @return a {@code ChainedCalcUtil} instance with the updated value
*/
public ChainedCalcUtil divideWithScale(Number other, Integer scale) {
return baseOperator(otherValue ->
@@ -228,63 +228,54 @@ public final class ChainedCalcUtil {
* @param other the value to divide by
* @param scale the scale for the result
* @param beforeOperateScale the scale to be applied before the operation
- * @return a ChainedCalcUtil instance with the updated value
+ * @return a {@code ChainedCalcUtil} instance with the updated value
*/
public ChainedCalcUtil divideWithScale(Number other, Integer scale, Integer beforeOperateScale) {
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.
+ * Returns the current value as a {@link BigDecimal} with the specified scale.
*
* @param scale the scale for the result
- * @return the current value as a BigDecimal with the specified scale
+ * @return the current value as a {@link BigDecimal} with the specified scale
*/
public BigDecimal getValue(int scale) {
return value.setScale(scale, RoundingMode.HALF_UP);
}
/**
- * Returns the current value as a Double.
+ * Returns the current value as a {@link Double}.
*
- * @return the current value as a Double
+ * @return the current value as a {@link Double}
*/
public Double getDouble() {
return getValue().doubleValue();
}
/**
- * Returns the current value as a Double with the specified scale.
+ * Returns the current value as a {@link Double} with the specified scale.
*
* @param scale the scale for the result
- * @return the current value as a Double with the specified scale
+ * @return the current value as a {@link Double} with the specified scale
*/
public Double getDouble(int scale) {
return getValue(scale).doubleValue();
}
/**
- * Returns the current value as a Long.
+ * Returns the current value as a {@link Long}.
*
- * @return the current value as a Long
+ * @return the current value as a {@link Long}
*/
public Long getLong() {
return getValue().longValue();
}
/**
- * Returns the current value as an Integer.
+ * Returns the current value as an {@link Integer}.
*
- * @return the current value as an Integer
+ * @return the current value as an {@link Integer}
*/
public Integer getInteger() {
return getValue().intValue();
@@ -340,7 +331,7 @@ public final class ChainedCalcUtil {
}
/**
- * Converts the specified value to a BigDecimal.
+ * Converts the specified value to a {@link BigDecimal}.
*
* @param value the value to convert
* @param scale the scale to apply to the resulting BigDecimal, or null if
diff --git a/devkit-utils/src/main/java/cn/org/codecrafters/devkit/utils/HashUtil.java b/devkit-utils/src/main/java/cn/org/codecrafters/devkit/utils/HashUtil.java
index 37bb01b..c12c9b1 100644
--- a/devkit-utils/src/main/java/cn/org/codecrafters/devkit/utils/HashUtil.java
+++ b/devkit-utils/src/main/java/cn/org/codecrafters/devkit/utils/HashUtil.java
@@ -25,15 +25,10 @@ import java.util.Objects;
import java.util.Optional;
/**
- *
- * Utility class for performing hash operations on strings.
- *
- *
- * 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.
- *
+ * The {@code 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.
*
* Example usage:
*
* Note:
* The hash functions provided by the HashUtil class are one-way hash
@@ -69,7 +63,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
*/
@@ -121,7 +115,7 @@ public final class HashUtil {
* Calculates the MD2 hash value of the specified string using the given
* charset.
*
- * @param value the string to calculate the MD2 hash value for
+ * @param value the string to calculate with the MD2 algorithm
* @param charset the charset to use for encoding the string (default is
* UTF-8 if null)
* @return the MD2 hash value as a hexadecimal string
@@ -135,7 +129,7 @@ public final class HashUtil {
* Calculates the MD2 hash value of the specified string using the UTF-8
* charset.
*
- * @param value the string to calculate the MD2 hash value for
+ * @param value the string to calculate with the MD2 algorithm
* @return the MD2 hash value as a hexadecimal string
*/
public static String md2(String value) {
@@ -146,7 +140,7 @@ public final class HashUtil {
* Calculates the MD5 hash value of the specified string using the given
* charset.
*
- * @param value the string to calculate the MD5 hash value for
+ * @param value the string to calculate with the MD5 algorithm
* @param charset the charset to use for encoding the string (default is
* UTF-8 if null)
* @return the MD5 hash value as a hexadecimal string
@@ -160,7 +154,7 @@ public final class HashUtil {
* Calculates the MD5 hash value of the specified string using the UTF-8
* charset.
*
- * @param value the string to calculate the MD5 hash value for
+ * @param value the string to calculate with the MD5 algorithm
* @return the MD5 hash value as a hexadecimal string
*/
public static String md5(String value) {
@@ -171,7 +165,7 @@ public final class HashUtil {
* Calculates the SHA-1 hash value of the specified string using the given
* charset.
*
- * @param value the string to calculate the SHA-1 hash value for
+ * @param value the string to calculate with the SHA-1 algorithm
* @param charset the charset to use for encoding the string (default is
* UTF-8 if null)
* @return the SHA-1 hash value as a hexadecimal string
@@ -185,7 +179,7 @@ public final class HashUtil {
* Calculates the SHA-1 hash value of the specified string using the UTF-8
* charset.
*
- * @param value the string to calculate the SHA-1 hash value for
+ * @param value the string to calculate with the SHA-1 algorithm
* @return the SHA-1 hash value as a hexadecimal string
*/
public static String sha1(String value) {
@@ -196,7 +190,7 @@ public final class HashUtil {
* Calculates the SHA-224 hash value of the specified string using the
* given charset.
*
- * @param value the string to calculate the SHA-224 hash value for
+ * @param value the string to calculate with the SHA-225 algorithm
* @param charset the charset to use for encoding the string (default is
* UTF-8 if null)
* @return the SHA-224 hash value as a hexadecimal string
@@ -210,7 +204,7 @@ public final class HashUtil {
* Calculates the SHA-224 hash value of the specified string using the
* UTF-8 charset.
*
- * @param value the string to calculate the SHA-224 hash value for
+ * @param value the string to calculate with the SHA-224 algorithm
* @return the SHA-224 hash value as a hexadecimal string
*/
public static String sha224(String value) {
@@ -221,7 +215,7 @@ public final class HashUtil {
* Calculates the SHA-256 hash value of the specified string using the
* given charset.
*
- * @param value the string to calculate the SHA-256 hash value for
+ * @param value the string to calculate with the SHA-256 algorithm
* @param charset the charset to use for encoding the string (default is
* UTF-8 if null)
* @return the SHA-256 hash value as a hexadecimal string
@@ -235,7 +229,7 @@ public final class HashUtil {
* Calculates the SHA-256 hash value of the specified string using the
* UTF-8 charset.
*
- * @param value the string to calculate the SHA-256 hash value for
+ * @param value the string to calculate with the SHA-256 algorithm
* @return the SHA-256 hash value as a hexadecimal string
*/
public static String sha256(String value) {
@@ -246,7 +240,7 @@ public final class HashUtil {
* Calculates the SHA-384 hash value of the specified string using the
* given charset.
*
- * @param value the string to calculate the SHA-384 hash value for
+ * @param value the string to calculate with the SHA-384 algorithm
* @param charset the charset to use for encoding the string (default is
* UTF-8 if null)
* @return the SHA-384 hash value as a hexadecimal string
@@ -260,7 +254,7 @@ public final class HashUtil {
* Calculates the SHA-384 hash value of the specified string using the
* UTF-8 charset.
*
- * @param value the string to calculate the SHA-384 hash value for
+ * @param value the string to calculate with the SHA-384 algorithm
* @return the SHA-384 hash value as a hexadecimal string
*/
public static String sha384(String value) {
@@ -271,7 +265,7 @@ public final class HashUtil {
* Calculates the SHA-512 hash value of the specified string using the
* given charset.
*
- * @param value the string to calculate the SHA-384 hash value for
+ * @param value the string to calculate with the SHA-512 algorithm
* @param charset the charset to use for encoding the string (default is
* UTF-8 if null)
* @return the SHA-512 hash value as a hexadecimal string
@@ -285,7 +279,7 @@ public final class HashUtil {
* Calculates the SHA-512 hash value of the specified string using the
* UTF-8 charset.
*
- * @param value the string to calculate the SHA-384 hash value for
+ * @param value the string to calculate with the SHA-512 algorithm
* @return the SHA-512 hash value as a hexadecimal string
*/
public static String sha512(String value) {
diff --git a/devkit-utils/src/main/java/cn/org/codecrafters/devkit/utils/MapUtil.java b/devkit-utils/src/main/java/cn/org/codecrafters/devkit/utils/MapUtil.java
index 3d2cf36..68ab6d4 100644
--- a/devkit-utils/src/main/java/cn/org/codecrafters/devkit/utils/MapUtil.java
+++ b/devkit-utils/src/main/java/cn/org/codecrafters/devkit/utils/MapUtil.java
@@ -24,17 +24,15 @@ import java.util.HashMap;
import java.util.Map;
/**
- *
- * MapUtil is a utility class that provides methods for converting objects to
- * maps and maps to objects.
- *
+ * {@code MapUtil} is a utility class that provides methods for converting
+ * objects to maps and maps to objects.
*
* 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 {
@@ -180,6 +178,22 @@ public final class MapUtil {
method.invoke(obj, fieldValue);
}
+ /**
+ * Casts the specified value to the required type.
+ *
+ * @param value the value to be cast
+ * @param requiredType the type to which the value should be cast
+ * @param
* The {@code GuidCreator} is a generic interface for generating globally unique
* identifiers (GUIDs) of a specific type.
- *
*
* The type of ID is determined by the class implementing this interface.
- *
*
* @param
- * SnowflakeGuidCreator - GUID generator based on the Snowflake algorithm.
- *
- *
- * The SnowflakeGuidCreator generates unique identifiers using the Snowflake
- * algorithm, which combines a timestamp, worker ID, and data center ID to
- * create 64-bit long integers. The bit distribution for the generated IDs is
- * as follows:
+ * The {@code SnowflakeGuidCreator} generates unique identifiers using the
+ * Snowflake algorithm, which combines a timestamp, worker ID, and data centre
+ * ID to create 64-bit long integers. The bit distribution for the generated
+ * IDs is as follows:
*
- * When initializing the SnowflakeGuidCreator, you must provide the worker ID
- * and data center ID, ensuring they are within the valid range defined by the
- * bit size. The generator maintains an internal sequence number that
- * increments for IDs generated within the same millisecond. If the system
+ * When initializing a {@link SnowflakeGuidCreator}, you must provide the
+ * worker ID and data centre ID, ensuring they are within the valid range
+ * defined by the bit size. The generator maintains an internal sequence number
+ * that increments for IDs generated within the same millisecond. If the system
* clock moves backward, an exception is thrown to prevent generating IDs with
* repeated timestamps.
*
* @author Zihlu Wang
- * @version 1.0.0
+ * @version 1.1.0
* @since 1.0.0
*/
public final class SnowflakeGuidCreator implements GuidCreator
- * The TimingException class represents an exception that is thrown when there
- * is an error related to time sequence.
- *
- *
- * 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.
- *
+ * The {@code TimingException} class represents an exception that is thrown
+ * when there is an error related to time sequence.
*
* 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.
- *
- *
- * 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
@@ -54,9 +40,9 @@ public class TimingException extends RuntimeException {
/**
* A custom exception that is thrown when there is an issue with timing or
- * scheduling with customized error message.
+ * scheduling with customised error message.
*
- * @param message customized message
+ * @param message customised message
*/
public TimingException(String message) {
super(message);
@@ -64,9 +50,9 @@ public class TimingException extends RuntimeException {
/**
* A custom exception that is thrown when there is an issue with timing or
- * scheduling with customized error message.
+ * scheduling with customised error message.
*
- * @param message customized message
+ * @param message customised message
* @param cause the cause of this exception
*/
public TimingException(String message, Throwable cause) {
@@ -75,7 +61,7 @@ public class TimingException extends RuntimeException {
/**
* A custom exception that is thrown when there is an issue with timing or
- * scheduling with customized error message.
+ * scheduling with customised error message.
*
* @param cause the cause of this exception
*/
diff --git a/guid/src/main/java/cn/org/codecrafters/guid/exceptions/package-info.java b/guid/src/main/java/cn/org/codecrafters/guid/exceptions/package-info.java
index 565cad2..e12ea58 100644
--- a/guid/src/main/java/cn/org/codecrafters/guid/exceptions/package-info.java
+++ b/guid/src/main/java/cn/org/codecrafters/guid/exceptions/package-info.java
@@ -16,17 +16,14 @@
*/
/**
- *
* 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).
- *
*
* 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.
- *
*
* 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.
- *
*
* Developers using the GUID generation module should be aware of the possible
* exceptions that can be thrown and handle them appropriately to ensure smooth
diff --git a/guid/src/main/java/cn/org/codecrafters/guid/package-info.java b/guid/src/main/java/cn/org/codecrafters/guid/package-info.java
index 8e7f31a..a9e9def 100644
--- a/guid/src/main/java/cn/org/codecrafters/guid/package-info.java
+++ b/guid/src/main/java/cn/org/codecrafters/guid/package-info.java
@@ -16,15 +16,12 @@
*/
/**
- *
* The package provides a set of tools for generating globally unique
* identifiers (GUIDs).
- *
*
* The goal of this library is to provide an efficient, reliable way to
* generate globally unique identifiers without requiring any specific
* environment or configuration.
- *
*
* Key features include:
*
+ * Spring Boot applications often need to store sensitive configuration details
+ * such as database passwords, API keys, etc. To ensure that these sensitive
+ * pieces of information are not exposed to the public, developers can utilize
+ * the {@code PropertyGuard} class to encrypt and store them within
+ * configuration files.
+ *
+ * Usage
+ * You need a 16-char long secret for encrypting a configuration property. You
+ * can get this secret on your own, or use the helper utility class by the
+ * following code:
+ *
+ * Then, in {@code application.yml} or {@code application.properties}, change
+ * the original value from plain text to encrypted value with the prefix
+ * "
+ * This class is extracted from MyBatis-Plus.
+ *
+ * @author hubin@baomidou
+ * @version 1.1.0
+ * @see EnvironmentPostProcessor
+ * @since 1.1.0 (3.3.2 of MyBatis-Plus)
+ */
+public class PropertyGuard implements EnvironmentPostProcessor {
+
+ private final String PREFIX = "pg";
+
+ /**
+ * Process the encryption environment variables.
+ *
+ * @param environment the environment to post-process
+ * @param application the application to which the environment belongs
+ */
+ @Override
+ public void postProcessEnvironment(ConfigurableEnvironment environment, SpringApplication application) {
+ // Get the key for encryption from command line.
+ var encryptionKey = "";
+ for (var ps : environment.getPropertySources()) {
+ if (ps instanceof SimpleCommandLinePropertySource source) {
+ encryptionKey = source.getProperty("%s.key".formatted(PREFIX));
+ break;
+ }
+ }
+
+ if (Optional.ofNullable(encryptionKey).map((key) -> !key.isEmpty()).orElse(false)) {
+ var map = new HashMap
* 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.
- *
*
* Dependencies:
* 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.
- *
*
* Usage:
* To use the {@code AuthzeroTokenResolver}, first, create an instance of this
@@ -63,11 +60,9 @@ import java.util.*;
* "Token Issuer",
* "Token Secret");
* }
- *
*
* Then, you can utilize the various methods provided by this resolver to
* handle JWT tokens:
- *
*
* Note:
* 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
@@ -128,11 +122,11 @@ public class AuthzeroTokenResolver implements TokenResolver
* Builds the custom claims of the JSON Web Token (JWT) using the provided
* Map of claims and adds them to the JWTCreator.Builder.
*
- *
* This method is used to add custom claims to the JWT. It takes a Map of
* claims, where each entry represents a custom claim name (key) and its
* corresponding value (value). The custom claims will be added to the JWT
* using the JWTCreator.Builder.
- *
*
* @param claims a Map containing the custom claims to be added to the JWT
* @param builder the JWTCreator.Builder instance to which the custom
@@ -317,9 +309,7 @@ public class AuthzeroTokenResolver implements TokenResolver
* Finish creating a token.
- *
*
* This is the final step of create a token, to sign this token.
*
@@ -331,7 +321,7 @@ public class AuthzeroTokenResolver implements TokenResolver
- * This configuration class is used to establish the mapping between the
- * standard TokenAlgorithm defined within the AuthzeroTokenResolver facade and
- * the specific algorithms used by the Auth0 Java JWT library, which is the
- * underlying library used by AuthzeroTokenResolver to handle JSON Web Tokens
- * (JWTs).
- *
+ * This configuration is used to establish the mapping between the standard
+ * {@link TokenAlgorithm} defined within the {@link AuthzeroTokenResolver}
+ * facade and the specific algorithms used by the {@code com.auth0:java-jwt}
+ * library, which is the underlying library used by {@link
+ * AuthzeroTokenResolver} to handle JSON Web Tokens (JWTs).
*
* Algorithm Mapping:
- * The AuthzeroTokenResolverConfig class allows specifying the relationship
- * between the standard TokenAlgorithm instances supported by
- * AuthzeroTokenResolver and the corresponding algorithms used by the
- * com.auth0:java-jwt 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 Auth0 Java JWT library for each corresponding
- * key.
- *
+ * The {@code AuthzeroTokenResolverConfig} allows specifying the relationship
+ * between the standard {@link TokenAlgorithm} instances supported by
+ * {@link AuthzeroTokenResolver} and the corresponding algorithms used by the
+ * {@code com.auth0:java-jwt} 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 Auth0 Java JWT library for each
+ * corresponding key.
*
* Note:
* The provided algorithm mapping should be consistent with the actual
- * algorithms supported and used by the Auth0 Java JWT library. It is crucial
- * to ensure that the mapping is accurate to enable proper token validation
- * and processing within the AuthzeroTokenResolver.
+ * algorithms supported and used by the {@code com.auth0:java-jwt} library. It
+ * is crucial to ensure that the mapping is accurate to enable proper token
+ * validation and processing within the {@link AuthzeroTokenResolver}.
*
* @author Zihlu Wang
- * @version 1.0.0
+ * @version 1.1.0
* @since 1.0.0
*/
public final class AuthzeroTokenResolverConfig implements TokenResolverConfig
- * Constructs a new instance of AuthzeroTokenResolverConfig.
- *
+ * Constructs a new instance of {@code AuthzeroTokenResolverConfig}.
*
* The constructor is set as private to enforce the singleton pattern for
- * this configuration class. Instances of AuthzeroTokenResolverConfig
- * should be obtained through the {@link #getInstance()} method.
+ * this configuration class. Instances of
+ * {@code AuthzeroTokenResolverConfig} should be obtained through the
+ * {@link #getInstance()} method.
*/
private AuthzeroTokenResolverConfig() {
}
/**
- *
- * The singleton instance of AuthzeroTokenResolverConfig.
- *
+ * The singleton instance of {@code AuthzeroTokenResolverConfig}.
*
* This instance is used to ensure that only one instance of
- * AuthzeroTokenResolverConfig is created and shared throughout the
- * application. The singleton pattern is implemented to provide centralized
+ * {@code AuthzeroTokenResolverConfig} is created and shared throughout the
+ * application. The singleton pattern is implemented to provide centralised
* configuration and avoid redundant object creation.
*/
private static AuthzeroTokenResolverConfig instance;
/**
- *
* The supported algorithms and their corresponding algorithm functions.
- *
*
* This map stores the supported algorithms as keys and their corresponding
* algorithm functions as values. The algorithm functions represent the
- * functions used by the Auth0 Java JWT library to handle the specific
- * algorithms. The mapping is used to provide proper algorithm resolution
- * and processing within the AuthzeroTokenResolver.
+ * functions used by the {@code com.auth0:java-jwt} library to handle the
+ * specific algorithms. The mapping is used to provide proper algorithm
+ * resolution and processing within the {@link AuthzeroTokenResolver}.
*/
private static final Map
* This method returns the algorithm function associated with the given
- * TokenAlgorithm. The provided TokenAlgorithm represents the specific
- * algorithm for which the corresponding algorithm function is required.
- * The returned AlgorithmFunction represents the function implementation
- * that can be used by the TokenResolver to handle the specific algorithm.
+ * {@link TokenAlgorithm}. The provided {@link TokenAlgorithm} represents
+ * the specific algorithm for which the corresponding algorithm function
+ * is required. The returned Algorithm Function represents the function
+ * implementation that can be used by the {@link TokenResolver} to handle
+ * the specific algorithm.
*
- * @param algorithm the TokenAlgorithm for which the algorithm function is
- * required
- * @return the algorithm function associated with the given TokenAlgorithm
+ * @param algorithm the {@link TokenAlgorithm} for which the algorithm
+ * function isrequired
+ * @return the algorithm function associated with the given {@link
+ * TokenAlgorithm}
* @throws UnsupportedAlgorithmException if the given {@code algorithm} is
* not supported by this
* implementation
diff --git a/simple-jwt-authzero/src/main/java/cn/org/codecrafters/simplejwt/authzero/config/package-info.java b/simple-jwt-authzero/src/main/java/cn/org/codecrafters/simplejwt/authzero/config/package-info.java
index 19f0774..5d6a0ae 100644
--- a/simple-jwt-authzero/src/main/java/cn/org/codecrafters/simplejwt/authzero/config/package-info.java
+++ b/simple-jwt-authzero/src/main/java/cn/org/codecrafters/simplejwt/authzero/config/package-info.java
@@ -16,17 +16,14 @@
*/
/**
- *
* The package {@code cn.org.codecrafters.simplejwt.authzero.config} contains
* configuration classes related to the {@link
* cn.org.codecrafters.simplejwt.authzero.AuthzeroTokenResolver}
* implementation.
- *
*
* 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.
- *
*
* 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.
- *
*
* The configuration options in this package help developers integrate and
* configure the {@link
@@ -45,13 +41,12 @@
* 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.
- *
*
* It is recommended to explore the classes in this package to understand how
* to configure and use the {@link
* cn.org.codecrafters.simplejwt.authzero.AuthzeroTokenResolver} effectively
* in the Spring Boot environment to handle JWT authentication and
- * authorization securely and efficiently.
+ * authorisation securely and efficiently.
*
* @since 1.0.0
*/
diff --git a/simple-jwt-authzero/src/main/java/cn/org/codecrafters/simplejwt/authzero/package-info.java b/simple-jwt-authzero/src/main/java/cn/org/codecrafters/simplejwt/authzero/package-info.java
index c8e75cb..11df0aa 100644
--- a/simple-jwt-authzero/src/main/java/cn/org/codecrafters/simplejwt/authzero/package-info.java
+++ b/simple-jwt-authzero/src/main/java/cn/org/codecrafters/simplejwt/authzero/package-info.java
@@ -19,11 +19,10 @@
* This package contains classes related to the integration of the {@code
* com.auth0:java-jwt} library in the Simple JWT project. {@code
* com.auth0:java-jwt} is a powerful and widely-used Identity as a Service
- * (IDaaS) platform that provides secure authentication and authorization
+ * (IDaaS) platform that provides secure authentication and authorisation
* 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.
- *
*
* The main class in this package is the {@link
* cn.org.codecrafters.simplejwt.authzero.AuthzeroTokenResolver}, which
@@ -33,22 +32,22 @@
* {@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.
- *
*
- * 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.
- *
+ * The {@link cn.org.codecrafters.simplejwt.authzero.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} {@link
+ * com.auth0.jwt.algorithms.Algorithm} class to define and use different
+ * algorithms for JWT signing and verification.
*
- * To use the {@code AuthzeroTokenResolver}, developers must provide the
- * necessary configurations and dependencies, such as the {@code GuidCreator}
- * for generating unique JWT IDs (JTI), the supported algorithm function, the
- * issuer name, and the secret key used for token signing and validation. The
- * {@code AuthzeroTokenResolverConfig} class provides a convenient way to
- * configure these dependencies.
- *
+ * To use the {@link
+ * cn.org.codecrafters.simplejwt.authzero.AuthzeroTokenResolver}, developers
+ * must provide the necessary configurations and dependencies, such as the
+ * {@link cn.org.codecrafters.guid.GuidCreator} for generating unique JWT IDs
+ * (JTI), the supported algorithm function, the issuer name, and the secret key
+ * used for token signing and validation. The {@link
+ * cn.org.codecrafters.simplejwt.authzero.config.AuthzeroTokenResolverConfig}
+ * class provides a convenient way to configure these dependencies.
*
* Developers using the {@code com.auth0:java-jwt} integration should be
* familiar with the concepts and usage of the {@code com.auth0:java-jwt}
diff --git a/simple-jwt-facade/pom.xml b/simple-jwt-facade/pom.xml
index b1130f4..bd72ec4 100644
--- a/simple-jwt-facade/pom.xml
+++ b/simple-jwt-facade/pom.xml
@@ -23,7 +23,7 @@
- * TokenPayload - Interface for JWT Payload Data Classes.
- *
- *
- * The {@code TokenPayload} interface is used to mark a data class as suitable
+ * {@code TokenPayload} interface is used to mark a data class as suitable
* for being used as the payload in a JSON Web Token (JWT). Any class
* implementing this interface can be used to represent the payload data that
* will be included in a JWT.
- *
*
* Implementing this interface indicates that the data class contains
* information that needs to be securely transmitted and verified as part of a
* JWT. The payload typically contains claims or attributes that provide
* additional information about the JWT subject or context.
- *
*
* Usage:
* To use a class as a JWT payload, simply implement the {@code TokenPayload}
@@ -45,8 +39,9 @@ import java.util.Map;
* }
*
*
+ * @author Zihlu Wang
+ * @version 1.1.0
* @since 1.0.0
- * @version 1.0.0
*/
public interface TokenPayload {
diff --git a/simple-jwt-facade/src/main/java/cn/org/codecrafters/simplejwt/TokenResolver.java b/simple-jwt-facade/src/main/java/cn/org/codecrafters/simplejwt/TokenResolver.java
index 65189d3..c69818d 100644
--- a/simple-jwt-facade/src/main/java/cn/org/codecrafters/simplejwt/TokenResolver.java
+++ b/simple-jwt-facade/src/main/java/cn/org/codecrafters/simplejwt/TokenResolver.java
@@ -22,25 +22,21 @@ import java.time.Duration;
import java.util.Map;
/**
- *
- * 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.
- *
+ * {@code TokenResolver} 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.
*
* Token Creation:
* 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.
- *
*
* Token Extraction:
* 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.
- *
*
* Token Renewal:
* The interface also offers methods for token renewal. Clients can renew an
@@ -50,7 +46,7 @@ import java.util.Map;
* @param
- * This annotation is used to mark a property of a data class that should be
- * 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.
- *
- *
- * Usage:
+ * Usage:
* To exclude a property from the JWT payload, annotate the property with
* {@code @ExcludeFromPayload}:
*
@@ -45,14 +43,15 @@ import java.lang.annotation.Target;
* // Getters and setters...
* }
* }
- *
- * Note:
- * This annotation should be used only on properties that are not intended to
+ *
+ * Note:
+ * This annotation should be used 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.
+ * reasons only. 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)
diff --git a/simple-jwt-facade/src/main/java/cn/org/codecrafters/simplejwt/annotations/package-info.java b/simple-jwt-facade/src/main/java/cn/org/codecrafters/simplejwt/annotations/package-info.java
index 86f3e22..0aca24d 100644
--- a/simple-jwt-facade/src/main/java/cn/org/codecrafters/simplejwt/annotations/package-info.java
+++ b/simple-jwt-facade/src/main/java/cn/org/codecrafters/simplejwt/annotations/package-info.java
@@ -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;
\ No newline at end of file
diff --git a/simple-jwt-facade/src/main/java/cn/org/codecrafters/simplejwt/config/TokenResolverConfig.java b/simple-jwt-facade/src/main/java/cn/org/codecrafters/simplejwt/config/TokenResolverConfig.java
index 619b0c9..2989a03 100644
--- a/simple-jwt-facade/src/main/java/cn/org/codecrafters/simplejwt/config/TokenResolverConfig.java
+++ b/simple-jwt-facade/src/main/java/cn/org/codecrafters/simplejwt/config/TokenResolverConfig.java
@@ -17,21 +17,21 @@
package cn.org.codecrafters.simplejwt.config;
+import cn.org.codecrafters.simplejwt.TokenResolver;
import cn.org.codecrafters.simplejwt.constants.TokenAlgorithm;
/**
- *
- * The TokenResolverConfig interface provides a mechanism to configure a
- * TokenResolver with algorithm functions.
- *
+ * The {@code TokenResolverConfig} provides a mechanism to configure a
+ * {@link TokenResolver} with algorithm functions.
*
* This generic interface is used to define the configuration details for a
- * TokenResolver that utilizes algorithm functions. The interface allows for
- * specifying algorithm functions corresponding to different TokenAlgorithm
- * instances supported by the TokenResolver implementation.
+ * {@link TokenResolver} that utilizes algorithm functions. The interface
+ * allows for specifying algorithm functions corresponding to different {@link
+ * TokenAlgorithm} instances supported by the {@link TokenResolver}
+ * implementation.
*
* @param
* This method returns the algorithm function associated with the given
- * TokenAlgorithm. The provided TokenAlgorithm represents the specific
- * algorithm for which the corresponding algorithm function is required.
- * The returned AlgorithmFunction represents the function implementation
- * that can be used by the TokenResolver to handle the specific algorithm.
+ * {@link TokenAlgorithm}. The provided TokenAlgorithm represents the
+ * specific algorithm for which the corresponding algorithm function is
+ * required. The returned {@code Algo} represents the function
+ * implementation that can be used by the {@link TokenResolver} to handle
+ * the specific algorithm.
*
- * @param algorithm the TokenAlgorithm for which the algorithm function is
- * required
- * @return the algorithm function associated with the given TokenAlgorithm
+ * @param algorithm the {@link TokenAlgorithm} for which the algorithm
+ * function is required
+ * @return the algorithm function associated with the given {@link
+ * TokenAlgorithm}
*/
Algo getAlgorithm(TokenAlgorithm algorithm);
diff --git a/simple-jwt-facade/src/main/java/cn/org/codecrafters/simplejwt/config/package-info.java b/simple-jwt-facade/src/main/java/cn/org/codecrafters/simplejwt/config/package-info.java
index 2b30c2d..97774c4 100644
--- a/simple-jwt-facade/src/main/java/cn/org/codecrafters/simplejwt/config/package-info.java
+++ b/simple-jwt-facade/src/main/java/cn/org/codecrafters/simplejwt/config/package-info.java
@@ -16,17 +16,16 @@
*/
/**
- *
* 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.
- *
+ * the {@code cn.org.codecrafters:simple-jwt-facade} library. They are used
+ * to customize the behavior of the library and allow developers to fine-tune
+ * various aspects of JWT generation and validation.
*
* Other configuration classes may be added in the future to support additional
- * customization options and features. Developers using the Simple JWT library
- * should be familiar with the available configuration options to ensure proper
- * integration and usage of the library.
+ * customisation options and features. Developers using the
+ * {@code cn.org.codecrafters:simple-jwt-facade} library should be familiar
+ * with the available configuration options to ensure proper integration and
+ * usage of the library.
*
* @since 1.0.0
*/
diff --git a/simple-jwt-facade/src/main/java/cn/org/codecrafters/simplejwt/constants/PredefinedKeys.java b/simple-jwt-facade/src/main/java/cn/org/codecrafters/simplejwt/constants/PredefinedKeys.java
index c648b19..2df9309 100644
--- a/simple-jwt-facade/src/main/java/cn/org/codecrafters/simplejwt/constants/PredefinedKeys.java
+++ b/simple-jwt-facade/src/main/java/cn/org/codecrafters/simplejwt/constants/PredefinedKeys.java
@@ -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.
- *
- * The class provides the following standard JWT claim constants:
+ *
+ * The class provides the following standard JWT claim constants:
* The class also contains a list of all the standard claim constants, accessible via the {@link #KEYS} field. This
+ *
+ * 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.
- *
- * Note: This class is final and cannot be instantiated. It only serves as a utility class to hold the standard JWT
+ *
+ * Note: This class is final and cannot be instantiated. It only serves as a utility class to hold the standard JWT
* claim constants.
*
+ * @author Zihlu Wang
+ * @version 1.1.0
* @since 1.0.0
*/
public final class PredefinedKeys {
@@ -86,11 +88,13 @@ public final class PredefinedKeys {
public static final List
+ * This class is intended to be used as a utility class with only static
+ * constants and methods.
*/
private PredefinedKeys() {
- // Private constructor to prevent instantiation
}
}
diff --git a/simple-jwt-facade/src/main/java/cn/org/codecrafters/simplejwt/constants/TokenAlgorithm.java b/simple-jwt-facade/src/main/java/cn/org/codecrafters/simplejwt/constants/TokenAlgorithm.java
index 5b71e16..3b831fd 100644
--- a/simple-jwt-facade/src/main/java/cn/org/codecrafters/simplejwt/constants/TokenAlgorithm.java
+++ b/simple-jwt-facade/src/main/java/cn/org/codecrafters/simplejwt/constants/TokenAlgorithm.java
@@ -25,9 +25,8 @@ 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.
- *
- * Supported Algorithms:
- * This enum includes the following supported algorithms:
+ *
+ * Supported Algorithms:
*
- * This {@code UnsupportedAlgorithmException} is to indicates that the given
- * algorithm is not supported by TokenResolver yet.
- *
- *
- * To support a specified algorithm, you could
- *
+ * If you want the supports to an unsupported algorithm, you could
+ *
- * Constructs a new runtime exception with the specified detail message and
- * cause.
- *
- * Note that the detail message associated with
- * {@code cause} is not automatically incorporated in
- * this runtime exception's detail message.
- *
+ * Constructs a new {@code UnsupportedAlgorithmException} with the
+ * specified detail message and cause.
*
* @param message the detail message (which is saved for later retrieval
* by the {@link #getMessage()} method).
@@ -73,11 +71,12 @@ public class UnsupportedAlgorithmException extends RuntimeException {
}
/**
- * Constructs a new runtime exception with the specified cause and a
- * detail message of {@code (cause==null ? null : cause.toString())}
- * (which typically contains the class and detail message of
- * {@code cause}). This constructor is useful for runtime exceptions
- * that are little more than wrappers for other throwables.
+ * Constructs a new {@code UnsupportedAlgorithmException} with the
+ * specified cause and a detail message of
+ * {@code (cause==null ? null : cause.toString())} (which typically
+ * contains the class and detail message of {@code cause}). This
+ * constructor is useful for runtime exceptions that are little more
+ * than wrappers for other throwable.
*
* @param cause the cause (which is saved for later retrieval by the
* {@link #getCause()} method). (A {@code null} value is
@@ -90,18 +89,17 @@ public class UnsupportedAlgorithmException extends RuntimeException {
}
/**
- * Constructs a new runtime exception with the specified detail
- * message, cause, suppression enabled or disabled, and writable
- * stack trace enabled or disabled.
+ * Constructs a new {@code UnsupportedAlgorithmException} with the
+ * specified detail message, cause, suppression enabled or disabled, and
+ * writable 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);
diff --git a/simple-jwt-facade/src/main/java/cn/org/codecrafters/simplejwt/exceptions/WeakSecretException.java b/simple-jwt-facade/src/main/java/cn/org/codecrafters/simplejwt/exceptions/WeakSecretException.java
index be78140..25126f9 100644
--- a/simple-jwt-facade/src/main/java/cn/org/codecrafters/simplejwt/exceptions/WeakSecretException.java
+++ b/simple-jwt-facade/src/main/java/cn/org/codecrafters/simplejwt/exceptions/WeakSecretException.java
@@ -18,24 +18,31 @@
package cn.org.codecrafters.simplejwt.exceptions;
/**
- * WeakSecretException
+ * {@code WeakSecretException} represents that your secret is too weak to be
+ * used in signing JWTs.
+ *
+ * {@code WeakSecretException} will only appears that if you are using the
+ * implementation module {@code cn.org.codecrafters:simple-jwt-jjwt} due to
+ * it is implemented by {@code io.jsonwebtoken:jjwt}.
*
* @author Zihlu Wang
+ * @version 1.1.0
+ * @since 1.0.0
*/
public class WeakSecretException extends RuntimeException {
/**
- * Constructs a new runtime exception with {@code null} as its
- * detail message. The cause is not initialized, and may subsequently be
+ * Constructs a new {@code WeakSecretException} with {@code null} as its
+ * detail message. The cause is not initialized, and may subsequently be
* initialized by a call to {@link #initCause}.
*/
public WeakSecretException() {
}
/**
- * Constructs a new runtime exception with the specified detail message.
- * The cause is not initialized, and may subsequently be initialized by a
- * call to {@link #initCause}.
+ * Constructs a new {@code WeakSecretException} with the specified detail
+ * message. The cause is not initialized, and may subsequently be
+ * initialized by a call to {@link #initCause}.
*
* @param message the detail message. The detail message is saved for
* later retrieval by the {@link #getMessage()} method.
@@ -45,10 +52,11 @@ public class WeakSecretException extends RuntimeException {
}
/**
- * Constructs a new runtime exception with the specified detail message and
- * cause. Note that the detail message associated with
- * {@code cause} is not automatically incorporated in
- * this runtime exception's detail message.
+ * Constructs a new {@code WeakSecretException} with the specified detail
+ * message and cause.
+ *
+ * Note that the detail message associated with {@code cause} is not
+ * 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).
@@ -56,42 +64,41 @@ public class WeakSecretException extends RuntimeException {
* {@link #getCause()} method). (A {@code null} value is
* permitted, and indicates that the cause is nonexistent or
* unknown.)
- * @since 1.4
+ * @since 1.0.0
*/
public WeakSecretException(String message, Throwable cause) {
super(message, cause);
}
/**
- * Constructs a new runtime exception with the specified cause and a
- * detail message of {@code (cause==null ? null : cause.toString())}
+ * Constructs a new {@code WeakSecretException} with the specified cause
+ * and a detail message of {@code (cause==null ? null : cause.toString())}
* (which typically contains the class and detail message of
- * {@code cause}). This constructor is useful for runtime exceptions
- * that are little more than wrappers for other throwables.
+ * {@code cause}). This constructor is useful for runtime exceptions that
+ * are little more than wrappers for other throwable.
*
* @param cause the cause (which is saved for later retrieval by the
* {@link #getCause()} method). (A {@code null} value is
* permitted, and indicates that the cause is nonexistent or
* unknown.)
- * @since 1.4
+ * @since 1.0.0
*/
public WeakSecretException(Throwable cause) {
super(cause);
}
/**
- * Constructs a new runtime exception with the specified detail
+ * Constructs a new {@code WeakSecretException} with the specified detail
* message, cause, suppression enabled or disabled, and writable
* 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 WeakSecretException(String message, Throwable cause, boolean enableSuppression, boolean writableStackTrace) {
super(message, cause, enableSuppression, writableStackTrace);
diff --git a/simple-jwt-facade/src/main/java/cn/org/codecrafters/simplejwt/exceptions/package-info.java b/simple-jwt-facade/src/main/java/cn/org/codecrafters/simplejwt/exceptions/package-info.java
index fcd7929..b8f48f8 100644
--- a/simple-jwt-facade/src/main/java/cn/org/codecrafters/simplejwt/exceptions/package-info.java
+++ b/simple-jwt-facade/src/main/java/cn/org/codecrafters/simplejwt/exceptions/package-info.java
@@ -16,26 +16,23 @@
*/
/**
- *
* 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.
- *
- *
+ * custom exception classes related to the
+ * {@code cn.org.codecrafters:simple-jwt-facade} 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.
*
* Custom exception classes in this package are designed to enhance the
* robustness and reliability of the JWT handling process by providing clear
* and meaningful error messages to the developers. They help developers
* identify and troubleshoot issues related to JWT generation, validation, or
- * extraction and ensure smooth operation and error handling in their
- * applications.
- *
- *
+ * extraction and ensure smooth operation and error handling in
+ * their applications.
*
- * Developers using the Simple JWT library should be aware of the possible
- * exceptions that can be thrown and handle them appropriately to ensure secure
- * and reliable JWT handling in their Java applications.
+ * Developers using the {@code cn.org.codecrafters:simple-jwt-facade} library
+ * should be aware of the possible exceptions that can be thrown and handle
+ * them appropriately to ensure secure and reliable JWT handling in their
+ * Java applications.
*
* @since 1.0.0
*/
diff --git a/simple-jwt-facade/src/main/java/cn/org/codecrafters/simplejwt/package-info.java b/simple-jwt-facade/src/main/java/cn/org/codecrafters/simplejwt/package-info.java
index feca898..791dae8 100644
--- a/simple-jwt-facade/src/main/java/cn/org/codecrafters/simplejwt/package-info.java
+++ b/simple-jwt-facade/src/main/java/cn/org/codecrafters/simplejwt/package-info.java
@@ -16,28 +16,23 @@
*/
/**
- *
* 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
- * widely-used standard for representing claims between two parties, typically
- * 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.
- *
- *
+ * 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 widely-used standard for representing claims between two parties,
+ * typically 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.
*
- * 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
+ * The Simple JWT library is designed to be flexible and customisable,
+ * 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.
- *
- *
*
* Developers should refer to the official documentation and examples for the
- * Simple JWT project to understand how to use the library effectively and
- * securely in their Java applications.
+ * Simple JWT project to understand how to use the library effectively
+ * and securely in their Java applications.
*
*
* @since 1.0.0
diff --git a/simple-jwt-jjwt/pom.xml b/simple-jwt-jjwt/pom.xml
index eaf8804..e5acdeb 100644
--- a/simple-jwt-jjwt/pom.xml
+++ b/simple-jwt-jjwt/pom.xml
@@ -23,7 +23,7 @@
+ * Dependencies:
+ * 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.
+ *
+ * Usage:
+ * To use the {@code JjwtTokenResolver}, first, create an instance of this
+ * class:
+ *
+ * Then, you can utilize the various methods provided by this resolver to
+ * handle JWT tokens:
+ *
+ * Note:
+ * 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
+ * This configuration class is used to establish the mapping between the
+ * standard {@link TokenAlgorithm} defined within the
+ * {@code JjwtTokenResolverConfig} and the specific algorithms used by the
+ * {@code io.jsonwebtoken:jjwt} library, which is the underlying library used
+ * by {@code JjwtTokenResolver} to handle JSON Web Tokens (JWTs).
+ *
+ * Algorithm Mapping:
+ * The {@code JjwtTokenResolverConfig} allows specifying the relationship
+ * between the standard {@link TokenAlgorithm} instances supported by {@link
+ * JjwtTokenResolver} 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 {@link TokenAlgorithm} instances, and the
+ * values represent the algorithm functions used by
+ * {@code io.jsonwebtoken:jjwt} library for each corresponding key.
+ *
+ * Note:
+ * 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
* The package {@code cn.org.codecrafters.simplejwt.jjwt.config} contains
* configuration classes related to the {@link
* cn.org.codecrafters.simplejwt.jjwt.JjwtTokenResolver}
* implementation.
- *
*
* 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.
- *
*
* 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.
- *
*
* The configuration options in this package help developers integrate and
* configure the {@link
@@ -45,13 +41,12 @@
* 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.
- *
*
* It is recommended to explore the classes in this package to understand how
* to configure and use the {@link
* cn.org.codecrafters.simplejwt.jjwt.JjwtTokenResolver} effectively
* in the Spring Boot environment to handle JWT authentication and
- * authorization securely and efficiently.
+ * authorisation securely and efficiently.
*
* @since 1.0.0
*/
diff --git a/simple-jwt-jjwt/src/main/java/cn/org/codecrafters/simplejwt/jjwt/package-info.java b/simple-jwt-jjwt/src/main/java/cn/org/codecrafters/simplejwt/jjwt/package-info.java
index 88c40b7..1753d09 100644
--- a/simple-jwt-jjwt/src/main/java/cn/org/codecrafters/simplejwt/jjwt/package-info.java
+++ b/simple-jwt-jjwt/src/main/java/cn/org/codecrafters/simplejwt/jjwt/package-info.java
@@ -19,11 +19,10 @@
* This package contains classes related to the integration of the {@code
* io.jsonwebtoken:jjwt-api} library in the Simple JWT project. {@code
* io.jsonwebtoken:jjwt-api} is a powerful and widely-used Identity as a Service
- * (IDaaS) platform that provides secure authentication and authorization
+ * (IDaaS) platform that provides secure authentication and authorisation
* 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.
- *
*
* The main class in this package is the {@link
* cn.org.codecrafters.simplejwt.jjwt.JjwtTokenResolver}, which
@@ -33,22 +32,21 @@
* 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.
- *
*
- * The {@code JjwtTokenResolver} relies on the {@code io.jsonwebtoken:jjwt-api}
+ * The {@link cn.org.codecrafters.simplejwt.jjwt.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.
- *
+ * {@link io.jsonwebtoken.SignatureAlgorithm} class to define and use different
+ * algorithms for JWT signing and verification.
*
- * To use the {@code JjwtTokenResolver}, developers must provide the necessary
- * configurations and dependencies, such as the {@code GuidCreator} for
- * generating unique JWT IDs (JTI), the supported algorithm function, the
- * issuer name, and the secret key used for token signing and validation. The
- * {@code JjwtTokenResolverConfig} class provides a convenient way to configure
- * these dependencies.
- *
+ * To use the {@link cn.org.codecrafters.simplejwt.jjwt.JjwtTokenResolver},
+ * developers must provide the necessary configurations and dependencies, such
+ * as the {@link cn.org.codecrafters.guid.GuidCreator} for generating unique
+ * JWT IDs (JTI), the supported algorithm function, the issuer name, and the
+ * secret key used for token signing and validation. The
+ * {@link cn.org.codecrafters.simplejwt.jjwt.config.JjwtTokenResolverConfig}
+ * class provides a convenient way to configure these dependencies.
*
* Developers using the {@code io.jsonwebtoken:jjwt-api} integration should be
* familiar with the concepts and usage of the {@code io.jsonwebtoken:jjwt-api}
diff --git a/simple-jwt-spring-boot-starter/pom.xml b/simple-jwt-spring-boot-starter/pom.xml
index 0a5575b..9e6a49c 100644
--- a/simple-jwt-spring-boot-starter/pom.xml
+++ b/simple-jwt-spring-boot-starter/pom.xml
@@ -23,7 +23,7 @@
- * 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.
- *
- *
- * 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.
- *
+ * configures the {@link AuthzeroTokenResolver} bean based on the available
+ * options and properties.
*
* 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
+ * However, developers still have the flexibility to customise the behavior of
* the library by providing their own configurations and properties.
- *
*
* @author Zihlu Wang
* @version 1.0.0
diff --git a/simple-jwt-spring-boot-starter/src/main/java/cn/org/codecrafters/simplejwt/autoconfiguration/GuidAutoConfiguration.java b/simple-jwt-spring-boot-starter/src/main/java/cn/org/codecrafters/simplejwt/autoconfiguration/GuidAutoConfiguration.java
index 77287e4..a4d452c 100644
--- a/simple-jwt-spring-boot-starter/src/main/java/cn/org/codecrafters/simplejwt/autoconfiguration/GuidAutoConfiguration.java
+++ b/simple-jwt-spring-boot-starter/src/main/java/cn/org/codecrafters/simplejwt/autoconfiguration/GuidAutoConfiguration.java
@@ -29,9 +29,11 @@ import org.springframework.context.annotation.Conditional;
import java.util.UUID;
/**
- * GuidAutoConfiguration
+ * Autoconfiguration for injecting a {@link GuidCreator} for generating jwt id.
*
* @author Zihlu Wang
+ * @version 1.1.0
+ * @since 1.0.0
*/
@Slf4j
@AutoConfiguration
diff --git a/simple-jwt-spring-boot-starter/src/main/java/cn/org/codecrafters/simplejwt/autoconfiguration/JjwtTokenResolverAutoConfiguration.java b/simple-jwt-spring-boot-starter/src/main/java/cn/org/codecrafters/simplejwt/autoconfiguration/JjwtTokenResolverAutoConfiguration.java
index 29d5b09..26cfc87 100644
--- a/simple-jwt-spring-boot-starter/src/main/java/cn/org/codecrafters/simplejwt/autoconfiguration/JjwtTokenResolverAutoConfiguration.java
+++ b/simple-jwt-spring-boot-starter/src/main/java/cn/org/codecrafters/simplejwt/autoconfiguration/JjwtTokenResolverAutoConfiguration.java
@@ -34,28 +34,25 @@ import org.springframework.boot.context.properties.EnableConfigurationProperties
import org.springframework.context.annotation.Bean;
/**
- *
- * JjwtTokenResolverAutoConfiguration is responsible for automatically
+ * {@code 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.
- *
*
- * 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.
- *
+ * configures the {@link JjwtTokenResolver} bean based on the available options
+ * and properties.
*
* 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
diff --git a/simple-jwt-spring-boot-starter/src/main/java/cn/org/codecrafters/simplejwt/autoconfiguration/conditions/GuidCreatorCondition.java b/simple-jwt-spring-boot-starter/src/main/java/cn/org/codecrafters/simplejwt/autoconfiguration/conditions/GuidCreatorCondition.java
index b83e2fa..287b3cd 100644
--- a/simple-jwt-spring-boot-starter/src/main/java/cn/org/codecrafters/simplejwt/autoconfiguration/conditions/GuidCreatorCondition.java
+++ b/simple-jwt-spring-boot-starter/src/main/java/cn/org/codecrafters/simplejwt/autoconfiguration/conditions/GuidCreatorCondition.java
@@ -9,11 +9,11 @@ import org.springframework.core.type.AnnotatedTypeMetadata;
import java.util.Objects;
/**
- * GuidCreatorCondition
- *
- * Created on 28 Aug 2023
+ * The conditions to create bean {@code jtiCreator}.
*
* @author Zihlu Wang
+ * @version 1.1.0
+ * @since 1.0.0
*/
@Slf4j
public class GuidCreatorCondition implements Condition {
diff --git a/simple-jwt-spring-boot-starter/src/main/java/cn/org/codecrafters/simplejwt/autoconfiguration/properties/SimpleJwtProperties.java b/simple-jwt-spring-boot-starter/src/main/java/cn/org/codecrafters/simplejwt/autoconfiguration/properties/SimpleJwtProperties.java
index e176893..8105cf3 100644
--- a/simple-jwt-spring-boot-starter/src/main/java/cn/org/codecrafters/simplejwt/autoconfiguration/properties/SimpleJwtProperties.java
+++ b/simple-jwt-spring-boot-starter/src/main/java/cn/org/codecrafters/simplejwt/autoconfiguration/properties/SimpleJwtProperties.java
@@ -24,28 +24,24 @@ import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
/**
- *
* {@code SimpleJwtProperties} is a configuration properties class used to
- * store the properties related to Simple JWT library configuration. These
+ * store the properties related to Simple JWT library configurations. These
* properties can be configured in the application's properties file (e.g.,
* application.properties) with the prefix "code-crafters.simple-jwt".
- *
- *
*
- * 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.
- *
- *
+ * {@code SimpleJwtProperties} provides configuration options for the JWT
+ * algorithm, issuer, and secret. The properties are used by the {@link
+ * AuthzeroTokenResolverAutoConfiguration} and {@link
+ * cn.org.codecrafters.simplejwt.jjwt.JjwtTokenResolver} to set up the
+ * necessary configurations for JWT generation and validation.
*
- * Developers can customize the JWT algorithm, issuer, and secret by setting
+ * Developers can customise 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.
- *
+ * {@code 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
diff --git a/simple-jwt-spring-boot-starter/src/main/java/cn/org/codecrafters/simplejwt/autoconfiguration/properties/package-info.java b/simple-jwt-spring-boot-starter/src/main/java/cn/org/codecrafters/simplejwt/autoconfiguration/properties/package-info.java
index fc5a7f4..be6889c 100644
--- a/simple-jwt-spring-boot-starter/src/main/java/cn/org/codecrafters/simplejwt/autoconfiguration/properties/package-info.java
+++ b/simple-jwt-spring-boot-starter/src/main/java/cn/org/codecrafters/simplejwt/autoconfiguration/properties/package-info.java
@@ -16,15 +16,12 @@
*/
/**
- *
* 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.
- *
- *
*
* Developers can customize the JWT algorithm, issuer, and secret by setting
* the corresponding properties in the application's properties file with the
diff --git a/webcal/README.md b/webcal/README.md
index ec896ed..d421196 100644
--- a/webcal/README.md
+++ b/webcal/README.md
@@ -2,12 +2,12 @@
## Introduction
-The module `webcal` is a Java library that facilitates the generation and resolution of iCalendar content for web-based calendar applications. It provides a flexible and easy-to-use API for creating web calendars with customizable settings and events.
+The module `webcal` is a Java library that facilitates the generation and resolution of iCalendar content for web-based calendar applications. It provides a flexible and easy-to-use API for creating web calendars with customisable settings and events.
### Key features
- Create and manage web calendars with events, including event details such as summary, description, location, and more.
-- Define event classifications and categories for better organization and filtering of calendar data.
+- Define event classifications and categories for better organisation and filtering of calendar data.
- Set event start and end times, durations, and time zones to handle various scheduling scenarios.
- Configure event priorities and completion percentages for visual representation in the calendar.
- Generate iCalendar format output suitable for web calendar applications.
diff --git a/webcal/pom.xml b/webcal/pom.xml
index 8e77cae..4419d64 100644
--- a/webcal/pom.xml
+++ b/webcal/pom.xml
@@ -23,7 +23,7 @@
- * It allows users to create and customize calendar components and events and
- * generate an iCalendar string containing all the calendar information.
- *
- * Usage Example:
+ * It allows users to create and customise calendar components and events and
+ * generate an iCalendar string containing all the calendar information.
+ *
+ * Usage Example:
*
- * 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.
+ * The {@code 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 {
/**
- * The VCALENDAR tag for iCalendar format
+ * The {@code VCALENDAR} tag for iCalendar format
*/
private final static String TAG = "VCALENDAR";
@@ -63,7 +61,6 @@ public final class WebCalendar {
/**
* The company who produces this calendar.
- *
*
* This property will be used in {@code PRODID}.
*/
@@ -71,7 +68,6 @@ public final class WebCalendar {
/**
* The product name.
- *
*
* This property will be used in {@code PRODID}
*/
diff --git a/webcal/src/main/java/cn/org/codecrafters/webcal/WebCalendarEvent.java b/webcal/src/main/java/cn/org/codecrafters/webcal/WebCalendarEvent.java
index e700900..c073d19 100644
--- a/webcal/src/main/java/cn/org/codecrafters/webcal/WebCalendarEvent.java
+++ b/webcal/src/main/java/cn/org/codecrafters/webcal/WebCalendarEvent.java
@@ -28,20 +28,19 @@ import java.util.Optional;
import java.util.UUID;
/**
- * The WebCalendarEvent class represents an event in the web calendar. It
- * extends the abstract class WebCalendarNode and provides additional methods
- * to set properties specific to events.
- *
+ * The {@code WebCalendarEvent} class represents an event in the web calendar.
+ * It extends the abstract class WebCalendarNode and provides additional
+ * methods to set properties specific to events.
*
* Users can use the methods in this class to add categories, set the
- * classification, add comments, descriptions, locations, set percent complete
- * , set priority, set summary, set start time, set end time, set duration, set
- * URL, set UID, and set timezone for the event. After setting the properties,
- * users can call the {@link #resolve()} method to generate the corresponding
- * iCalendar content for the event.
+ * classification, add comments, descriptions, locations, set percent
+ * complete, set priority, set summary, set start time, set end time, set
+ * duration, set URL, set UID, and set timezone for the event. After setting
+ * the properties, users can call the {@link #resolve()} method to generate the
+ * corresponding 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 {
@@ -275,7 +274,7 @@ public final class WebCalendarEvent extends WebCalendarNode {
.map((item) -> "DTEND" + Optional.ofNullable(timezone).map(tz -> ";TZID=" + tz).orElse("") + ":" +
end.format(DateTimeFormatter.ISO_LOCAL_DATE_TIME) + "\n").orElse("") +
Optional.ofNullable(classification)
- .map((item) -> "CLASS:" + item.getClassification() + "\n").orElse("") +
+ .map((item) -> "CLASS:" + item.name() + "\n").orElse("") +
Optional.ofNullable(comment).map((item) -> "COMMENT:" + item + "\n").orElse("") +
Optional.ofNullable(description).map((item) -> "DESCRIPTION:" + item + "\n").orElse("") +
Optional.ofNullable(location).map((item) -> "LOCATION:" + item + "\n").orElse("") +
diff --git a/webcal/src/main/java/cn/org/codecrafters/webcal/WebCalendarNode.java b/webcal/src/main/java/cn/org/codecrafters/webcal/WebCalendarNode.java
index dba99b6..5f56b11 100644
--- a/webcal/src/main/java/cn/org/codecrafters/webcal/WebCalendarNode.java
+++ b/webcal/src/main/java/cn/org/codecrafters/webcal/WebCalendarNode.java
@@ -25,17 +25,16 @@ import java.util.ArrayList;
import java.util.List;
/**
- * The abstract sealed class WebCalendarNode represents a node in the web
- * calendar, such as an event, a to-do item, or an alarm. It provides common
- * properties and methods for all calendar components and events.
- *
+ * The abstract sealed class {@code WebCalendarNode} represents a node in the
+ * web calendar, such as an event, a to-do item, or an alarm. It provides
+ * common properties and methods for all calendar components and events.
*
- * Subclasses of WebCalendarNode should implement the {@link #resolve()} method
- * to generate the corresponding iCalendar content for the specific calendar
- * component or event.
+ * Subclasses of {@code WebCalendarNode} should implement the {@link
+ * #resolve()} method to generate the corresponding iCalendar content for the
+ * specific calendar component or event.
*
* @author Zihlu Wang
- * @version 1.0.0
+ * @version 1.1.0
* @since 1.0.0
*/
public abstract sealed class WebCalendarNode
diff --git a/webcal/src/main/java/cn/org/codecrafters/webcal/config/Classification.java b/webcal/src/main/java/cn/org/codecrafters/webcal/config/Classification.java
index 6b45c5f..2f40751 100644
--- a/webcal/src/main/java/cn/org/codecrafters/webcal/config/Classification.java
+++ b/webcal/src/main/java/cn/org/codecrafters/webcal/config/Classification.java
@@ -20,9 +20,8 @@ package cn.org.codecrafters.webcal.config;
import lombok.Getter;
/**
- * The Classification enum represents the classification levels of calendar
- * content based on RFC 5545.
- *
+ * The {@code Classification} enum represents the classification levels of
+ * calendar content based on RFC-5545.
*
* Calendar events or components can be classified as one of the following
* levels:
@@ -42,55 +41,34 @@ import lombok.Getter;
*
* Indicates that the calendar content is public and can be freely
* distributed.
*/
- PUBLIC("PUBLIC"),
+ PUBLIC,
/**
* Private classification level.
- *
*
* Indicates that the calendar content is private and should not be shared
* with others.
*/
- PRIVATE("PRIVATE"),
+ PRIVATE,
/**
* Confidential classification level.
- *
*
* Indicates that the calendar content is confidential and should be kept
* strictly private.
*/
- CONFIDENTIAL("CONFIDENTIAL"),
+ CONFIDENTIAL,
;
- /**
- * -- GETTER --
- * Get the string representation of the classification level.
- *
- * @return the string representation of the classification level
- */
- private final String classification;
-
- /**
- * Constructor for Classification enum.
- *
- * @param classification the classification level as a string representation
- */
- Classification(String classification) {
- this.classification = classification;
- }
-
}
diff --git a/webcal/src/main/java/cn/org/codecrafters/webcal/config/package-info.java b/webcal/src/main/java/cn/org/codecrafters/webcal/config/package-info.java
index 894709e..fdfc842 100644
--- a/webcal/src/main/java/cn/org/codecrafters/webcal/config/package-info.java
+++ b/webcal/src/main/java/cn/org/codecrafters/webcal/config/package-info.java
@@ -16,11 +16,10 @@
*/
/**
- * The package cn.org.codecrafters.webcal.config contains classes related to
- * the configuration and settings of the web calendar module. It provides
- * various configurations and constants used in the generation and resolution
- * of iCalendar content.
- *
+ * The package {@code cn.org.codecrafters.webcal.config} contains classes
+ * related to the configuration and settings of the web calendar module. It
+ * provides various configurations and constants used in the generation and
+ * resolution of iCalendar content.
* The classes in this package include:
* The main classes and modules in this package include:
*
@@ -84,26 +79,31 @@ import java.util.function.Function;
* .getValue(2);
*
* The above expressions perform various mathematical calculations using the
- * ChainedCalcUtil class.
- *
+ * {@code ChainedCalcUtil} class.
*
@@ -58,9 +53,8 @@ import java.util.Optional;
* // Perform SHA-512 hash operation
* String sha512Hash = HashUtil.sha512("someString");
*
- * The above examples demonstrate how to use the HashUtil class to calculate
- * hash values for a given string using different algorithms.
- *
+ * The above examples demonstrate how to use the {@code HashUtil} class to
+ * calculate hash values for a given string using different algorithms.
*
*
- *
*
diff --git a/pom.xml b/pom.xml
index 49b6f1b..77edffc 100644
--- a/pom.xml
+++ b/pom.xml
@@ -29,7 +29,7 @@
*
* @author Zihlu Wang
- * @version 1.0.0
+ * @version 1.1.0
* @since 1.0.0
*/
-@Getter
public enum Classification {
/**
* Public classification level.
- *
* {@code
+ * var secret = AesUtil.generateRandomSecret(); // Let's presume the result is
+ * // "3856faef0d2d4f33"
+ * }
+ * pg:".
+ *
+ * # original
+ * app.example-properties=Sample Value
+ *
+ * # encrypted with key 3856faef0d2d4f33
+ * app.example-properties=pg:t4YBfv8M9ZmTzWgTi2gJqg==
+ *
+ * After that, before running, you need to add the command line arguments
+ * "pg.key" as the following codes: {@code --pg.key={@code
* // Creating a new JWT token
* String token =
@@ -84,7 +79,6 @@ import java.util.*;
* String renewedToken =
* tokenResolver.renew(token, Duration.ofMinutes(30), customPayloads);
* }
- *
*
*
- *
- *
*
*
- * @version 1.0.0
+ * @author Zihlu Wang
+ * @version 1.1.0
* @since 1.0.0
*/
@Getter
diff --git a/simple-jwt-facade/src/main/java/cn/org/codecrafters/simplejwt/constants/package-info.java b/simple-jwt-facade/src/main/java/cn/org/codecrafters/simplejwt/constants/package-info.java
index 192ea9d..2c7726e 100644
--- a/simple-jwt-facade/src/main/java/cn/org/codecrafters/simplejwt/constants/package-info.java
+++ b/simple-jwt-facade/src/main/java/cn/org/codecrafters/simplejwt/constants/package-info.java
@@ -22,6 +22,5 @@
* configuration parameters.
*
* @since 1.0.0
- * @version 1.0.0
*/
package cn.org.codecrafters.simplejwt.constants;
\ No newline at end of file
diff --git a/simple-jwt-facade/src/main/java/cn/org/codecrafters/simplejwt/exceptions/UnsupportedAlgorithmException.java b/simple-jwt-facade/src/main/java/cn/org/codecrafters/simplejwt/exceptions/UnsupportedAlgorithmException.java
index 28c35cb..020ea63 100644
--- a/simple-jwt-facade/src/main/java/cn/org/codecrafters/simplejwt/exceptions/UnsupportedAlgorithmException.java
+++ b/simple-jwt-facade/src/main/java/cn/org/codecrafters/simplejwt/exceptions/UnsupportedAlgorithmException.java
@@ -18,30 +18,34 @@
package cn.org.codecrafters.simplejwt.exceptions;
/**
+ * This {@code UnsupportedAlgorithmException} represents the given
+ * algorithm is not supported by {@link
+ * cn.org.codecrafters.simplejwt.TokenResolver} yet.
*
+ *
*
* @author Zihlu Wang
+ * @version 1.1.0
+ * @since 1.0.0
*/
public class UnsupportedAlgorithmException extends RuntimeException {
/**
- * Constructs a new runtime exception with {@code null} as its detail
- * message. The cause is not initialized, and may subsequently be
- * initialized by a call to {@link #initCause}.
+ * Constructs a new {@code UnsupportedAlgorithmException} with {@code null}
+ * as its detail message. The cause is not initialized, and may
+ * subsequently be initialized by a call to {@link #initCause}.
*/
public UnsupportedAlgorithmException() {
}
/**
- * Constructs a new runtime exception with the specified detail message.
- * The cause is not initialized, and may subsequently be initialized by a
- * call to {@link #initCause}.
+ * Constructs a new {@code UnsupportedAlgorithmException} with the
+ * specified detail message. The cause is not initialized, and may
+ * subsequently be initialized by a call to {@link #initCause}.
*
* @param message the detail message. The detail message is saved for
* later retrieval by the {@link #getMessage()} method.
@@ -51,14 +55,8 @@ public class UnsupportedAlgorithmException extends RuntimeException {
}
/**
- * {@code
+ * TokenResolver
+ * {@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);
+ * }
+ *
* WebCalendar calendar = new WebCalendar()
* .setName("My Web Calendar")
@@ -39,20 +38,19 @@ import java.util.List;
* .addEvent(event2);
* String iCalendarString = calendar.resolve();
*
- *
*
*
*