onixbyte/onixbyte-bom
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(global): Optimised javadoc, changed the spelling to British English.

Browse Source
This commit is contained in:
Zihlu Wang
2023-09-18 15:04:10 +08:00
parent fee85d5d84
commit f80c47e8ad
41 changed files with 459 additions and 438 deletions
Download Patch File Download Diff File Expand all files Collapse all files
simple-jwt-facade/src/main/java/cn/org/codecrafters/simplejwt/SecretCreator.java
+11 -9
View File
@@ -22,9 +22,9 @@ import cn.org.codecrafters.simplejwt.exceptions.WeakSecretException;
import java.util.Random;
/**
* SecretCreator is a utility class that provides methods to generate secure
* secret strings. The generated secrets can be used as cryptographic keys or
* passwords for various security-sensitive purposes.
* {@code SecretCreator} is a utility class that provides methods to generate
* secure secret strings. The generated secrets can be used as cryptographic
* keys or passwords for various security-sensitive purposes.
*
* @author Zihlu Wang
* @version 1.1.0
@@ -83,24 +83,23 @@ public final class SecretCreator {
if (length < 32) {
throw new WeakSecretException("""
The requested secret, which is only %d characters long, is too weak. \
Please replace it with a stronger secret.
""".formatted(length));
Please replace it with a stronger secret.""".formatted(length));
}
final var randomizer = new Random();
final var randomiser = new Random();
var charset = new StringBuilder(LOWERCASE_CHARACTERS);
if (isContainCapital) charset.append(UPPERCASE_CHARACTERS);
if (isContainDigital) charset.append(DIGITS);
if (isContainSpecialSign) charset.append(SPECIAL_SIGNS);
var password = new StringBuilder();
var secretBuilder = new StringBuilder();
var charsetSize = charset.length();
for (var i = 0; i < length; ++i) {
password.append(charset.charAt(randomizer.nextInt(charsetSize)));
secretBuilder.append(charset.charAt(randomiser.nextInt(charsetSize)));
}
return password.toString();
return secretBuilder.toString();
}
/**
@@ -115,6 +114,7 @@ public final class SecretCreator {
* @return the generated secure secret
* @throws WeakSecretException if the requested secret length is less than
* 32 characters
* @see #createSecret(int, boolean, boolean, boolean)
*/
public static String createSecret(int length,
boolean isContainCapital,
@@ -132,6 +132,7 @@ public final class SecretCreator {
* @return the generated secure secret
* @throws WeakSecretException if the requested secret length is less than
* 32 characters
* @see #createSecret(int, boolean, boolean, boolean)
*/
public static String createSecret(int length,
boolean isContainCapital) {
@@ -146,6 +147,7 @@ public final class SecretCreator {
* @return the generated secure secret
* @throws WeakSecretException if the requested secret length is less than
* 32 characters
* @see #createSecret(int, boolean, boolean, boolean)
*/
public static String createSecret(int length) {
return createSecret(length, false, false, false);
simple-jwt-facade/src/main/java/cn/org/codecrafters/simplejwt/TokenPayload.java
+1 -7
View File
@@ -20,21 +20,15 @@ package cn.org.codecrafters.simplejwt;
import java.util.Map;
/**
* <p>
* TokenPayload - Interface for JWT Payload Data Classes.
*
* <p>
* 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.
*
* <p>
* 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.
*
* <p>
* <b>Usage:</b>
* To use a class as a JWT payload, simply implement the {@code TokenPayload}
simple-jwt-facade/src/main/java/cn/org/codecrafters/simplejwt/TokenResolver.java
+4 -4
View File
@@ -22,10 +22,10 @@ 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.
* <p>
* <b>Token Creation:</b>
* The interface provides overloaded methods for creating tokens with different
simple-jwt-facade/src/main/java/cn/org/codecrafters/simplejwt/annotations/ExcludeFromPayload.java
+7 -8
View File
@@ -23,11 +23,10 @@ import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**
* <p>
* 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.
* Annotation {@code ExcludeFromPayload} 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 by this annotation, it will not be included in the JWT payloads.
* <p>
* <b>Usage:</b>
* To exclude a property from the JWT payload, annotate the property with
@@ -46,10 +45,10 @@ import java.lang.annotation.Target;
* }</pre>
* <p>
* <b>Note:</b>
* This annotation should be used only on properties that are not intended to
* 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.
*
* @author Zihlu Wang
* @version 1.1.0
simple-jwt-facade/src/main/java/cn/org/codecrafters/simplejwt/config/TokenResolverConfig.java
+19 -15
View File
@@ -17,19 +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.
* <p>
* 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 <Algo> the type representing algorithm functions used by the
* {@code TokenResolver}
* {@link TokenResolver}
* @author Zihlu Wang
* @version 1.0.0
* @since 1.0.0
@@ -37,18 +39,20 @@ import cn.org.codecrafters.simplejwt.constants.TokenAlgorithm;
public interface TokenResolverConfig<Algo> {
/**
* Gets the algorithm function corresponding to the specified
* TokenAlgorithm.
* Gets the algorithm function corresponding to the specified {@link
* TokenAlgorithm}.
* <p>
* 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);
simple-jwt-facade/src/main/java/cn/org/codecrafters/simplejwt/config/package-info.java
+7 -6
View File
@@ -17,14 +17,15 @@
/**
* 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.
* <p>
* Other configuration classes may be added in the future to support additional
* customisation 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
*/
simple-jwt-facade/src/main/java/cn/org/codecrafters/simplejwt/constants/PredefinedKeys.java
+5 -3
View File
@@ -87,11 +87,13 @@ public final class PredefinedKeys {
public static final List<String> KEYS = List.of(ISSUER, SUBJECT, AUDIENCE, EXPIRATION_TIME, NOT_BEFORE, ISSUED_AT, JWT_ID);
/**
* Private constructor to prevent instantiation of the {@code PredefinedKeys} class.
* This class is intended to be used as a utility class with only static constants and methods.
* Private constructor to prevent instantiation of the
* {@code PredefinedKeys} class.
* <p>
* This class is intended to be used as a utility class with only static
* constants and methods.
*/
private PredefinedKeys() {
// Private constructor to prevent instantiation
}
}
simple-jwt-facade/src/main/java/cn/org/codecrafters/simplejwt/constants/TokenAlgorithm.java
+2 -2
View File
@@ -25,8 +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.
* <p><b>Supported Algorithms:</b>
* This enum includes the following supported algorithms:
* <p>
* <b>Supported Algorithms:</b>
* <ul>
* <li>{@link TokenAlgorithm#HS256}: HMAC SHA-256</li>
* <li>{@link TokenAlgorithm#HS384}: HMAC SHA-384</li>
simple-jwt-facade/src/main/java/cn/org/codecrafters/simplejwt/exceptions/UnsupportedAlgorithmException.java
+25 -23
View File
@@ -18,10 +18,15 @@
package cn.org.codecrafters.simplejwt.exceptions;
/**
* This {@code UnsupportedAlgorithmException} is to indicates that the given
* algorithm is not supported by TokenResolver yet.
* This {@code UnsupportedAlgorithmException} represents the given
* algorithm is not supported by {@link
* cn.org.codecrafters.simplejwt.TokenResolver} yet.
* <p>
* To support a specified algorithm, you could
* If you want the supports to an unsupported algorithm, you could
* <ul>
* <li>Commit an issue at GitHub Issues or;</li>
* <li>Communicate with us on Discord Community.</li>
* </ul>
*
* @author Zihlu Wang
* @version 1.1.0
@@ -30,17 +35,17 @@ package cn.org.codecrafters.simplejwt.exceptions;
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.
@@ -50,12 +55,8 @@ public class UnsupportedAlgorithmException extends RuntimeException {
}
/**
* Constructs a new runtime exception with the specified detail message and
* cause.
* <p>
* Note that the detail message associated with
* {@code cause} is <i>not</i> 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).
@@ -70,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
@@ -87,9 +89,9 @@ 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,
simple-jwt-facade/src/main/java/cn/org/codecrafters/simplejwt/exceptions/WeakSecretException.java
+29 -25
View File
@@ -18,8 +18,12 @@
package cn.org.codecrafters.simplejwt.exceptions;
/**
* This Exception indicates that your secret is too weak to be used in signing
* JWTs.
* {@code WeakSecretException} represents that your secret is too weak to be
* used in signing JWTs.
* <p>
* {@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
@@ -28,17 +32,17 @@ package cn.org.codecrafters.simplejwt.exceptions;
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.
@@ -48,10 +52,11 @@ public class WeakSecretException extends RuntimeException {
}
/**
* Constructs a new runtime exception with the specified detail message and
* cause. <p>Note that the detail message associated with
* {@code cause} is <i>not</i> automatically incorporated in
* this runtime exception's detail message.
* Constructs a new {@code WeakSecretException} with the specified detail
* message and cause.
* <p>
* Note that the detail message associated with {@code cause} is <i>not</i>
* automatically incorporated in this runtime exception's detail message.
*
* @param message the detail message (which is saved for later retrieval
* by the {@link #getMessage()} method).
@@ -59,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);
simple-jwt-facade/src/main/java/cn/org/codecrafters/simplejwt/exceptions/package-info.java
+10 -8
View File
@@ -17,20 +17,22 @@
/**
* 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.
* <p>
* 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.
* <p>
* Developers using the Simple JWT library should be aware of the possible
* exceptions that can be thrown and handle them appropriately to ensure secure
* 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
*/
simple-jwt-facade/src/main/java/cn/org/codecrafters/simplejwt/package-info.java
+11 -11
View File
@@ -17,22 +17,22 @@
/**
* 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.
* <b>Simple JWT</b> 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.
* <p>
* 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
* The <b>Simple JWT</b> 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.
* <p>
* 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.
* <b>Simple JWT</b> project to understand how to use the library effectively
* and securely in their Java applications.
*
*
* @since 1.0.0