java docs

Author: hoangtien2k3

pom.xml

@@ -11,7 +11,7 @@
 
     <groupId>io.github.hoangtien2k3</groupId>
     <artifactId>fw-commons</artifactId>
-    <version>${version.lib}</version>
+    <version>1.1.0</version>
     <packaging>jar</packaging>
     <name>fw-commons</name>
     <description>a commons java tool lib with spring boot framework</description>
@@ -49,7 +49,6 @@
 
     <properties>
         <java.version>21</java.version>
-        <version.lib>1.1.0</version.lib>
         <micrometer.tracing.version>1.3.1</micrometer.tracing.version>
         <micrometer.registry.version>1.13.1</micrometer.registry.version>
         <micrometer.core.version>1.13.1</micrometer.core.version>
@@ -66,13 +65,13 @@
         <spotless.version>2.43.0</spotless.version>
         <file.encoding>UTF-8</file.encoding>
         <!-- Plugins version -->
-        <maven-compiler-plugin.version>3.11.0</maven-compiler-plugin.version>
-        <maven-surefire-plugin.version>3.1.2</maven-surefire-plugin.version>
-        <central-publishing-maven-plugin.version>0.3.0</central-publishing-maven-plugin.version>
-        <nexus-staging-maven-plugin.version>1.6.7</nexus-staging-maven-plugin.version>
-        <maven-gpg-plugin.version>1.5</maven-gpg-plugin.version>
-        <maven-javadoc-plugin.version>2.9.1</maven-javadoc-plugin.version>
-        <maven-source-plugin.version>2.2.1</maven-source-plugin.version>
+        <maven-compiler-plugin.version>3.13.0</maven-compiler-plugin.version>
+        <maven-surefire-plugin.version>3.4.0</maven-surefire-plugin.version>
+        <central-publishing-maven-plugin.version>0.5.0</central-publishing-maven-plugin.version>
+        <nexus-staging-maven-plugin.version>1.7.0</nexus-staging-maven-plugin.version>
+        <maven-gpg-plugin.version>3.2.5</maven-gpg-plugin.version>
+        <maven-javadoc-plugin.version>3.8.0</maven-javadoc-plugin.version>
+        <maven-source-plugin.version>3.3.1</maven-source-plugin.version>
     </properties>
 
     <dependencyManagement>
@@ -192,7 +191,7 @@
         <dependency>
             <groupId>org.json</groupId>
             <artifactId>json</artifactId>
-            <version>20231013</version>
+            <version>20240303</version>
         </dependency>
         <dependency>
             <groupId>javax.xml.bind</groupId>
@@ -437,6 +436,13 @@
                     <javadocExecutable>${java.home}/bin/javadoc</javadocExecutable>
                 </configuration>
                 <executions>
+                    <execution>
+                        <id>generate-javadocs</id>
+                        <phase>prepare-package</phase>
+                        <goals>
+                            <goal>javadoc</goal>
+                        </goals>
+                    </execution>
                     <execution>
                         <id>attach-javadocs</id>
                         <goals>
@@ -507,6 +513,7 @@
                             <spacesPerTab>2</spacesPerTab>
                         </indent>
                         <removeUnusedImports/>
+                        <palantirJavaFormat/>
                         <licenseHeader>
                             <content><![CDATA[
 /*

src/main/java/io/hoangtien2k3/commons/FwCommonsApplication.java

@@ -0,0 +1,40 @@
+/*
+ * Copyright 2024 author - Hoàng Anh Tiến
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+ */
+package io.hoangtien2k3.commons;
+
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+import org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration;
+import org.springframework.boot.autoconfigure.jdbc.DataSourceTransactionManagerAutoConfiguration;
+import org.springframework.boot.autoconfigure.orm.jpa.HibernateJpaAutoConfiguration;
+import org.springframework.boot.autoconfigure.security.servlet.SecurityAutoConfiguration;
+import org.springframework.context.annotation.ComponentScan;
+import org.springframework.context.annotation.ImportResource;
+
+@SpringBootApplication(
+        exclude = {
+            DataSourceAutoConfiguration.class,
+            DataSourceTransactionManagerAutoConfiguration.class,
+            HibernateJpaAutoConfiguration.class,
+            SecurityAutoConfiguration.class,
+        })
+@ComponentScan(basePackages = {"io.hoangtien2k3.commons.*"})
+@ImportResource({"classpath*:applicationContext.xml"})
+// @EnableDiscoveryClient
+public class FwCommonsApplication {
+    public static void main(String[] args) {
+        SpringApplication.run(FwCommonsApplication.class, args);
+    }
+}

src/main/java/io/hoangtien2k3/commons/annotations/LocalCache.java

@@ -19,12 +19,55 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * Annotation for specifying caching behavior on methods.
+ *
+ * <p>
+ * This annotation allows methods to utilize caching by specifying cache
+ * parameters. The caching behavior is controlled by the
+ * {@code durationInMinute}, {@code maxRecord}, and {@code autoCache}
+ * attributes.
+ * </p>
+ *
+ * <ul>
+ * <li><b>durationInMinute:</b> Specifies the duration (in minutes) for which
+ * the cache entries should be retained. The default value is 120 minutes.</li>
+ * <li><b>maxRecord:</b> Defines the maximum number of cache records to store.
+ * The default value is 1000 records.</li>
+ * <li><b>autoCache:</b> Indicates whether caching should be automatically
+ * applied. If {@code true}, caching is enabled without additional
+ * configuration. The default value is {@code false}.</li>
+ * </ul>
+ *
+ * <p>
+ * This annotation should be applied to methods where caching is desired. The
+ * cache implementation will use the specified parameters to manage caching
+ * behavior, including cache expiration and size limits.
+ * </p>
+ */
 @Target(ElementType.METHOD)
 @Retention(RetentionPolicy.RUNTIME)
 public @interface LocalCache {
-  int durationInMinute() default 120;
 
-  int maxRecord() default 1000;
+    /**
+     * The duration (in minutes) for which cache entries should be retained.
+     *
+     * @return the cache duration in minutes
+     */
+    int durationInMinute() default 120;
+
+    /**
+     * The maximum number of cache records to store.
+     *
+     * @return the maximum number of cache records
+     */
+    int maxRecord() default 1000;
 
-  boolean autoCache() default false;
+    /**
+     * Whether caching should be automatically applied.
+     *
+     * @return {@code true} if caching should be automatically applied;
+     *         {@code false} otherwise
+     */
+    boolean autoCache() default false;
 }

src/main/java/io/hoangtien2k3/commons/annotations/LogPerformance.java

@@ -22,13 +22,13 @@
 @Target({ElementType.METHOD, ElementType.TYPE})
 @Retention(RetentionPolicy.RUNTIME)
 public @interface LogPerformance {
-  String logType() default "";
+    String logType() default "";
 
-  String actionType() default "";
+    String actionType() default "";
 
-  boolean logOutput() default true;
+    boolean logOutput() default true;
 
-  boolean logInput() default true;
+    boolean logInput() default true;
 
-  String title() default "";
+    String title() default "";
 }

src/main/java/io/hoangtien2k3/commons/annotations/cache/CacheAspect.java

@@ -15,6 +15,8 @@
 package io.hoangtien2k3.commons.annotations.cache;
 
 import com.github.benmanes.caffeine.cache.Cache;
+import io.hoangtien2k3.commons.annotations.LocalCache;
+import java.util.Optional;
 import lombok.extern.slf4j.Slf4j;
 import org.aspectj.lang.ProceedingJoinPoint;
 import org.aspectj.lang.annotation.Around;
@@ -27,32 +29,72 @@
 import reactor.core.publisher.Mono;
 import reactor.core.publisher.Signal;
 
-import java.util.Optional;
-
+/**
+ * Aspect for managing cache operations based on the {@link LocalCache}
+ * annotation.
+ *
+ * <p>
+ * This aspect intercepts method calls annotated with {@link LocalCache} and
+ * handles caching of method results. It uses a cache store to retrieve results
+ * if they are present, and if not, it proceeds with the method execution,
+ * stores the result in the cache, and then returns it.
+ * </p>
+ *
+ * <p>
+ * The cache key is generated based on the method arguments, and the cache is
+ * identified using the method name and class name of the target object.
+ * </p>
+ *
+ * @see LocalCache
+ * @see CacheStore
+ * @see SimpleKeyGenerator
+ * @see CacheMono
+ * @see Signal
+ */
 @Aspect
 @Configuration
 @Slf4j
 public class CacheAspect {
-  @Pointcut("@annotation(io.hoangtien2k3.commons.annotations.LocalCache)")
-  private void processAnnotation() {
-  }
 
-  @Around("processAnnotation()")
-  public Object aroundAdvice(ProceedingJoinPoint joinPoint) throws Throwable {
-    Object[] args = joinPoint.getArgs();
-    Object key = SimpleKeyGenerator.generateKey(args);
-    String name = ClassUtils.getUserClass(joinPoint.getTarget().getClass()).getSimpleName() + "."
-        + joinPoint.getSignature().getName();
-    Cache cache = CacheStore.getCache(name);
+    /**
+     * Pointcut for methods annotated with {@link LocalCache}.
+     */
+    @Pointcut("@annotation(io.hoangtien2k3.commons.annotations.LocalCache)")
+    private void processAnnotation() {}
+
+    /**
+     * Around advice for caching method results.
+     *
+     * <p>
+     * This method intercepts the execution of a method annotated with
+     * {@link LocalCache}, retrieves the result from the cache if available, or
+     * proceeds with the method execution if the result is not cached. The result is
+     * then stored in the cache for future use.
+     * </p>
+     *
+     * @param joinPoint
+     *            the join point representing the intercepted method call
+     * @return the result of the method call, either from the cache or from the
+     *         method execution
+     * @throws Throwable
+     *             if the method call or caching operation fails
+     */
+    @Around("processAnnotation()")
+    public Object aroundAdvice(ProceedingJoinPoint joinPoint) throws Throwable {
+        Object[] args = joinPoint.getArgs();
+        Object key = SimpleKeyGenerator.generateKey(args);
+        String name = ClassUtils.getUserClass(joinPoint.getTarget().getClass()).getSimpleName() + "."
+                + joinPoint.getSignature().getName();
+        Cache cache = CacheStore.getCache(name);
 
-    return CacheMono.lookup(k -> Mono.justOrEmpty(cache.getIfPresent(key)).map(Signal::next), key)
-        .onCacheMissResume((Mono<Object>) joinPoint.proceed(args))
-        .andWriteWith((k, sig) -> Mono.fromRunnable(() -> {
-          if (sig != null && sig.get() != null) {
-            if (!(sig.get() instanceof Optional && ((Optional) sig.get()).isEmpty())) {
-              cache.put(k, sig.get());
-            }
-          }
-        }));
-  }
+        return CacheMono.lookup(k -> Mono.justOrEmpty(cache.getIfPresent(key)).map(Signal::next), key)
+                .onCacheMissResume((Mono<Object>) joinPoint.proceed(args))
+                .andWriteWith((k, sig) -> Mono.fromRunnable(() -> {
+                    if (sig != null && sig.get() != null) {
+                        if (!(sig.get() instanceof Optional && ((Optional) sig.get()).isEmpty())) {
+                            cache.put(k, sig.get());
+                        }
+                    }
+                }));
+    }
 }