writeAndFlushWith(Publisher flux;
private final HttpHeaders headers;
+ /**
+ * Constructs a ResponseAdapter with the given body and headers.
+ *
+ * @param body
+ * The Publisher that provides the response body.
+ * @param headers
+ * The headers associated with the response.
+ */
public ResponseAdapter(Publisher body, HttpHeaders headers) {
this.headers = headers;
if (body instanceof Flux) {
diff --git a/src/main/java/io/hoangtien2k3/commons/filter/properties/KeyCloakProperties.java b/src/main/java/io/hoangtien2k3/commons/filter/properties/KeyCloakProperties.java
index 3fe8701..1fa9150 100644
--- a/src/main/java/io/hoangtien2k3/commons/filter/properties/KeyCloakProperties.java
+++ b/src/main/java/io/hoangtien2k3/commons/filter/properties/KeyCloakProperties.java
@@ -18,6 +18,74 @@
import lombok.Data;
import lombok.NoArgsConstructor;
+/**
+ * The `KeyCloakProperties` class is used to store configuration properties
+ * related to Keycloak. It is a simple POJO (Plain Old Java Object) with Lombok
+ * annotations to reduce boilerplate code such as getters, setters, and
+ * constructors.
+ *
+ * Attributes:
+ *
+ * - clientId: A string representing the client ID used in
+ * Keycloak. This is typically used to identify the client application.
+ * - clientSecret: A string representing the client secret
+ * used in Keycloak. This secret is used to authenticate the client application
+ * with Keycloak.
+ *
+ *
+ * Lombok Annotations:
+ *
+ * - @Data: Generates boilerplate code such as getters,
+ * setters, `equals()`, `hashCode()`, and `toString()` methods
+ * automatically.
+ * - @AllArgsConstructor: Generates a constructor with all
+ * fields as parameters. This allows you to create an instance of the class with
+ * all attributes set at once.
+ * - @NoArgsConstructor: Generates a no-arguments
+ * constructor. This is useful for creating instances of the class without
+ * setting any attributes initially.
+ *
+ *
+ * Usage Example:
+ *
+ *
+ * {
+ * @code
+ * @Configuration
+ * @ConfigurationProperties(prefix = "keycloak")
+ * public class KeyCloakConfig {
+ *
+ * private final KeyCloakProperties keyCloakProperties;
+ *
+ * @Autowired
+ * public KeyCloakConfig(KeyCloakProperties keyCloakProperties) {
+ * this.keyCloakProperties = keyCloakProperties;
+ * }
+ *
+ * @PostConstruct
+ * public void init() {
+ * // Example of accessing properties
+ * System.out.println("Client ID: " + keyCloakProperties.getClientId());
+ * System.out.println("Client Secret: " + keyCloakProperties.getClientSecret());
+ * }
+ * }
+ * }
+ *
+ *
+ * Configuration Example:
+ *
+ * {@code
+ * # application.yml
+ * keycloak:
+ * clientId: my-client-id
+ * clientSecret: my-client-secret
+ * }
+ *
+ * In this example, the `KeyCloakProperties` class is used to bind the
+ * configuration properties from `application.yml` file. The `KeyCloakConfig`
+ * class demonstrates how to use these properties within a Spring Boot
+ * application.
+ */
@Data
@AllArgsConstructor
@NoArgsConstructor
diff --git a/src/main/java/io/hoangtien2k3/commons/filter/properties/MonitoringProperties.java b/src/main/java/io/hoangtien2k3/commons/filter/properties/MonitoringProperties.java
index 07d5ae0..34f3e87 100644
--- a/src/main/java/io/hoangtien2k3/commons/filter/properties/MonitoringProperties.java
+++ b/src/main/java/io/hoangtien2k3/commons/filter/properties/MonitoringProperties.java
@@ -20,6 +20,87 @@
import lombok.Data;
import lombok.NoArgsConstructor;
+/**
+ * The `MonitoringProperties` class holds configuration properties related to
+ * monitoring within an application. It uses Lombok annotations to automatically
+ * generate boilerplate code such as getters, setters, and constructors.
+ *
+ * Attributes:
+ *
+ * - isEnable: A boolean flag indicating whether monitoring
+ * is enabled or not. Defaults to `true` if not explicitly set.
+ * - meterRegistry: An instance of `MeterRegistry` used for
+ * registering and managing metrics. Defaults to a `LoggingMeterRegistry` if not
+ * explicitly set.
+ *
+ *
+ * Lombok Annotations:
+ *
+ * - @Data: Generates getters, setters, `equals()`,
+ * `hashCode()`, and `toString()` methods automatically.
+ * - @AllArgsConstructor: Creates a constructor with all
+ * fields as parameters, allowing for easy instantiation of the class with all
+ * properties set.
+ * - @NoArgsConstructor: Provides a no-argument constructor
+ * for creating instances of the class without initializing the fields.
+ *
+ *
+ * Usage Example:
+ *
+ *
+ * {
+ * @code
+ * @Configuration
+ * @ConfigurationProperties(prefix = "monitoring")
+ * public class MonitoringConfig {
+ *
+ * private final MonitoringProperties monitoringProperties;
+ *
+ * @Autowired
+ * public MonitoringConfig(MonitoringProperties monitoringProperties) {
+ * this.monitoringProperties = monitoringProperties;
+ * }
+ *
+ * @PostConstruct
+ * public void init() {
+ * // Example of accessing properties
+ * System.out.println("Monitoring Enabled: " + monitoringProperties.isEnable());
+ * System.out.println("Meter Registry: " + monitoringProperties.getMeterRegistry());
+ * }
+ * }
+ * }
+ *
+ *
+ * Configuration Example:
+ *
+ * {@code
+ * # application.yml
+ * monitoring:
+ * isEnable: true
+ * meterRegistry: com.example.CustomMeterRegistry
+ * }
+ *
+ * Detailed Description:
+ *
+ *
+ * The `MonitoringProperties` class is used to configure monitoring settings for
+ * an application. The `isEnable` flag determines whether monitoring is active,
+ * while the `meterRegistry` attribute specifies the type of meter registry to
+ * be used for managing metrics.
+ *
+ *
+ *
+ * The default value for `isEnable` is `true`, meaning monitoring is enabled by
+ * default unless explicitly disabled.
+ *
+ *
+ *
+ * The `meterRegistry` is an instance of `MeterRegistry`, which is responsible
+ * for collecting and reporting metrics. The default value is an instance of
+ * `LoggingMeterRegistry`, which logs metrics to the console. You can replace
+ * this with a custom `MeterRegistry` implementation as needed.
+ *
+ */
@Data
@AllArgsConstructor
@NoArgsConstructor
diff --git a/src/main/java/io/hoangtien2k3/commons/filter/properties/PoolProperties.java b/src/main/java/io/hoangtien2k3/commons/filter/properties/PoolProperties.java
index f1fc15c..7b92b79 100644
--- a/src/main/java/io/hoangtien2k3/commons/filter/properties/PoolProperties.java
+++ b/src/main/java/io/hoangtien2k3/commons/filter/properties/PoolProperties.java
@@ -18,6 +18,96 @@
import lombok.Data;
import lombok.NoArgsConstructor;
+/**
+ * The `PoolProperties` class encapsulates configuration settings for a
+ * connection pool. It uses Lombok annotations to generate boilerplate code such
+ * as getters, setters, and constructors.
+ *
+ * Attributes:
+ *
+ * - maxSize: An integer representing the maximum number of
+ * connections that the pool can hold. Defaults to `2000` if not explicitly
+ * set.
+ * - maxPendingAcquire: An integer representing the maximum
+ * number of connections that can be pending acquisition from the pool. Defaults
+ * to `2000` if not explicitly set.
+ *
+ *
+ * Lombok Annotations:
+ *
+ * - @Data: Automatically generates getters, setters,
+ * `equals()`, `hashCode()`, and `toString()` methods.
+ * - @AllArgsConstructor: Creates a constructor with all
+ * fields as parameters, allowing for easy instantiation of the class with all
+ * properties set.
+ * - @NoArgsConstructor: Provides a no-argument constructor
+ * for creating instances of the class with default values.
+ *
+ *
+ * Usage Example:
+ *
+ *
+ * {
+ * @code
+ * @Configuration
+ * @ConfigurationProperties(prefix = "pool")
+ * public class PoolConfig {
+ *
+ * private final PoolProperties poolProperties;
+ *
+ * @Autowired
+ * public PoolConfig(PoolProperties poolProperties) {
+ * this.poolProperties = poolProperties;
+ * }
+ *
+ * @PostConstruct
+ * public void init() {
+ * // Example of accessing properties
+ * System.out.println("Max Pool Size: " + poolProperties.getMaxSize());
+ * System.out.println("Max Pending Acquire: " + poolProperties.getMaxPendingAcquire());
+ * }
+ * }
+ * }
+ *
+ *
+ * Configuration Example:
+ *
+ * {@code
+ * # application.yml
+ * pool:
+ * maxSize: 3000
+ * maxPendingAcquire: 5000
+ * }
+ *
+ * Detailed Description:
+ *
+ *
+ * The `PoolProperties` class is used to configure the parameters for a
+ * connection pool in an application. It allows you to specify the maximum size
+ * of the pool and the maximum number of connections that can be pending
+ * acquisition.
+ *
+ *
+ *
+ * The default value for `maxSize` is `2000`, which means the pool can hold up
+ * to 2000 connections. If you want to allow more or fewer connections, you can
+ * adjust this value.
+ *
+ *
+ *
+ * The `maxPendingAcquire` value is also set to `2000` by default. This property
+ * defines the maximum number of connections that can be in the process of being
+ * acquired from the pool. If the number of pending connections exceeds this
+ * limit, additional requests will have to wait until a connection becomes
+ * available.
+ *
+ *
+ *
+ * Both properties are customizable to fit the specific needs of your
+ * application's connection pool. Adjusting these values can help optimize
+ * performance and resource usage based on your application's requirements.
+ *
+ */
@Data
@AllArgsConstructor
@NoArgsConstructor
diff --git a/src/main/java/io/hoangtien2k3/commons/filter/properties/ProxyProperties.java b/src/main/java/io/hoangtien2k3/commons/filter/properties/ProxyProperties.java
index 7c0caf6..9753de8 100644
--- a/src/main/java/io/hoangtien2k3/commons/filter/properties/ProxyProperties.java
+++ b/src/main/java/io/hoangtien2k3/commons/filter/properties/ProxyProperties.java
@@ -18,6 +18,103 @@
import lombok.Data;
import lombok.NoArgsConstructor;
+/**
+ * The `ProxyProperties` class is used to configure proxy settings for an
+ * application. It employs Lombok annotations to automatically generate getters,
+ * setters, and constructors.
+ *
+ * Attributes:
+ *
+ * - enable: A boolean flag indicating whether proxy support
+ * is enabled. Defaults to `false` if not explicitly set.
+ * - httpHost: A string representing the host address for
+ * HTTP proxy configuration. This value should be set if an HTTP proxy is
+ * required.
+ * - httpPort: An integer specifying the port number for HTTP
+ * proxy configuration. This value should be set in conjunction with
+ * `httpHost`.
+ * - httpsHost: A string representing the host address for
+ * HTTPS proxy configuration. This value should be set if an HTTPS proxy is
+ * required.
+ * - httpsPort: An integer specifying the port number for
+ * HTTPS proxy configuration. This value should be set in conjunction with
+ * `httpsHost`.
+ *
+ *
+ * Lombok Annotations:
+ *
+ * - @Data: Automatically generates getters, setters,
+ * `equals()`, `hashCode()`, and `toString()` methods for the class.
+ * - @AllArgsConstructor: Creates a constructor with all
+ * fields as parameters, allowing for easy instantiation with all properties
+ * set.
+ * - @NoArgsConstructor: Provides a no-argument constructor
+ * for creating instances with default values.
+ *
+ *
+ * Usage Example:
+ *
+ *
+ * {
+ * @code
+ * @Configuration
+ * @ConfigurationProperties(prefix = "proxy")
+ * public class ProxyConfig {
+ *
+ * private final ProxyProperties proxyProperties;
+ *
+ * @Autowired
+ * public ProxyConfig(ProxyProperties proxyProperties) {
+ * this.proxyProperties = proxyProperties;
+ * }
+ *
+ * @PostConstruct
+ * public void init() {
+ * if (proxyProperties.isEnable()) {
+ * // Example of accessing and using proxy settings
+ * System.out.println("HTTP Proxy Host: " + proxyProperties.getHttpHost());
+ * System.out.println("HTTP Proxy Port: " + proxyProperties.getHttpPort());
+ * System.out.println("HTTPS Proxy Host: " + proxyProperties.getHttpsHost());
+ * System.out.println("HTTPS Proxy Port: " + proxyProperties.getHttpsPort());
+ * }
+ * }
+ * }
+ * }
+ *
+ *
+ * Configuration Example:
+ *
+ * {@code
+ * # application.yml
+ * proxy:
+ * enable: true
+ * httpHost: "http-proxy.example.com"
+ * httpPort: 8080
+ * httpsHost: "https-proxy.example.com"
+ * httpsPort: 8443
+ * }
+ *
+ * Detailed Description:
+ *
+ *
+ * The `ProxyProperties` class provides a way to configure proxy settings for
+ * your application, including both HTTP and HTTPS proxies. It is particularly
+ * useful when your application needs to communicate through a proxy server.
+ *
+ *
+ *
+ * By default, proxy support is disabled (i.e., `enable` is `false`). To use a
+ * proxy, you need to set the `enable` flag to `true` and provide the necessary
+ * `httpHost`, `httpPort`, `httpsHost`, and `httpsPort` values.
+ *
+ *
+ *
+ * The `httpHost` and `httpPort` define the proxy settings for HTTP connections,
+ * while the `httpsHost` and `httpsPort` define the settings for HTTPS
+ * connections. Make sure to configure these values appropriately based on your
+ * network infrastructure and proxy server settings.
+ *
+ */
@Data
@AllArgsConstructor
@NoArgsConstructor
diff --git a/src/main/java/io/hoangtien2k3/commons/filter/properties/RetryProperties.java b/src/main/java/io/hoangtien2k3/commons/filter/properties/RetryProperties.java
index ac4fb2f..abe8c2c 100644
--- a/src/main/java/io/hoangtien2k3/commons/filter/properties/RetryProperties.java
+++ b/src/main/java/io/hoangtien2k3/commons/filter/properties/RetryProperties.java
@@ -22,6 +22,112 @@
import lombok.NoArgsConstructor;
import org.springframework.http.HttpMethod;
+/**
+ * The `RetryProperties` class is used to configure retry behavior for HTTP
+ * requests within an application. It leverages Lombok annotations to
+ * automatically generate getters, setters, and constructors.
+ *
+ * Attributes:
+ *
+ * - isEnable: A boolean flag indicating whether retry
+ * functionality is enabled. Defaults to `true` if not explicitly set.
+ * - count: An integer specifying the number of retry
+ * attempts. Defaults to `2` if not explicitly set.
+ * - methods: A list of HTTP methods for which retry should
+ * be applied. By default, it includes `HttpMethod.GET`, `HttpMethod.PUT`, and
+ * `HttpMethod.DELETE`.
+ * - exceptions: A list of exception classes that should
+ * trigger a retry. Defaults to `ConnectTimeoutException` and
+ * `ReadTimeoutException`.
+ *
+ *
+ * Lombok Annotations:
+ *
+ * - @Data: Automatically generates getters, setters,
+ * `equals()`, `hashCode()`, and `toString()` methods for the class.
+ * - @AllArgsConstructor: Creates a constructor with all
+ * fields as parameters, allowing for easy instantiation with all properties
+ * set.
+ * - @NoArgsConstructor: Provides a no-argument constructor
+ * for creating instances with default values.
+ *
+ *
+ * Usage Example:
+ *
+ *
+ * {
+ * @code
+ * @Configuration
+ * @ConfigurationProperties(prefix = "retry")
+ * public class RetryConfig {
+ *
+ * private final RetryProperties retryProperties;
+ *
+ * @Autowired
+ * public RetryConfig(RetryProperties retryProperties) {
+ * this.retryProperties = retryProperties;
+ * }
+ *
+ * @Bean
+ * public WebClient.Builder webClientBuilder() {
+ * return WebClient.builder().filter((request, next) -> {
+ * if (retryProperties.isEnable()) {
+ * return next.exchange(request)
+ * .retryWhen(Retry.backoff(retryProperties.getCount(), Duration.ofSeconds(1))
+ * .filter(throwable -> retryProperties.getExceptions().stream()
+ * .anyMatch(exceptionClass -> exceptionClass.isInstance(throwable))));
+ * }
+ * return next.exchange(request);
+ * });
+ * }
+ * }
+ * }
+ *
+ *
+ * Configuration Example:
+ *
+ * {@code
+ * # application.yml
+ * retry:
+ * isEnable: true
+ * count: 3
+ * methods:
+ * - GET
+ * - POST
+ * exceptions:
+ * - java.net.ConnectException
+ * - java.net.SocketTimeoutException
+ * }
+ *
+ * Detailed Description:
+ *
+ *
+ * The `RetryProperties` class provides configuration options for retrying HTTP
+ * requests when certain conditions are met. The `isEnable` flag determines
+ * whether the retry logic is active. The `count` attribute specifies how many
+ * times the request should be retried if a retryable exception occurs.
+ *
+ *
+ *
+ * The `methods` list specifies which HTTP methods the retry logic should apply
+ * to. By default, it includes `GET`, `PUT`, and `DELETE` requests, but this can
+ * be customized based on the application's requirements.
+ *
+ *
+ *
+ * The `exceptions` list includes exception classes that trigger a retry.
+ * Commonly used exceptions like `ConnectTimeoutException` and
+ * `ReadTimeoutException` are included by default, but this can be customized to
+ * handle other specific exceptions as needed.
+ *
+ *
+ *
+ * Using this configuration allows applications to handle transient errors and
+ * improve resilience by automatically retrying failed requests, which can be
+ * particularly useful in distributed systems or when dealing with unreliable
+ * network conditions.
+ *
+ */
@Data
@AllArgsConstructor
@NoArgsConstructor
diff --git a/src/main/java/io/hoangtien2k3/commons/filter/properties/TimeoutProperties.java b/src/main/java/io/hoangtien2k3/commons/filter/properties/TimeoutProperties.java
index 0bf972b..c2bba34 100644
--- a/src/main/java/io/hoangtien2k3/commons/filter/properties/TimeoutProperties.java
+++ b/src/main/java/io/hoangtien2k3/commons/filter/properties/TimeoutProperties.java
@@ -18,6 +18,87 @@
import lombok.Data;
import lombok.NoArgsConstructor;
+/**
+ * The `TimeoutProperties` class is used to configure timeout settings for HTTP
+ * requests within an application. It leverages Lombok annotations to
+ * automatically generate getters, setters, and constructors.
+ *
+ * Attributes:
+ *
+ * - read: An integer specifying the read timeout in
+ * milliseconds. The default value is `180000` milliseconds (3 minutes). This
+ * timeout controls how long the application will wait for data to be read from
+ * the server before timing out.
+ * - connection: An integer specifying the connection timeout
+ * in milliseconds. The default value is `500` milliseconds (0.5 seconds). This
+ * timeout controls how long the application will wait to establish a connection
+ * to the server before timing out.
+ *
+ *
+ * Lombok Annotations:
+ *
+ * - @Data: Automatically generates getters, setters,
+ * `equals()`, `hashCode()`, and `toString()` methods for the class.
+ * - @AllArgsConstructor: Creates a constructor with all
+ * fields as parameters, allowing for easy instantiation with all properties
+ * set.
+ * - @NoArgsConstructor: Provides a no-argument constructor
+ * for creating instances with default values.
+ *
+ *
+ * Usage Example:
+ *
+ *
+ * {
+ * @code
+ * @Configuration
+ * @ConfigurationProperties(prefix = "timeout")
+ * public class TimeoutConfig {
+ *
+ * private final TimeoutProperties timeoutProperties;
+ *
+ * @Autowired
+ * public TimeoutConfig(TimeoutProperties timeoutProperties) {
+ * this.timeoutProperties = timeoutProperties;
+ * }
+ *
+ * @Bean
+ * public WebClient.Builder webClientBuilder() {
+ * return WebClient.builder()
+ * .clientConnector(new ReactorClientHttpConnector(HttpClient.create()
+ * .option(ChannelOption.CONNECT_TIMEOUT_MILLIS, timeoutProperties.getConnection())
+ * .responseTimeout(Duration.ofMillis(timeoutProperties.getRead()))));
+ * }
+ * }
+ * }
+ *
+ *
+ * Configuration Example:
+ *
+ * {@code
+ * # application.yml
+ * timeout:
+ * read: 180000
+ * connection: 500
+ * }
+ *
+ * Detailed Description:
+ *
+ *
+ * The `TimeoutProperties` class provides configuration options for setting
+ * timeout values for HTTP requests. The `read` attribute specifies how long the
+ * client will wait for data to be read from the server before giving up. The
+ * `connection` attribute specifies how long the client will wait to establish a
+ * connection to the server.
+ *
+ *
+ *
+ * Using this configuration allows you to fine-tune how your application handles
+ * network delays and connection issues. By setting appropriate timeout values,
+ * you can improve the responsiveness of your application and handle network
+ * conditions more effectively.
+ *
+ */
@Data
@AllArgsConstructor
@NoArgsConstructor
diff --git a/src/main/java/io/hoangtien2k3/commons/filter/webclient/WebClientLoggingFilter.java b/src/main/java/io/hoangtien2k3/commons/filter/webclient/WebClientLoggingFilter.java
index adbe3e8..da45243 100644
--- a/src/main/java/io/hoangtien2k3/commons/filter/webclient/WebClientLoggingFilter.java
+++ b/src/main/java/io/hoangtien2k3/commons/filter/webclient/WebClientLoggingFilter.java
@@ -23,6 +23,105 @@
import org.springframework.web.reactive.function.client.ExchangeFunction;
import reactor.core.publisher.Mono;
+/**
+ * The {@code WebClientLoggingFilter} class is an implementation of
+ * {@link ExchangeFilterFunction} used to log HTTP request and response details
+ * when using Spring's {@link}. This filter logs information about API calls,
+ * including headers and bodies, with support for obfuscating sensitive header
+ * values. It utilizes Lombok annotations for logging and constructor injection.
+ *
+ * Attributes:
+ *
+ * - OBFUSCATE_HEADER: A constant string used to replace
+ * sensitive header values in logs. The default value is "xxxxx".
+ * - obfuscateHeader: A list of header names that should be
+ * obfuscated in the logs. This list is provided during the instantiation of the
+ * filter.
+ *
+ *
+ * Methods:
+ *
+ * - filter: The core method of the
+ * {@code WebClientLoggingFilter} class. It intercepts the request and response,
+ * logs request details, and then passes the request to the next
+ * {@link ExchangeFunction} in the chain. After receiving the response, it logs
+ * the response details before returning the {@link ClientResponse} to the
+ * caller.
+ *
+ * - Parameters:
+ *
+ * - request: The original {@link ClientRequest} object
+ * representing the HTTP request.
+ * - next: The next {@link ExchangeFunction} in the chain
+ * that will handle the request after this filter.
+ *
+ *
+ * - Returns: A {@link Mono} of {@link ClientResponse}
+ * representing the response returned by the next filter in the chain.
+ *
+ *
+ *
+ *
+ * Logging:
+ *
+ * - Request Logging: Logs the HTTP method and URL of the
+ * request. If the request has a body, it is logged as well. Headers are logged
+ * in debug mode with sensitive values obfuscated if their names match any in
+ * the {@code obfuscateHeader} list.
+ * - Response Logging: Logs response headers in debug mode,
+ * with sensitive values obfuscated if necessary.
+ *
+ *
+ * Usage Example:
+ *
+ *
+ * {
+ * @code
+ * @Configuration
+ * public class WebClientConfig {
+ *
+ * @Bean
+ * public WebClient.Builder webClientBuilder() {
+ * List obfuscateHeaders = List.of("Authorization", "Cookie");
+ * return WebClient.builder().filter(new WebClientLoggingFilter(obfuscateHeaders));
+ * }
+ * }
+ * }
+ *
+ *
+ * Configuration Example:
+ *
+ * {@code
+ * # application.yml
+ * webclient:
+ * logging:
+ * obfuscate-headers:
+ * - Authorization
+ * - Cookie
+ * }
+ *
+ * Detailed Description:
+ *
+ * The {@code WebClientLoggingFilter} class provides detailed logging for HTTP
+ * requests and responses. It is particularly useful for debugging and
+ * monitoring API interactions. The filter logs important request and response
+ * details, including headers and bodies (if present). Sensitive header values,
+ * such as authorization tokens or cookies, can be obfuscated in the logs by
+ * specifying their names in the {@code obfuscateHeader} list.
+ *
+ *
+ *
+ * Logging levels are controlled by the {@code log} object. Request and response
+ * bodies are logged if their length is greater than zero. Header names and
+ * values are logged at the debug level, with sensitive values replaced by a
+ * placeholder string.
+ *
+ *
+ *
+ * This filter can be added to a {@link} configuration to automatically apply
+ * logging to all requests made through that client.
+ *
+ */
@Slf4j
@RequiredArgsConstructor
public class WebClientLoggingFilter implements ExchangeFilterFunction {
diff --git a/src/main/java/io/hoangtien2k3/commons/filter/webclient/WebClientMonitoringFilter.java b/src/main/java/io/hoangtien2k3/commons/filter/webclient/WebClientMonitoringFilter.java
index 43b8c0f..0fb39a9 100644
--- a/src/main/java/io/hoangtien2k3/commons/filter/webclient/WebClientMonitoringFilter.java
+++ b/src/main/java/io/hoangtien2k3/commons/filter/webclient/WebClientMonitoringFilter.java
@@ -24,6 +24,107 @@
import org.springframework.web.reactive.function.client.ExchangeFunction;
import reactor.core.publisher.Mono;
+/**
+ * The `WebClientMonitoringFilter` class implements `ExchangeFilterFunction` to
+ * monitor and record metrics for HTTP requests made using Spring's `WebClient`.
+ * It utilizes Micrometer's `MeterRegistry` to collect and record metrics such
+ * as response time.
+ *
+ * Attributes:
+ *
+ * - METRICS_WEBCLIENT_START_TIME: A constant string used as
+ * a key to store the start time of the HTTP request in the context.
+ * - meterRegistry: An instance of `MeterRegistry` used to
+ * register and publish metrics. It is provided during the instantiation of the
+ * filter.
+ * - tagsProvider: (Commented out) A
+ * `WebClientExchangeTagsProvider` for generating tags for the metrics. It is
+ * currently not used but can be configured for more detailed metrics.
+ *
+ *
+ * Methods:
+ *
+ * - filter: This method is invoked for every HTTP request
+ * handled by the `WebClient`. It:
+ *
+ * - Records the start time of the request in the context.
+ * - Registers a `Timer` metric with `MeterRegistry` to measure the duration
+ * of the request and response.
+ * - Logs the request duration in seconds, including percentiles for response
+ * time.
+ *
+ *
+ * - Parameters:
+ *
+ * - clientRequest: The `ClientRequest` object representing
+ * the HTTP request.
+ * - exchangeFunction: The `ExchangeFunction` that processes
+ * the HTTP request and returns a `ClientResponse`.
+ *
+ *
+ * - Returns: A `Mono` representing the
+ * response from the exchange function.
+ *
+ *
+ *
+ *
+ * Logging:
+ *
+ * - Monitoring Logging: Logs the duration of the API call in
+ * seconds. The duration is calculated based on the time elapsed between the
+ * start and end of the request.
+ *
+ *
+ * Usage Example:
+ *
+ *
+ * {
+ * @code
+ * @Configuration
+ * public class WebClientConfig {
+ *
+ * @Bean
+ * public WebClient.Builder webClientBuilder(MeterRegistry meterRegistry) {
+ * return WebClient.builder().filter(new WebClientMonitoringFilter(meterRegistry));
+ * }
+ * }
+ * }
+ *
+ *
+ * Configuration Example:
+ *
+ * {@code
+ * # application.yml
+ * metrics:
+ * webclient:
+ * enabled: true
+ * }
+ *
+ * Detailed Description:
+ *
+ *
+ * The `WebClientMonitoringFilter` class provides monitoring capabilities for
+ * HTTP requests made through Spring's `WebClient`. It is designed to track and
+ * record metrics such as response times to help in performance monitoring and
+ * analysis. The filter uses Micrometer's `MeterRegistry` to register and
+ * publish these metrics, allowing you to monitor the duration of HTTP requests.
+ *
+ *
+ *
+ * When a request is processed, the filter captures the start time and records
+ * the duration of the request once the response is received. The metrics are
+ * published with percentiles to provide insight into response time
+ * distributions. You can also log the duration of requests for further
+ * analysis.
+ *
+ *
+ *
+ * To use this filter, configure it as part of your `WebClient` setup and
+ * provide a `MeterRegistry` bean to register the metrics. This filter is useful
+ * in performance monitoring scenarios, where understanding request durations
+ * and response times is crucial for optimizing application performance.
+ *
+ */
@Slf4j
@Data
@RequiredArgsConstructor
diff --git a/src/main/java/io/hoangtien2k3/commons/filter/webclient/WebClientRetryHandler.java b/src/main/java/io/hoangtien2k3/commons/filter/webclient/WebClientRetryHandler.java
index 1e33cfe..caa6d6e 100644
--- a/src/main/java/io/hoangtien2k3/commons/filter/webclient/WebClientRetryHandler.java
+++ b/src/main/java/io/hoangtien2k3/commons/filter/webclient/WebClientRetryHandler.java
@@ -25,6 +25,111 @@
import reactor.core.publisher.Mono;
import reactor.util.retry.Retry;
+/**
+ * The `WebClientRetryHandler` class implements `ExchangeFilterFunction` to
+ * provide retry functionality for HTTP requests made using Spring's
+ * `WebClient`. It uses a configurable retry strategy to handle transient
+ * failures and retry requests based on specific conditions.
+ *
+ * Attributes:
+ *
+ * - properties: An instance of `RetryProperties` used to
+ * configure retry behavior, such as the number of retry attempts, HTTP methods
+ * to apply retries, and exception types that should trigger retries.
+ *
+ *
+ * Methods:
+ *
+ * - filter: This method is invoked for every HTTP request
+ * handled by the `WebClient`. It:
+ *
+ * - Creates a `Retry` instance with the configured properties, including the
+ * maximum number of retry attempts and the conditions under which retries
+ * should be performed.
+ * - Logs a warning message each time a retry is attempted, including the
+ * number of retries and the cause of the failure.
+ * - Throws an exception if all retry attempts are exhausted.
+ *
+ *
+ * - Parameters:
+ *
+ * - request: The `ClientRequest` object representing the
+ * HTTP request.
+ * - next: The `ExchangeFunction` that processes the HTTP
+ * request and returns a `ClientResponse`.
+ *
+ *
+ * - Returns: A `Mono` representing the
+ * response from the exchange function, which includes retry handling.
+ *
+ *
+ *
+ *
+ * Logging:
+ *
+ * - Retry Logging: Logs a warning message each time a retry
+ * is performed, including the retry count and the cause of the failure. This
+ * helps in monitoring and debugging retry attempts.
+ *
+ *
+ * Usage Example:
+ *
+ *
+ * {
+ * @code
+ * @Configuration
+ * public class WebClientConfig {
+ *
+ * @Bean
+ * public WebClient.Builder webClientBuilder(RetryProperties retryProperties) {
+ * return WebClient.builder().filter(new WebClientRetryHandler(retryProperties));
+ * }
+ * }
+ * }
+ *
+ *
+ * Configuration Example:
+ *
+ * {@code
+ * # application.yml
+ * retry:
+ * enable: true
+ * count: 3
+ * methods:
+ * - GET
+ * - PUT
+ * exceptions:
+ * - java.net.ConnectException
+ * - java.net.SocketTimeoutException
+ * }
+ *
+ * Detailed Description:
+ *
+ *
+ * The `WebClientRetryHandler` class provides a way to handle transient errors
+ * and retry HTTP requests using Spring's `WebClient`. It allows you to
+ * configure retry behavior based on the number of retry attempts, the HTTP
+ * methods that should be retried, and the types of exceptions that should
+ * trigger retries. The retry logic is built using Reactor's retry
+ * functionality, which allows for configurable retry policies and handling of
+ * transient failures.
+ *
+ *
+ *
+ * When a request fails, the filter will attempt to retry the request based on
+ * the configured properties. The retry attempts are logged for monitoring
+ * purposes, and an exception is thrown if all retry attempts are exhausted.
+ * This functionality is useful in scenarios where transient errors are expected
+ * and retrying the request can lead to successful outcomes.
+ *
+ *
+ *
+ * To use this filter, configure it as part of your `WebClient` setup and
+ * provide a `RetryProperties` bean to specify the retry behavior. This filter
+ * is helpful for ensuring reliability in HTTP communications by automatically
+ * retrying requests in the event of transient failures.
+ *
+ */
@Slf4j
@RequiredArgsConstructor
public class WebClientRetryHandler implements ExchangeFilterFunction {
diff --git a/src/main/java/io/hoangtien2k3/commons/model/SagaProcess.java b/src/main/java/io/hoangtien2k3/commons/model/SagaProcess.java
index dd2413c..bdb2a29 100644
--- a/src/main/java/io/hoangtien2k3/commons/model/SagaProcess.java
+++ b/src/main/java/io/hoangtien2k3/commons/model/SagaProcess.java
@@ -24,13 +24,123 @@
import reactor.core.publisher.Mono;
import reactor.core.scheduler.Schedulers;
+/**
+ * The `SagaProcess` class represents an abstract base class for implementing a
+ * saga pattern. It defines the structure and behavior of a saga process, which
+ * consists of a series of steps that need to be executed and potentially rolled
+ * back in case of errors.
+ *
+ * Attributes:
+ *
+ * - executedStep: A `List` of `SagaStep` objects that keeps
+ * track of the steps that have been executed so far. It is used for rollback
+ * purposes in case of failures.
+ *
+ *
+ * Abstract Methods:
+ *
+ * - getSteps(): This abstract method should be implemented
+ * by subclasses to return the list of `SagaStep` objects that define the steps
+ * of the saga process.
+ *
+ *
+ * Methods:
+ *
+ * - execute(): Executes the steps of the saga process. It
+ * processes each step in sequence and handles the results. If any step fails,
+ * the process triggers a rollback of the previously executed steps. The method:
+ *
+ * - Logs the start of the execution.
+ * - Uses `Flux.fromIterable(getSteps())` to create a stream of steps.
+ * - Applies `flatMap(SagaStep::execute)` to execute each step
+ * asynchronously.
+ * - Handles the result of each step using `handle()` to either continue or
+ * trigger an error.
+ * - Subscribes on a bounded elastic scheduler to ensure that the operations
+ * are performed in a dedicated thread pool.
+ * - On error, calls the `revert()` method to roll back the changes made by
+ * the previously executed steps.
+ *
+ *
+ * - revert(): Rolls back the previously executed steps in
+ * reverse order. It is called when an error occurs during the execution of the
+ * saga process. The method:
+ *
+ * - Logs the start of the rollback.
+ * - Reverses the order of the steps using
+ * `Collections.reverse(getSteps())`.
+ * - Filters out the steps that have not been completed successfully and
+ * applies `flatMap(SagaStep::revert)` to revert each step asynchronously.
+ *
+ *
+ *
+ *
+ * Usage Example:
+ *
+ * {@code
+ * public class MySagaProcess extends SagaProcess {
+ * @Override
+ * public List getSteps() {
+ * return List.of(new Step1(), new Step2(), new Step3());
+ * }
+ * }
+ *
+ * // Create an instance of MySagaProcess
+ * SagaProcess sagaProcess = new MySagaProcess();
+ *
+ * // Execute the saga process
+ * sagaProcess.execute().doOnSuccess(result -> System.out.println("Saga executed successfully"))
+ * .doOnError(ex -> System.out.println("Saga execution failed: " + ex.getMessage())).subscribe();
+ * }
+ *
+ * Detailed Description:
+ *
+ *
+ * The `SagaProcess` class is designed to manage complex transactional processes
+ * using the saga pattern. It provides a way to execute a series of steps while
+ * ensuring that if any step fails, the previously executed steps are rolled
+ * back to maintain consistency. The class uses reactive programming constructs
+ * from Project Reactor to handle asynchronous execution and rollback.
+ *
+ *
+ *
+ * Subclasses must implement the `getSteps()` method to provide the specific
+ * steps of the saga process. The `execute()` method orchestrates the execution
+ * of these steps and manages rollback in case of errors. The `revert()` method
+ * ensures that any changes made by the executed steps are undone in reverse
+ * order.
+ *
+ *
+ *
+ * This class is useful in scenarios where long-running transactions or complex
+ * business processes need to be managed, and where rollback capabilities are
+ * required to handle failures gracefully.
+ *
+ */
@Slf4j
public abstract class SagaProcess {
+ /**
+ * Abstract method that should be implemented by subclasses to return the list
+ * of `SagaStep` objects that define the steps of the saga process.
+ *
+ * @return A list of `SagaStep` objects.
+ */
public abstract List getSteps();
+ /**
+ * A `List` of `SagaStep` objects that keeps track of the steps that have been
+ * executed so far. This is used for rollback purposes in case of failures.
+ */
protected final List executedStep = new LinkedList<>();
+ /**
+ * Executes the steps of the saga process. It processes each step in sequence
+ * and handles the results. If any step fails, the process triggers a rollback
+ * of the previously executed steps.
+ *
+ * @return A `Flux` indicating the result of the saga execution.
+ */
public Flux execute() {
log.info("==================Start execute================");
return Flux.fromIterable(getSteps())
@@ -47,6 +157,12 @@ public Flux execute() {
.onErrorResume(ex -> revert().then(Mono.error(ex)));
}
+ /**
+ * Rolls back the previously executed steps in reverse order. It is called when
+ * an error occurs during the execution of the saga process.
+ *
+ * @return A `Flux` indicating the result of the rollback.
+ */
public Flux revert() {
log.info("==================Start rollback================");
Collections.reverse(getSteps());
diff --git a/src/main/java/io/hoangtien2k3/commons/model/SagaStep.java b/src/main/java/io/hoangtien2k3/commons/model/SagaStep.java
index 77c177f..2faabc9 100644
--- a/src/main/java/io/hoangtien2k3/commons/model/SagaStep.java
+++ b/src/main/java/io/hoangtien2k3/commons/model/SagaStep.java
@@ -16,11 +16,130 @@
import reactor.core.publisher.Mono;
+/**
+ * The {@code SagaStep} interface defines a single step in a saga process. Each
+ * step represents an individual operation that can be executed, and, if
+ * necessary, rolled back in case of failure. The interface provides methods for
+ * executing, reverting, and checking the completion status of the step.
+ *
+ * Methods:
+ *
+ * - complete(): Checks whether the step has been completed
+ * successfully. This is used in the rollback process to determine which steps
+ * need to be reverted.
+ * - execute(): Executes the step and returns a
+ * {@link Mono}<{@link StepResult}> indicating the result of the
+ * execution. This method is used in the saga process to perform the step's
+ * operation.
+ * - revert(): Reverts the step's changes if the execution
+ * fails. It returns a {@link Mono}<{@link Boolean}> indicating whether
+ * the revert operation was successful.
+ *
+ *
+ * Methods Description:
+ *
+ * boolean complete()
+ *
+ * This method is used to check whether the step has been completed
+ * successfully. It returns {@code true} if the step is complete, and
+ * {@code false} otherwise. This information is crucial for determining which
+ * steps need to be rolled back in case of an error.
+ *
+ *
+ * Mono<StepResult> execute()
+ *
+ * This method is responsible for executing the step's operation. It returns a
+ * {@link Mono}<{@link StepResult}>, where {@link StepResult} encapsulates
+ * the outcome of the execution. The {@link StepResult} typically contains
+ * information about whether the execution was successful and any relevant
+ * messages. This method is called during the saga process to perform the step's
+ * operation.
+ *
+ *
+ * Mono<Boolean> revert()
+ *
+ * This method is used to revert the step's changes if the execution fails. It
+ * returns a {@link Mono}<{@link Boolean}>, where {@code true} indicates
+ * that the revert operation was successful and {@code false} otherwise. This
+ * method is called during the rollback process to undo the changes made by the
+ * step if necessary.
+ *
+ *
+ * Usage Example:
+ *
+ *
+ * {
+ * @code
+ * public class MySagaStep implements SagaStep {
+ *
+ * @Override
+ * public boolean complete() {
+ * // Check if the step has been completed
+ * return true; // or false based on the actual completion status
+ * }
+ *
+ * @Override
+ * public Mono execute() {
+ * // Perform the step's operation and return the result
+ * return Mono.just(new StepResult(true, "Operation succeeded"));
+ * }
+ *
+ * @Override
+ * public Mono revert() {
+ * // Revert the step's changes and return the result
+ * return Mono.just(true); // or false based on the actual revert outcome
+ * }
+ * }
+ * // Create an instance of MySagaStep
+ * SagaStep sagaStep = new MySagaStep();
+ * // Execute the step
+ * sagaStep.execute().doOnNext(result -> System.out.println("Step executed successfully: " + result))
+ * .doOnError(ex -> System.out.println("Step execution failed: " + ex.getMessage())).subscribe();
+ * // Revert the step
+ * sagaStep.revert().doOnNext(success -> System.out.println("Step reverted successfully: " + success))
+ * .doOnError(ex -> System.out.println("Step revert failed: " + ex.getMessage())).subscribe();
+ * }
+ *
+ *
+ * Detailed Description:
+ *
+ *
+ * The {@code SagaStep} interface is a fundamental component in implementing the
+ * saga pattern. It defines the operations that can be performed as part of a
+ * saga process, including executing the step, checking its completion status,
+ * and reverting its changes if needed. Each step in the saga must implement
+ * this interface to be integrated into the saga process.
+ *
+ *
+ *
+ * By implementing the {@code SagaStep} interface, you can define specific
+ * behaviors for each step in your saga, handle successful execution, and manage
+ * rollback scenarios. This interface provides a structured way to manage
+ * complex transactional processes and ensure consistency in case of failures.
+ *
+ */
public interface SagaStep {
+ /**
+ * Checks whether the step has been completed successfully.
+ *
+ * @return {@code true} if the step is complete, {@code false} otherwise.
+ */
boolean complete();
+ /**
+ * Executes the step's operation and returns a {@link Mono} containing the
+ * result.
+ *
+ * @return A {@link Mono} containing the outcome of the execution.
+ */
Mono execute();
+ /**
+ * Reverts the step's changes if the execution fails.
+ *
+ * @return A {@link Mono}<{@link Boolean}> indicating whether the revert
+ * operation was successful.
+ */
Mono revert();
}
diff --git a/src/main/java/io/hoangtien2k3/commons/model/StepResult.java b/src/main/java/io/hoangtien2k3/commons/model/StepResult.java
index a8e7844..aec234a 100644
--- a/src/main/java/io/hoangtien2k3/commons/model/StepResult.java
+++ b/src/main/java/io/hoangtien2k3/commons/model/StepResult.java
@@ -16,20 +16,102 @@
import lombok.Getter;
+/**
+ * The `StepResult` class represents the result of executing a step in a saga
+ * process. It encapsulates the outcome of the step execution, including whether
+ * it was successful and any associated message.
+ *
+ * Fields:
+ *
+ * - success: A boolean indicating whether the step execution
+ * was successful. `true` if the execution was successful, `false`
+ * otherwise.
+ * - message: A string containing any message associated with
+ * the result. This is typically used to provide additional information or error
+ * messages when the step fails.
+ *
+ *
+ * Constructors:
+ *
+ * The constructor is private and only accessible through the static factory
+ * methods. This design ensures that instances of `StepResult` are created with
+ * specific success and failure states.
+ *
+ *
+ * Static Methods:
+ *
+ * - success(): Creates a `StepResult` instance representing
+ * a successful execution. The message will be `null`.
+ * - failure(String message): Creates a `StepResult` instance
+ * representing a failed execution. The provided message will be used to
+ * describe the failure.
+ *
+ *
+ * Usage Example:
+ *
+ * {@code
+ * // Creating a successful result
+ * StepResult successResult = StepResult.success();
+ *
+ * // Creating a failure result with a message
+ * StepResult failureResult = StepResult.failure("An error occurred while executing the step.");
+ *
+ * // Checking the result
+ * if (successResult.isSuccess()) {
+ * System.out.println("Step executed successfully.");
+ * } else {
+ * System.out.println("Step failed: " + failureResult.getMessage());
+ * }
+ * }
+ *
+ * Detailed Description:
+ *
+ *
+ * The `StepResult` class is used to encapsulate the result of executing a step
+ * in a saga process. It provides a clear and structured way to represent
+ * whether the execution was successful or failed, along with an optional
+ * message that describes the outcome. This is useful for handling success and
+ * failure scenarios in the saga process and ensuring that appropriate actions
+ * are taken based on the result of each step.
+ *
+ */
@Getter
public class StepResult {
private final boolean success;
private final String message;
+ /**
+ * Private constructor to create an instance of `StepResult`.
+ *
+ * @param success
+ * Indicates whether the step execution was successful.
+ * @param message
+ * A message associated with the result, or `null` if there is no
+ * message.
+ */
private StepResult(boolean success, String message) {
this.success = success;
this.message = message;
}
+ /**
+ * Creates a `StepResult` instance representing a successful execution.
+ *
+ * @return A `StepResult` instance with `success` set to `true` and `message`
+ * set to `null`.
+ */
public static StepResult success() {
return new StepResult(true, null);
}
+ /**
+ * Creates a `StepResult` instance representing a failed execution.
+ *
+ * @param message
+ * A message describing the failure.
+ * @return A `StepResult` instance with `success` set to `false` and the
+ * provided `message`.
+ */
public static StepResult failure(String message) {
return new StepResult(false, message);
}
diff --git a/src/main/java/io/hoangtien2k3/commons/model/TokenUser.java b/src/main/java/io/hoangtien2k3/commons/model/TokenUser.java
index 42370d5..aef2dbe 100644
--- a/src/main/java/io/hoangtien2k3/commons/model/TokenUser.java
+++ b/src/main/java/io/hoangtien2k3/commons/model/TokenUser.java
@@ -21,6 +21,75 @@
import lombok.Data;
import lombok.NoArgsConstructor;
+/**
+ * The `TokenUser` class represents a user token with various properties related
+ * to user identity and organization. It is used to encapsulate user information
+ * typically obtained from an authentication system or token service.
+ *
+ * Annotations:
+ *
+ * - @JsonIgnoreProperties: Specifies that any properties not
+ * bound to this instance are ignored during deserialization. This helps handle
+ * cases where the JSON data contains extra properties not defined in the
+ * `TokenUser` class.
+ * - @Data: Lombok annotation that generates getters,
+ * setters, equals, hashCode, and toString methods, as well as a constructor
+ * with all arguments and a no-args constructor.
+ * - @AllArgsConstructor: Lombok annotation that generates a
+ * constructor with all fields as arguments.
+ * - @NoArgsConstructor: Lombok annotation that generates a
+ * no-arguments constructor.
+ * - @Builder: Lombok annotation that generates a builder
+ * pattern for the class, allowing fluent and immutable object creation.
+ *
+ *
+ * Fields:
+ *
+ * - id: A unique identifier for the user.
+ * - name: The full name of the user.
+ * - username: The username of the user, typically used for
+ * login.
+ * - email: The email address of the user.
+ * - individualId: An identifier for the individual
+ * associated with the user. Annotated with @JsonProperty("individual_id") to
+ * map the JSON property "individual_id" to this field.
+ * - organizationId: An identifier for the organization
+ * associated with the user.
+ *
+ *
+ * Usage Example:
+ *
+ * {@code
+ * // Creating a TokenUser instance using the builder pattern
+ * TokenUser user = TokenUser.builder().id("12345").name("Hoang Tien").username("hoangtien2k3")
+ * .email("hoangtien2k3@gmail.com").individualId("ind-67890").organizationId("org-123").build();
+ *
+ * // Accessing properties
+ * String userId = user.getId();
+ * String userEmail = user.getEmail();
+ *
+ * // Displaying user information
+ * System.out.println("User Name: " + user.getName());
+ * System.out.println("User Email: " + user.getEmail());
+ * }
+ *
+ * Detailed Description:
+ *
+ *
+ * The `TokenUser` class serves as a data model for holding user information
+ * extracted from authentication tokens or identity services. It includes fields
+ * for user identification, personal details, and organizational information.
+ * The class is annotated with Lombok annotations to simplify the creation and
+ * manipulation of `TokenUser` instances.
+ *
+ *
+ *
+ * With the `@JsonIgnoreProperties` annotation, the class can handle extra
+ * properties in JSON data gracefully. The `@JsonProperty("individual_id")`
+ * annotation ensures that the JSON field "individual_id" is correctly mapped to
+ * the `individualId` field in the class.
+ *
+ */
@JsonIgnoreProperties
@Data
@AllArgsConstructor
diff --git a/src/main/java/io/hoangtien2k3/commons/model/UserDTO.java b/src/main/java/io/hoangtien2k3/commons/model/UserDTO.java
index 3aa5980..3f4d5a9 100644
--- a/src/main/java/io/hoangtien2k3/commons/model/UserDTO.java
+++ b/src/main/java/io/hoangtien2k3/commons/model/UserDTO.java
@@ -19,6 +19,69 @@
import lombok.Data;
import lombok.NoArgsConstructor;
+/**
+ * The `UserDTO` class represents a Data Transfer Object (DTO) used for
+ * user-related information. It is typically used to encapsulate user data
+ * obtained from authentication or authorization services.
+ *
+ * Annotations:
+ *
+ * - @Data: Lombok annotation that generates getters,
+ * setters, equals, hashCode, and toString methods, as well as a constructor
+ * with all arguments and a no-args constructor.
+ * - @NoArgsConstructor: Lombok annotation that generates a
+ * no-arguments constructor.
+ * - @AllArgsConstructor: Lombok annotation that generates a
+ * constructor with all fields as arguments.
+ * - @JsonProperty: Jackson annotation used to map JSON
+ * properties to Java fields, ensuring the correct mapping between JSON data and
+ * the DTO fields.
+ *
+ *
+ * Fields:
+ *
+ * - id: The unique identifier of the user, mapped from the
+ * JSON property "sub".
+ * - username: The preferred username of the user, mapped
+ * from the JSON property "preferred_username".
+ *
+ *
+ * Usage Example:
+ *
+ * {@code
+ * // Creating a UserDTO instance using the all-args constructor
+ * UserDTO user = new UserDTO("12345", "tien");
+ *
+ * // Accessing properties
+ * String userId = user.getId();
+ * String username = user.getUsername();
+ *
+ * // Displaying user information
+ * System.out.println("User ID: " + user.getId());
+ * System.out.println("Username: " + user.getUsername());
+ *
+ * // Creating a UserDTO instance using the no-args constructor and setters
+ * UserDTO anotherUser = new UserDTO();
+ * anotherUser.setId("67890");
+ * anotherUser.setUsername("hoangtien2k3");
+ * }
+ *
+ * Detailed Description:
+ *
+ *
+ * The `UserDTO` class is a simple data structure used to transfer user
+ * information between different layers of an application or between systems. It
+ * includes fields for a unique user ID and a preferred username.
+ *
+ *
+ *
+ * The class is annotated with Lombok annotations to simplify the creation and
+ * manipulation of `UserDTO` instances. The `@JsonProperty` annotations are used
+ * to ensure that JSON properties are correctly mapped to the Java fields, which
+ * is particularly useful when working with JSON data from external services or
+ * APIs.
+ *
+ */
@Data
@NoArgsConstructor
@AllArgsConstructor
diff --git a/src/main/java/io/hoangtien2k3/commons/model/WhiteList.java b/src/main/java/io/hoangtien2k3/commons/model/WhiteList.java
index f00c42a..f3845cd 100644
--- a/src/main/java/io/hoangtien2k3/commons/model/WhiteList.java
+++ b/src/main/java/io/hoangtien2k3/commons/model/WhiteList.java
@@ -19,6 +19,60 @@
import lombok.Data;
import lombok.NoArgsConstructor;
+/**
+ * The `WhiteList` class represents the configuration for public APIs that do
+ * not require authentication. This class is used to define which URIs and HTTP
+ * methods are allowed to be accessed without authentication.
+ *
+ * Annotations:
+ *
+ * - @Data: Lombok annotation that automatically generates
+ * getters, setters, equals, hashCode, and toString methods, along with a
+ * constructor with all arguments and a no-arguments constructor.
+ * - @NoArgsConstructor: Lombok annotation that generates a
+ * no-arguments constructor.
+ * - @AllArgsConstructor: Lombok annotation that generates a
+ * constructor with all fields as arguments.
+ *
+ *
+ * Fields:
+ *
+ * - uri: The URI pattern that is whitelisted and accessible
+ * without authentication. For example, "/public/api" or "/v1/resources".
+ * - methods: A list of HTTP methods (e.g., GET, POST, PUT)
+ * that are allowed for the given URI. This allows specifying which HTTP methods
+ * are permitted for the URI. If the list is empty, all methods are allowed for
+ * the URI.
+ *
+ *
+ * Configuration Example:
+ *
+ * {@code
+ * # In application.yml
+ * whitelist:
+ * - uri: /public/api
+ * methods:
+ * - GET
+ * - POST
+ * - uri: /v1/resources
+ * methods:
+ * - GET
+ * }
+ *
+ * Usage:
+ *
+ * The `WhiteList` class is used in the configuration of your application to
+ * define which endpoints can be accessed without authentication. This
+ * configuration helps in making certain APIs publicly accessible while securing
+ * other parts of your application.
+ *
+ *
+ *
+ * The class is typically used in conjunction with Spring Boot's configuration
+ * properties support, allowing you to easily inject these configurations into
+ * your application's security setup.
+ *
+ */
@Data
@AllArgsConstructor
@NoArgsConstructor
diff --git a/src/main/java/io/hoangtien2k3/commons/model/logging/HttpLogRequest.java b/src/main/java/io/hoangtien2k3/commons/model/logging/HttpLogRequest.java
index 3ff4e4c..eebd448 100644
--- a/src/main/java/io/hoangtien2k3/commons/model/logging/HttpLogRequest.java
+++ b/src/main/java/io/hoangtien2k3/commons/model/logging/HttpLogRequest.java
@@ -18,6 +18,68 @@
import lombok.Data;
import lombok.NoArgsConstructor;
+/**
+ * The `HttpLogRequest` class is a configuration class used to control whether
+ * HTTP request logging is enabled or disabled.
+ *
+ * Attributes:
+ *
+ * - enable: A boolean flag indicating whether HTTP request
+ * logging is enabled. Default value is
true.
+ *
+ *
+ * Constructor Details:
+ *
+ * - HttpLogRequest(): Default constructor that initializes
+ *
enable to true.
+ * - HttpLogRequest(boolean enable): Constructor that allows
+ * setting the
enable flag explicitly.
+ *
+ *
+ * Usage Example:
+ *
+ *
+ * {
+ * @code
+ * @Configuration
+ * public class LoggingConfig {
+ *
+ * @Bean
+ * public HttpLogRequest httpLogRequest() {
+ * return new HttpLogRequest(true);
+ * }
+ * }
+ * }
+ *
+ *
+ * Configuration Example:
+ *
+ * {@code
+ * # application.yml
+ * http:
+ * log:
+ * enable: false
+ * }
+ *
+ * Detailed Description:
+ *
+ *
+ * The `HttpLogRequest` class provides a simple way to configure logging of HTTP
+ * requests within an application. By setting the enable attribute
+ * to true, you can enable detailed logging for HTTP requests. If
+ * set to false, logging is disabled, which can be useful for
+ * reducing log verbosity in production environments or when detailed request
+ * logging is not required.
+ *
+ *
+ *
+ * This class can be used in conjunction with other logging configuration
+ * classes or aspects to conditionally enable or disable HTTP request logging
+ * based on the application's needs. It helps in centralizing the configuration
+ * of logging behavior and makes it easier to manage and control logging
+ * settings.
+ *
+ */
@Data
@AllArgsConstructor
@NoArgsConstructor
diff --git a/src/main/java/io/hoangtien2k3/commons/model/logging/HttpLogResponse.java b/src/main/java/io/hoangtien2k3/commons/model/logging/HttpLogResponse.java
index 0e06dd3..ed09dff 100644
--- a/src/main/java/io/hoangtien2k3/commons/model/logging/HttpLogResponse.java
+++ b/src/main/java/io/hoangtien2k3/commons/model/logging/HttpLogResponse.java
@@ -18,6 +18,68 @@
import lombok.Data;
import lombok.NoArgsConstructor;
+/**
+ * The {@code HttpLogResponse} class is a configuration class used to manage
+ * whether HTTP response logging is enabled or disabled.
+ *
+ * Attributes:
+ *
+ * - enable: A boolean flag indicating whether HTTP response
+ * logging is enabled. Default value is {@code true}.
+ *
+ *
+ * Constructor Details:
+ *
+ * - HttpLogResponse(): Default constructor that initializes
+ * {@code enable} to {@code true}.
+ * - HttpLogResponse(boolean enable): Constructor that allows
+ * setting the {@code enable} flag explicitly.
+ *
+ *
+ * Usage Example:
+ *
+ *
+ * {
+ * @code
+ * @Configuration
+ * public class LoggingConfig {
+ *
+ * @Bean
+ * public HttpLogResponse httpLogResponse() {
+ * return new HttpLogResponse(true);
+ * }
+ * }
+ * }
+ *
+ *
+ * Configuration Example:
+ *
+ * {@code
+ * # application.yml
+ * http:
+ * log:
+ * response:
+ * enable: false
+ * }
+ *
+ * Detailed Description:
+ *
+ *
+ * The {@code HttpLogResponse} class provides a mechanism to configure logging
+ * of HTTP responses within an application. By setting the {@code enable}
+ * attribute to {@code true}, detailed logging of HTTP responses is enabled.
+ * Setting it to {@code false} disables response logging, which can be useful to
+ * reduce log verbosity in production environments or when response logging is
+ * not necessary.
+ *
+ *
+ *
+ * This class can be used in combination with other logging configuration
+ * classes to control the logging behavior for HTTP responses. It centralizes
+ * the logging configuration and simplifies the management of logging settings
+ * for HTTP responses.
+ *
+ */
@Data
@AllArgsConstructor
@NoArgsConstructor
diff --git a/src/main/java/io/hoangtien2k3/commons/model/logging/LogField.java b/src/main/java/io/hoangtien2k3/commons/model/logging/LogField.java
index 8441711..07bbf73 100644
--- a/src/main/java/io/hoangtien2k3/commons/model/logging/LogField.java
+++ b/src/main/java/io/hoangtien2k3/commons/model/logging/LogField.java
@@ -16,6 +16,88 @@
import lombok.*;
+/**
+ * The `LogField` class is a data transfer object (DTO) designed to encapsulate
+ * various fields of logging information that can be used for structured logging
+ * in an application. This class is used to represent and store log data with
+ * detailed information about requests and responses.
+ *
+ * Attributes:
+ *
+ * - traceId: A unique identifier for tracking the trace of a
+ * request across different services.
+ * - requestId: A unique identifier for the specific request,
+ * often used to correlate logs for a single request.
+ * - service: The name of the service that generated the log
+ * entry.
+ * - duration: The duration of the request or operation in
+ * milliseconds.
+ * - logType: The type of log entry (e.g., INFO, ERROR,
+ * DEBUG).
+ * - actionType: The type of action or operation being logged
+ * (e.g., CREATE, UPDATE, DELETE).
+ * - startTime: The start time of the operation in
+ * milliseconds since epoch.
+ * - endTime: The end time of the operation in milliseconds
+ * since epoch.
+ * - clientAddress: The IP address of the client making the
+ * request.
+ * - title: A brief title or description of the log
+ * entry.
+ * - inputs: The input data or parameters provided in the
+ * request.
+ * - response: The response data or result returned by the
+ * service.
+ * - result: The outcome or result of the operation (e.g.,
+ * SUCCESS, FAILURE).
+ *
+ *
+ * Constructors:
+ *
+ * - LogField(): Default constructor.
+ * - LogField(String traceId, String requestId, String service, Long
+ * duration, String logType, String actionType, Long startTime, Long endTime,
+ * String clientAddress, String title, String inputs, String response, String
+ * result): Constructor with parameters to initialize all
+ * attributes.
+ *
+ *
+ * Methods:
+ *
+ * - Getters and Setters: Methods to get and set the values
+ * of each attribute.
+ * - Builder: Provides a builder pattern for creating
+ * instances of `LogField` with a fluent API.
+ *
+ *
+ * Usage Example:
+ *
+ * {@code
+ * LogField logField = LogField.builder().traceId("12345").requestId("67890").service("UserService").duration(150L)
+ * .logType("INFO").actionType("CREATE").startTime(System.currentTimeMillis() - 150)
+ * .endTime(System.currentTimeMillis()).clientAddress("192.168.1.1").title("User Created")
+ * .inputs("{\"username\":\"johndoe\"}").response("{\"status\":\"success\"}").result("SUCCESS").build();
+ *
+ * log.info("Log entry: {}", logField);
+ * }
+ *
+ * Detailed Description:
+ *
+ *
+ * The `LogField` class is used to structure and manage log data in a consistent
+ * manner. It includes fields for capturing detailed information about each log
+ * entry, such as trace IDs, request IDs, service names, durations, log types,
+ * and more. This structured approach helps in analyzing logs more effectively
+ * and correlating log entries across different components and services.
+ *
+ *
+ *
+ * By using the builder pattern, the `LogField` class provides a flexible and
+ * convenient way to create instances with various combinations of attributes.
+ * The class can be integrated with logging frameworks to enhance the quality
+ * and usability of log data.
+ *
+ */
@Data
@NoArgsConstructor
@AllArgsConstructor
diff --git a/src/main/java/io/hoangtien2k3/commons/model/logging/LoggerDTO.java b/src/main/java/io/hoangtien2k3/commons/model/logging/LoggerDTO.java
index 3c50d07..11cafbd 100644
--- a/src/main/java/io/hoangtien2k3/commons/model/logging/LoggerDTO.java
+++ b/src/main/java/io/hoangtien2k3/commons/model/logging/LoggerDTO.java
@@ -21,19 +21,155 @@
import lombok.NoArgsConstructor;
import reactor.util.context.Context;
+/**
+ * The `LoggerDTO` class represents a Data Transfer Object (DTO) designed for
+ * logging purposes. It encapsulates various fields related to logging
+ * information, including context, span details, timing, results, and more. This
+ * class is used to store and manage logging data for more structured and
+ * detailed log entries.
+ *
+ * Attributes:
+ *
+ * - contextRef: An `AtomicReference` containing the current
+ * `Context`. This is used to manage and share logging context information
+ * safely across threads.
+ * - newSpan: A `Span` object representing a new span in a
+ * distributed tracing system. This is useful for tracking the duration and
+ * details of specific operations in the system.
+ * - service: A `String` representing the name of the service
+ * generating the log entry.
+ * - startTime: A `Long` representing the start time of the
+ * operation in milliseconds since epoch.
+ * - endTime: A `Long` representing the end time of the
+ * operation in milliseconds since epoch.
+ * - result: A `String` indicating the result of the
+ * operation (e.g., SUCCESS, FAILURE).
+ * - response: An `Object` holding the response data returned
+ * by the service or operation.
+ * - logType: A `String` specifying the type of log entry
+ * (e.g., INFO, ERROR, DEBUG).
+ * - actionType: A `String` describing the type of action or
+ * operation being logged (e.g., CREATE, UPDATE, DELETE).
+ * - args: An array of `Object` holding the arguments or
+ * parameters passed to the operation.
+ * - title: A `String` providing a brief title or description
+ * of the log entry.
+ *
+ *
+ * Constructors:
+ *
+ * - LoggerDTO(): Default constructor that initializes an
+ * empty instance.
+ * - LoggerDTO(AtomicReference<Context> contextRef, Span
+ * newSpan, String service, Long startTime, Long endTime, String result, Object
+ * response, String logType, String actionType, Object[] args, String
+ * title): Constructor that initializes all attributes with provided
+ * values.
+ *
+ *
+ * Methods:
+ *
+ * - Getters and Setters: Methods to access and modify the
+ * values of each attribute.
+ *
+ *
+ * Usage Example:
+ *
+ * {@code
+ * // Create a new LoggerDTO instance with sample data
+ * LoggerDTO loggerDTO = new LoggerDTO(new AtomicReference<>(Context.current()), // Current context
+ * Span.current(), // Current span
+ * "UserService", // Service name
+ * System.currentTimeMillis() - 100, // Start time
+ * System.currentTimeMillis(), // End time
+ * "SUCCESS", // Result of the operation
+ * "{ \"status\": \"ok\" }", // Response data
+ * "INFO", // Log type
+ * "CREATE", // Action type
+ * new Object[]{"param1", "param2"}, // Arguments
+ * "User Created" // Title
+ * );
+ *
+ * // Use the LoggerDTO instance for logging
+ * log.info("Logging entry: {}", loggerDTO);
+ * }
+ *
+ * Detailed Description:
+ *
+ *
+ * The `LoggerDTO` class is designed to hold comprehensive details related to
+ * logging in an application. It captures information such as context, span,
+ * service name, timing, results, responses, and more. This structured approach
+ * helps in generating detailed and organized log entries, making it easier to
+ * monitor and troubleshoot the application.
+ *
+ *
+ *
+ * By using `AtomicReference` for context management and `Span` for distributed
+ * tracing, the class supports advanced logging scenarios in multi-threaded and
+ * distributed environments. The `LoggerDTO` class is useful for creating
+ * detailed log entries with all necessary context and metadata, enhancing the
+ * quality and usefulness of logs.
+ *
+ */
@Data
@NoArgsConstructor
@AllArgsConstructor
public class LoggerDTO {
- AtomicReference contextRef;
- Span newSpan;
- String service;
- Long startTime;
- Long endTime;
- String result;
- Object response;
- String logType;
- String actionType;
- Object[] args;
- String title;
+ /**
+ * An `AtomicReference` containing the current `Context`, used for managing and
+ * sharing logging context information safely across threads.
+ */
+ private AtomicReference contextRef;
+
+ /**
+ * A `Span` object representing a new span in a distributed tracing system,
+ * useful for tracking the duration and details of specific operations.
+ */
+ private Span newSpan;
+
+ /**
+ * The name of the service generating the log entry.
+ */
+ private String service;
+
+ /**
+ * The start time of the operation in milliseconds since epoch.
+ */
+ private Long startTime;
+
+ /**
+ * The end time of the operation in milliseconds since epoch.
+ */
+ private Long endTime;
+
+ /**
+ * The result of the operation (e.g., SUCCESS, FAILURE).
+ */
+ private String result;
+
+ /**
+ * The response data returned by the service or operation.
+ */
+ private Object response;
+
+ /**
+ * The type of log entry (e.g., INFO, ERROR, DEBUG).
+ */
+ private String logType;
+
+ /**
+ * The type of action or operation being logged (e.g., CREATE, UPDATE, DELETE).
+ */
+ private String actionType;
+
+ /**
+ * An array of arguments or parameters passed to the operation.
+ */
+ private Object[] args;
+
+ /**
+ * A brief title or description of the log entry.
+ */
+ private String title;
}
diff --git a/src/main/java/io/hoangtien2k3/commons/utils/MessageUtils.java b/src/main/java/io/hoangtien2k3/commons/utils/MessageUtils.java
index b016bae..4028521 100644
--- a/src/main/java/io/hoangtien2k3/commons/utils/MessageUtils.java
+++ b/src/main/java/io/hoangtien2k3/commons/utils/MessageUtils.java
@@ -20,15 +20,170 @@
import lombok.extern.slf4j.Slf4j;
import org.springframework.context.i18n.LocaleContextHolder;
+/**
+ * Utility class for handling internationalized messages.
+ *
+ * The {@code MessageUtils} class provides methods to retrieve localized
+ * messages from a resource bundle. It supports message formatting and fallback
+ * mechanisms for missing or erroneous messages.
+ *
+ * Class Overview:
+ *
+ * The class uses {@code ResourceBundle} to fetch messages based on the provided
+ * locale. It formats the message using {@code MessageFormat} and handles
+ * exceptions to ensure that the application continues to function even if a
+ * message is missing or the resource bundle is misconfigured.
+ *
+ *
+ * Fields:
+ *
+ * - BASE_NAME: The base name of the resource bundle, which
+ * is typically the name of the properties file (without the .properties
+ * extension) containing the messages. Defaults to "messages".
+ *
+ *
+ * Methods:
+ *
+ * - getMessage(String code, Locale locale): Retrieves the
+ * message associated with the given code and locale. If the message is missing
+ * or an error occurs, the code itself is returned as a fallback.
+ *
+ * Parameters:
+ *
+ *
+ * - code: The key for the desired message.
+ * - locale: The locale to use for message retrieval.
+ *
+ *
+ * Returns:
+ *
+ *
+ * - The localized message, or the code itself if the message is not
+ * found.
+ *
+ *
+ *
+ * - getMessage(String code, Locale locale, Object... args):
+ * Retrieves and formats the message associated with the given code and locale,
+ * using the provided arguments.
+ *
+ * Parameters:
+ *
+ *
+ * - code: The key for the desired message.
+ * - locale: The locale to use for message retrieval.
+ * - args: Arguments to format the message.
+ *
+ *
+ * Returns:
+ *
+ *
+ * - The formatted message, or the code itself if the message is not
+ * found.
+ *
+ *
+ *
+ * - getMessage(String code): Retrieves the message
+ * associated with the given code, using the default locale from
+ * {@code LocaleContextHolder}.
+ *
+ * Parameters:
+ *
+ *
+ * - code: The key for the desired message.
+ *
+ *
+ * Returns:
+ *
+ *
+ * - The localized message, or the code itself if the message is not
+ * found.
+ *
+ *
+ *
+ * - getMessage(String code, Object... args): Retrieves and
+ * formats the message associated with the given code, using the default locale
+ * from {@code LocaleContextHolder} and the provided arguments.
+ *
+ * Parameters:
+ *
+ *
+ * - code: The key for the desired message.
+ * - args: Arguments to format the message.
+ *
+ *
+ * Returns:
+ *
+ *
+ * - The formatted message, or the code itself if the message is not
+ * found.
+ *
+ *
+ *
+ *
+ * Usage Example:
+ *
+ * {@code
+ * // Assuming there is a message property file named "messages.properties" with
+ * // a key "welcome.message"
+ * String message = MessageUtils.getMessage("welcome.message", Locale.US);
+ * // Output: "Welcome to our application!"
+ *
+ * // With arguments
+ * String formattedMessage = MessageUtils.getMessage("welcome.user", Locale.US, "John");
+ * // Output: "Welcome to our application, John!"
+ *
+ * // Using default locale
+ * String defaultMessage = MessageUtils.getMessage("default.message");
+ * // Output will be based on the default locale set in LocaleContextHolder
+ * }
+ *
+ * Notes:
+ *
+ * The `MessageUtils` class relies on `ResourceBundle` for message retrieval.
+ * Ensure that the resource bundle files (e.g., `messages.properties`,
+ * `messages_en.properties`) are correctly placed in the classpath. The class
+ * also uses `LocaleContextHolder` to fetch the default locale, which should be
+ * properly configured in your Spring application context.
+ *
+ *
+ *
+ * Logging is performed for exceptions occurring during message retrieval,
+ * helping in debugging issues with missing or malformed messages.
+ *
+ */
@Slf4j
public class MessageUtils {
private static final String BASE_NAME = "messages";
+ /**
+ * Retrieves the message associated with the given code and locale.
+ *
+ * @param code
+ * The key for the desired message.
+ * @param locale
+ * The locale to use for message retrieval.
+ * @return The localized message, or the code itself if the message is not
+ * found.
+ */
public static String getMessage(String code, Locale locale) {
return getMessage(code, locale, null);
}
+ /**
+ * Retrieves and formats the message associated with the given code and locale,
+ * using the provided arguments.
+ *
+ * @param code
+ * The key for the desired message.
+ * @param locale
+ * The locale to use for message retrieval.
+ * @param args
+ * Arguments to format the message.
+ * @return The formatted message, or the code itself if the message is not
+ * found.
+ */
public static String getMessage(String code, Locale locale, Object... args) {
ResourceBundle resourceBundle = ResourceBundle.getBundle(BASE_NAME, locale);
String message;
@@ -43,10 +198,30 @@ public static String getMessage(String code, Locale locale, Object... args) {
return message;
}
+ /**
+ * Retrieves the message associated with the given code, using the default
+ * locale from LocaleContextHolder.
+ *
+ * @param code
+ * The key for the desired message.
+ * @return The localized message, or the code itself if the message is not
+ * found.
+ */
public static String getMessage(String code) {
return getMessage(code, LocaleContextHolder.getLocale(), null);
}
+ /**
+ * Retrieves and formats the message associated with the given code, using the
+ * default locale from LocaleContextHolder and the provided arguments.
+ *
+ * @param code
+ * The key for the desired message.
+ * @param args
+ * Arguments to format the message.
+ * @return The formatted message, or the code itself if the message is not
+ * found.
+ */
public static String getMessage(String code, Object... args) {
return getMessage(code, LocaleContextHolder.getLocale(), args);
}
diff --git a/src/main/java/io/hoangtien2k3/commons/utils/MinioUtils.java b/src/main/java/io/hoangtien2k3/commons/utils/MinioUtils.java
index f2d1290..52a716c 100644
--- a/src/main/java/io/hoangtien2k3/commons/utils/MinioUtils.java
+++ b/src/main/java/io/hoangtien2k3/commons/utils/MinioUtils.java
@@ -40,6 +40,138 @@
import reactor.core.publisher.Mono;
import reactor.core.scheduler.Schedulers;
+/**
+ * Utility class for handling internationalized messages.
+ *
+ * The {@code MessageUtils} class provides methods to retrieve localized
+ * messages from a resource bundle. It supports message formatting and fallback
+ * mechanisms for missing or erroneous messages.
+ *
+ * Class Overview:
+ *
+ * The class uses {@code ResourceBundle} to fetch messages based on the provided
+ * locale. It formats the message using {@code MessageFormat} and handles
+ * exceptions to ensure that the application continues to function even if a
+ * message is missing or the resource bundle is misconfigured.
+ *
+ *
+ * Fields:
+ *
+ * - BASE_NAME: The base name of the resource bundle, which
+ * is typically the name of the properties file (without the .properties
+ * extension) containing the messages. Defaults to "messages".
+ *
+ *
+ * Methods:
+ *
+ * - getMessage(String code, Locale locale): Retrieves the
+ * message associated with the given code and locale. If the message is missing
+ * or an error occurs, the code itself is returned as a fallback.
+ *
+ * Parameters:
+ *
+ *
+ * - code: The key for the desired message.
+ * - locale: The locale to use for message retrieval.
+ *
+ *
+ * Returns:
+ *
+ *
+ * - The localized message, or the code itself if the message is not
+ * found.
+ *
+ *
+ *
+ * - getMessage(String code, Locale locale, Object... args):
+ * Retrieves and formats the message associated with the given code and locale,
+ * using the provided arguments.
+ *
+ * Parameters:
+ *
+ *
+ * - code: The key for the desired message.
+ * - locale: The locale to use for message retrieval.
+ * - args: Arguments to format the message.
+ *
+ *
+ * Returns:
+ *
+ *
+ * - The formatted message, or the code itself if the message is not
+ * found.
+ *
+ *
+ *
+ * - getMessage(String code): Retrieves the message
+ * associated with the given code, using the default locale from
+ * {@code LocaleContextHolder}.
+ *
+ * Parameters:
+ *
+ *
+ * - code: The key for the desired message.
+ *
+ *
+ * Returns:
+ *
+ *
+ * - The localized message, or the code itself if the message is not
+ * found.
+ *
+ *
+ *
+ * - getMessage(String code, Object... args): Retrieves and
+ * formats the message associated with the given code, using the default locale
+ * from {@code LocaleContextHolder} and the provided arguments.
+ *
+ * Parameters:
+ *
+ *
+ * - code: The key for the desired message.
+ * - args: Arguments to format the message.
+ *
+ *
+ * Returns:
+ *
+ *
+ * - The formatted message, or the code itself if the message is not
+ * found.
+ *
+ *
+ *
+ *
+ * Usage Example:
+ *
+ * {@code
+ * // Assuming there is a message property file named "messages.properties" with
+ * // a key "welcome.message"
+ * String message = MessageUtils.getMessage("welcome.message", Locale.US);
+ * // Output: "Welcome to our application!"
+ *
+ * // With arguments
+ * String formattedMessage = MessageUtils.getMessage("welcome.user", Locale.US, "Tien");
+ * // Output: "Welcome to our application, John!"
+ *
+ * // Using default locale
+ * String defaultMessage = MessageUtils.getMessage("default.message");
+ * // Output will be based on the default locale set in LocaleContextHolder
+ * }
+ *
+ * Notes:
+ *
+ * The `MessageUtils` class relies on `ResourceBundle` for message retrieval.
+ * Ensure that the resource bundle files (e.g., `messages.properties`,
+ * `messages_en.properties`) are correctly placed in the classpath. The class
+ * also uses `LocaleContextHolder` to fetch the default locale, which should be
+ * properly configured in your Spring application context.
+ *
+ *
+ *
+ * Logging is performed for exceptions occurring during message retrieval,
+ * helping in debugging issues with missing or malformed messages.
+ *
+ */
@Slf4j
@Component
@ConditionalOnProperty(value = "minio.enabled", havingValue = "true", matchIfMissing = false)
diff --git a/src/main/java/io/hoangtien2k3/commons/utils/PageUtils.java b/src/main/java/io/hoangtien2k3/commons/utils/PageUtils.java
index 28ea953..1f3250f 100644
--- a/src/main/java/io/hoangtien2k3/commons/utils/PageUtils.java
+++ b/src/main/java/io/hoangtien2k3/commons/utils/PageUtils.java
@@ -14,7 +14,88 @@
*/
package io.hoangtien2k3.commons.utils;
+/**
+ * Utility class for pagination-related operations.
+ *
+ * The {@code PageUtils} class provides a static method to calculate the offset
+ * for pagination based on the current page number and page size. This is
+ * particularly useful for retrieving paginated results from a database or other
+ * data sources.
+ *
+ *
+ * Class Overview:
+ *
+ * This class contains utility methods for handling pagination calculations.
+ * Currently, it includes a method to compute the offset given a page number and
+ * page size.
+ *
+ *
+ * Methods:
+ *
+ * - getOffset: Calculates the offset for pagination based on
+ * the provided page number and page size.
+ *
+ * - Parameters:
+ *
+ * page (Integer): The current page number. Must be greater
+ * than 0.size (Integer): The number of items per page. Must be
+ * greater than 0.
+ *
+ * - Returns:
+ *
+ * An integer representing the offset. If the page or
+ * size is null or less than or equal to 0, the method returns 0.
+ *
+ *
+ * - Usage:
+ *
+ * This method can be used to calculate the starting index for a particular page
+ * in a paginated data set. For example, if the page size is 10 and the current
+ * page is 3, the method will calculate an offset of 20, which is the starting
+ * index for the 3rd page (page index starts at 0).
+ *
+ *
+ *
+ *
+ *
+ *
+ * Usage Example:
+ *
+ * {@code
+ * int page = 3;
+ * int size = 10;
+ * int offset = PageUtils.getOffset(page, size);
+ * // offset will be 20, which is used to fetch records starting from index 20
+ * }
+ *
+ * Notes:
+ *
+ * Ensure that the page number and page size are validated before calling the
+ * method. If either value is invalid (e.g., less than or equal to 0), the
+ * method returns 0, which might result in incorrect pagination behavior if not
+ * handled properly in the application logic.
+ *
+ */
public class PageUtils {
+
+ /**
+ * Calculates the offset for pagination based on the current page number and
+ * page size.
+ *
+ * This method computes the starting index for the given page number and page
+ * size. The offset is calculated as (page - 1) * size. If the page or size is
+ * null or not positive, it returns 0.
+ *
+ *
+ * @param page
+ * The current page number. Must be greater than 0.
+ * @param size
+ * The number of items per page. Must be greater than 0.
+ * @return The calculated offset. Returns 0 if page or size is null or less than
+ * or equal to 0.
+ */
public static int getOffset(Integer page, Integer size) {
if (page == null || page <= 0 || size == null || size <= 0) return 0;
return (page - 1) * size;
diff --git a/src/main/java/io/hoangtien2k3/commons/utils/ReactiveOAuth2Utils.java b/src/main/java/io/hoangtien2k3/commons/utils/ReactiveOAuth2Utils.java
index 190fec8..45a9ca0 100644
--- a/src/main/java/io/hoangtien2k3/commons/utils/ReactiveOAuth2Utils.java
+++ b/src/main/java/io/hoangtien2k3/commons/utils/ReactiveOAuth2Utils.java
@@ -17,10 +17,100 @@
import org.springframework.security.oauth2.client.*;
import org.springframework.security.oauth2.client.registration.ReactiveClientRegistrationRepository;
+/**
+ * Utility class for creating a {@link ReactiveOAuth2AuthorizedClientManager}
+ * instance.
+ *
+ * The {@code ReactiveOAuth2Utils} class provides a static method to configure
+ * and instantiate a {@link ReactiveOAuth2AuthorizedClientManager} with a
+ * specific {@link ReactiveOAuth2AuthorizedClientProvider}. This is useful for
+ * managing OAuth2 clients in a reactive environment, particularly for scenarios
+ * involving client credentials grant types.
+ *
+ *
+ * Class Overview:
+ *
+ * This class contains a utility method for creating and configuring a
+ * {@link ReactiveOAuth2AuthorizedClientManager}. The manager is responsible for
+ * handling OAuth2 authorized clients and their respective tokens in a reactive
+ * Spring application.
+ *
+ *
+ * Methods:
+ *
+ * - createAuthorizedClientManager: Configures and creates an
+ * instance of {@link ReactiveOAuth2AuthorizedClientManager} using the provided
+ * client registration repository and authorized client service.
+ *
+ * - Parameters:
+ *
+ * clientRegistrationRepository
+ * ({@link ReactiveClientRegistrationRepository}): Repository for managing
+ * client registrations. It provides information about client details such as
+ * client ID, client secret, and scopes.authorizedClientService
+ * ({@link ReactiveOAuth2AuthorizedClientService}): Service for managing
+ * authorized clients and their tokens. It handles storing and retrieving
+ * authorized client information.
+ *
+ * - Returns:
+ *
+ * A {@link ReactiveOAuth2AuthorizedClientManager} instance configured with the
+ * provided client registration repository and authorized client service. This
+ * manager is used to manage and authorize OAuth2 clients.
+ *
+ *
+ * - Usage:
+ *
+ * This method is used to set up an authorized client manager for handling
+ * OAuth2 authentication in a reactive application. The manager will use client
+ * credentials grant type to obtain access tokens and manage OAuth2 clients.
+ *
+ *
+ *
+ *
+ *
+ *
+ * Usage Example:
+ *
+ * {@code
+ * ReactiveClientRegistrationRepository clientRegistrationRepository = // obtain or create repository
+ * ReactiveOAuth2AuthorizedClientService authorizedClientService = // obtain or create service
+ * ReactiveOAuth2AuthorizedClientManager authorizedClientManager =
+ * ReactiveOAuth2Utils.createAuthorizedClientManager(clientRegistrationRepository, authorizedClientService);
+ * }
+ *
+ * Notes:
+ *
+ * Ensure that the provided {@link ReactiveClientRegistrationRepository} and
+ * {@link ReactiveOAuth2AuthorizedClientService} are correctly configured and
+ * initialized before passing them to the method. This setup is crucial for
+ * proper OAuth2 client management and token handling.
+ *
+ */
public class ReactiveOAuth2Utils {
+
+ /**
+ * Creates and configures a {@link ReactiveOAuth2AuthorizedClientManager}
+ * instance.
+ *
+ * This method sets up a {@link ReactiveOAuth2AuthorizedClientManager} with a
+ * client credentials provider, using the provided
+ * {@link ReactiveClientRegistrationRepository} and
+ * {@link ReactiveOAuth2AuthorizedClientService}.
+ *
+ *
+ * @param clientRegistrationRepository
+ * The repository for managing client registrations.
+ * @param authorizedClientService
+ * The service for managing authorized clients and their tokens.
+ * @return A configured {@link ReactiveOAuth2AuthorizedClientManager} instance.
+ */
public static ReactiveOAuth2AuthorizedClientManager createAuthorizedClientManager(
ReactiveClientRegistrationRepository clientRegistrationRepository,
ReactiveOAuth2AuthorizedClientService authorizedClientService) {
+
ReactiveOAuth2AuthorizedClientProvider authorizedClientProvider =
ReactiveOAuth2AuthorizedClientProviderBuilder.builder()
.clientCredentials()
diff --git a/src/main/java/io/hoangtien2k3/commons/utils/SQLUtils.java b/src/main/java/io/hoangtien2k3/commons/utils/SQLUtils.java
index c5aaa11..8a5ca33 100644
--- a/src/main/java/io/hoangtien2k3/commons/utils/SQLUtils.java
+++ b/src/main/java/io/hoangtien2k3/commons/utils/SQLUtils.java
@@ -16,7 +16,86 @@
import org.apache.commons.lang3.StringUtils;
+/**
+ * Utility class for handling SQL-related operations.
+ *
+ * The {@code SQLUtils} class provides a static method to replace special
+ * characters in a string to make it suitable for use in SQL queries. This is
+ * particularly useful for escaping characters that have special meanings in SQL
+ * like `%` and `_`, which are used in wildcard patterns.
+ *
+ *
+ * Class Overview:
+ *
+ * This class contains utility methods for SQL operations. Specifically, it
+ * provides a method to replace special characters in a string that can
+ * interfere with SQL query syntax.
+ *
+ *
+ * Methods:
+ *
+ * - replaceSpecialDigit: Replaces special characters in a
+ * string to prevent them from being interpreted as SQL wildcards.
+ *
+ * - Parameters:
+ *
+ * value (String): The string to be processed. It
+ * can be any value that might contain special characters.
+ *
+ * - Returns:
+ *
+ * The processed string with special characters replaced. Specifically, the
+ * percent sign (`%`) and underscore (`_`) are replaced with their escaped
+ * versions (`\%` and `\_` respectively). If the input string is empty or
+ * null, an empty string is returned.
+ *
+ *
+ * - Usage:
+ *
+ * This method is used to escape special characters in SQL queries to prevent
+ * them from being interpreted as wildcards. For example, if you need to include
+ * a literal percent sign in your SQL query, you would use this method to
+ * replace `%` with `\%`.
+ *
+ *
+ *
+ *
+ *
+ *
+ * Usage Example:
+ *
+ * {@code
+ * String rawValue = "100%";
+ * String safeValue = SQLUtils.replaceSpecialDigit(rawValue);
+ * // safeValue will be "100\\%"
+ * }
+ *
+ * Notes:
+ *
+ * This utility method is designed to handle basic escaping of special
+ * characters for SQL queries. Depending on the SQL database being used,
+ * additional escaping or handling might be required for other special
+ * characters or SQL injection prevention.
+ *
+ */
public class SQLUtils {
+
+ /**
+ * Replaces special characters in a string to prevent them from being
+ * interpreted as SQL wildcards.
+ *
+ * Specifically, the percent sign (`%`) and underscore (`_`) are replaced with
+ * their escaped versions (`\%` and `\_` respectively). This is useful for
+ * ensuring that these characters are treated as literals in SQL queries rather
+ * than wildcards.
+ *
+ *
+ * @param value
+ * The string to be processed. Can be null or empty.
+ * @return The processed string with special characters replaced. Returns an
+ * empty string if the input is null or empty.
+ */
public static String replaceSpecialDigit(String value) {
if (!StringUtils.isEmpty(value)) {
value = value.replace("%", "\\%").replace("_", "\\_");
diff --git a/src/main/java/io/hoangtien2k3/commons/utils/StreamUtil.java b/src/main/java/io/hoangtien2k3/commons/utils/StreamUtil.java
index a5105ee..42a0706 100644
--- a/src/main/java/io/hoangtien2k3/commons/utils/StreamUtil.java
+++ b/src/main/java/io/hoangtien2k3/commons/utils/StreamUtil.java
@@ -18,12 +18,91 @@
import java.io.InputStream;
import lombok.extern.slf4j.Slf4j;
+/**
+ * Utility class for handling stream operations.
+ *
+ * The {@code StreamUtil} class provides a static method for converting an
+ * {@link InputStream} into a byte array. This is useful for reading data from a
+ * stream and processing it as a byte array.
+ *
+ *
+ * Class Overview:
+ *
+ * This class contains utility methods for working with streams. Specifically,
+ * it provides a method to read data from an {@code InputStream} and convert it
+ * into a byte array.
+ *
+ *
+ * Methods:
+ *
+ * - streamToByteArray: Reads all the bytes from an
+ * {@code InputStream} and returns them as a byte array.
+ *
+ * - Parameters:
+ *
+ * inStream (InputStream): The input stream to be
+ * read.
+ *
+ * - Returns:
+ *
+ * A byte array containing the data read from the input stream. If an error
+ * occurs during reading, an empty byte array is returned.
+ *
+ *
+ * - Usage:
+ *
+ * This method is used to read data from an input stream into a byte array. This
+ * is useful when you need to process or manipulate the entire contents of a
+ * stream as a byte array.
+ *
+ *
+ * - Exceptions:
+ *
+ * If an error occurs during the reading process (e.g., an {@link Exception} is
+ * thrown), an error message is logged, and an empty byte array is returned.
+ *
+ *
+ *
+ *
+ *
+ *
+ * Usage Example:
+ *
+ * {@code
+ * InputStream inputStream = new FileInputStream("path/to/file");
+ * byte[] data = StreamUtil.streamToByteArray(inputStream);
+ * // data now contains the byte array representation of the file
+ * }
+ *
+ * Notes:
+ *
+ * The buffer size used for reading the stream is 100 bytes. If the stream
+ * contains more data, it will be read in chunks until the end of the stream is
+ * reached. The method ensures that all data from the input stream is captured
+ * in the resulting byte array.
+ *
+ */
@Slf4j
public class StreamUtil {
+
+ /**
+ * Converts an {@link InputStream} into a byte array.
+ *
+ * This method reads data from the input stream in chunks and writes it to a
+ * {@link ByteArrayOutputStream}. Once all data has been read, it is converted
+ * into a byte array and returned.
+ *
+ *
+ * @param inStream
+ * The input stream to be read. Must not be null.
+ * @return A byte array containing the data read from the input stream. If an
+ * error occurs, an empty byte array is returned.
+ */
public static byte[] streamToByteArray(InputStream inStream) {
ByteArrayOutputStream swapStream = new ByteArrayOutputStream();
byte[] buff = new byte[100];
- int rc = 0;
+ int rc;
byte[] in_b = new byte[] {};
try {
while ((rc = inStream.read(buff, 0, 100)) > 0) {
diff --git a/src/main/java/io/hoangtien2k3/commons/utils/TruncateUtils.java b/src/main/java/io/hoangtien2k3/commons/utils/TruncateUtils.java
index e87079f..d69b0d0 100644
--- a/src/main/java/io/hoangtien2k3/commons/utils/TruncateUtils.java
+++ b/src/main/java/io/hoangtien2k3/commons/utils/TruncateUtils.java
@@ -20,8 +20,153 @@
import lombok.extern.slf4j.Slf4j;
import org.springframework.util.MultiValueMap;
+/**
+ * Utility class for truncating strings and handling serialization of objects.
+ *
+ * The {@code TruncateUtils} class provides methods for truncating a string to
+ * ensure it does not exceed a specified byte length when encoded in UTF-8. It
+ * also includes methods for serializing objects and handling form data
+ * truncation.
+ *
+ *
+ * Class Overview:
+ *
+ * This class contains methods to truncate strings based on byte length,
+ * serialize objects to strings, and handle form data truncation.
+ *
+ *
+ * Methods:
+ *
+ * - truncate: Truncates a string to fit within a specified
+ * byte length when encoded in UTF-8.
+ *
+ * - Parameters:
+ *
+ * - {@code s} ({@code String}): The string to be truncated. Can be
+ * {@code null} or empty.
+ * - {@code maxByte} ({@code int}): The maximum byte length for the truncated
+ * string.
+ *
+ *
+ * - Returns:
+ *
+ * A truncated version of the input string if it exceeds the specified byte
+ * length, otherwise the original string.
+ *
+ *
+ * - Exceptions:
+ *
+ * Logs an error if an exception occurs during the truncation process. Returns
+ * the original string if an error occurs.
+ *
+ *
+ *
+ *
+ * - truncateBody: Truncates a string to fit within a
+ * specified byte length when encoded in UTF-8.
+ *
+ * - Parameters:
+ *
+ * - {@code s} ({@code String}): The string to be truncated.
+ * - {@code maxByte} ({@code int}): The maximum byte length for the truncated
+ * string.
+ *
+ *
+ * - Returns:
+ *
+ * A truncated version of the input string if it exceeds the specified byte
+ * length, otherwise the original string.
+ *
+ *
+ * - Notes:
+ *
+ * This method calculates the number of bytes required for each character in the
+ * string to ensure that the truncation does not break multi-byte characters.
+ *
+ *
+ *
+ *
+ * - truncateBody(Object responseBody): Serializes an object
+ * to a JSON string and truncates it.
+ *
+ * - Parameters:
+ *
+ * - {@code responseBody} ({@code Object}): The object to be serialized and
+ * truncated.
+ *
+ *
+ * - Returns:
+ *
+ * A JSON representation of the object, truncated if necessary. If serialization
+ * fails, returns a placeholder string.
+ *
+ *
+ * - Exceptions:
+ *
+ * Logs an error if an exception occurs during serialization. Returns a
+ * placeholder string if an error occurs.
+ *
+ *
+ *
+ *
+ * - truncateBody(MultiValueMap formData):
+ * Truncates and concatenates form data.
+ *
+ *
+ *
+ *
+ * Usage Example:
+ *
+ * {@code
+ * String longString = "A very long string that needs to be truncated...";
+ * String truncatedString = TruncateUtils.truncate(longString, 50);
+ * // truncatedString will contain the first 50 bytes of the original string
+ *
+ * Object responseObject = new SomeObject();
+ * String jsonString = TruncateUtils.truncateBody(responseObject);
+ * // jsonString will contain the JSON representation of responseObject
+ * }
+ *
+ * Notes:
+ *
+ * The UTF-8 byte length calculation considers multi-byte characters to ensure
+ * that truncation does not cut characters in the middle. The class uses
+ * {@code ObjectMapper} for serialization of objects and handles exceptions
+ * gracefully by logging errors and returning default values when necessary.
+ *
+ */
@Slf4j
public class TruncateUtils {
+
+ /**
+ * Truncates a string to fit within a specified byte length when encoded in
+ * UTF-8.
+ *
+ * This method first checks if the string is null or empty, and if so, returns
+ * it as is. If the string is longer than the specified byte length, it is
+ * truncated while preserving multi-byte characters.
+ *
+ *
+ * @param s
+ * The string to be truncated. Can be null or empty.
+ * @param maxByte
+ * The maximum byte length for the truncated string.
+ * @return A truncated version of the input string if it exceeds the specified
+ * byte length, otherwise the original string.
+ */
public static String truncate(String s, int maxByte) {
try {
if (DataUtil.isNullOrEmpty(s)) {
@@ -38,6 +183,22 @@ public static String truncate(String s, int maxByte) {
return s;
}
+ /**
+ * Truncates a string to fit within a specified byte length when encoded in
+ * UTF-8.
+ *
+ * This method iterates over the characters in the string, calculating the byte
+ * length for each character and truncating the string when the total byte
+ * length exceeds the specified limit.
+ *
+ *
+ * @param s
+ * The string to be truncated.
+ * @param maxByte
+ * The maximum byte length for the truncated string.
+ * @return A truncated version of the input string if it exceeds the specified
+ * byte length, otherwise the original string.
+ */
public static String truncateBody(String s, int maxByte) {
int b = 0;
for (int i = 0; i < s.length(); i++) {
@@ -69,6 +230,20 @@ public static String truncateBody(String s, int maxByte) {
return s;
}
+ /**
+ * Serializes an object to a JSON string and truncates it to fit within a
+ * specified byte length.
+ *
+ * This method uses Jackson's `ObjectMapper` to convert the object to a JSON
+ * string and then truncates it. If serialization fails, a placeholder string is
+ * returned.
+ *
+ *
+ * @param responseBody
+ * The object to be serialized and truncated.
+ * @return A JSON representation of the object, truncated if necessary. Returns
+ * a placeholder string if serialization fails.
+ */
public static String truncateBody(Object responseBody) {
ObjectMapper objectMapper = new ObjectMapper();
try {
@@ -79,11 +254,21 @@ public static String truncateBody(Object responseBody) {
}
}
+ /**
+ * Truncates and concatenates form data.
+ *
+ * This method iterates over the entries in a {@link MultiValueMap}, truncates
+ * the values, and concatenates them into a single string representation.
+ *
+ *
+ * @param formData
+ * The form data to be truncated and concatenated.
+ */
private String truncateBody(MultiValueMap formData) {
StringBuilder messageResponse = new StringBuilder();
Set keys = formData.keySet();
for (String key : keys) {
- messageResponse.append(key + ":" + truncateBody(formData.get(key)));
+ messageResponse.append(key).append(":").append(truncateBody(formData.get(key)));
}
return messageResponse.toString();
}