feat: commons task. added more detailed documentation for annotation …

…module.

annotation/README.md

@@ -50,27 +50,45 @@ The `SimplixSerializerSerializableAutoRegister` annotation is used to mark the c
 annotation. The `CustomAnnotationProcessor` interface is used to determine the processing method.
 
 This is very simple, right? But now that the definition is complete, how does this all work?
+What if we only want to process a few specific annotations?
 
 ```java
-
 @FairyLaunch
-@InjectableComponent
-public class AnnotationLauncher extends Plugin {
+public class Launcher extends Plugin {
     @Autowired
     private AnnotationProcessingServiceInterface annotationProcessingService;
 
     @Override
     public void onPluginEnable() {
-        String basePackage = this.getClass().getPackageName();
-        annotationProcessingService.processAnnotations(basePackage, false, this.getClassLoader());
+        List<String> basePackages = List.of(
+                // Packets expected to be processed
+                "org.example",
+
+                /*
+                 * The package where the Processor of the annotation to be processed is located
+                 * e.g. "me.qwqdev.library.configuration.serialize.annotation.SimplixSerializerSerializableAutoRegister"
+                 * so the package name is "me.qwqdev.library.configuration.serialize.annotation"
+                 */
+                "me.qwqdev.library.configuration.serialize.annotation"
+        );
+
+        annotationProcessingService.processAnnotations(
+                basePackages,
+
+                // should Processors dependency injection by Fairy IoC
+                false,
+
+                /*
+                 * All ClassLoaders used for basePackages scanning
+                 * Here, we need to pass in not only the ClassLoader of the current class, 
+                 * but also the ClassLoader of the Launcher when we need to use the Processor that comes with legacy-lands-library
+                 */
+                this.getClassLoader(),
+                ConfigurationLauncher.class.getClassLoader() // configuration moduel's class loader
+                // or CommonsLauncher.class.getClassLoader(), its commons module's class loader
+        );
     }
 }
 ```
 
-We only need to get `AnnotationProcessingService` through dependency injection and simply call the method~
-Let's focus on `annotationProcessingService.processAnnotations(basePackage, false, this.getClassLoader())`.
-
-The first parameter is the package we need to scan.
-The second is whether the processed class should be injected into the singleton mode by the Fairy framework. If it is
-false, it will be created through parameterless reflection.
-The third is the classloader that needs to be scanned.
+Let's look at this, we just need to get the `AnnotationProcessingService` through dependency injection and then call `processAnnotations`.

annotation/src/main/java/me/qwqdev/library/annotation/service/AnnotationProcessingService.java

@@ -1,5 +1,6 @@
 package me.qwqdev.library.annotation.service;
 
+import com.google.common.collect.Sets;
 import io.fairyproject.container.Containers;
 import io.fairyproject.container.InjectableComponent;
 import io.fairyproject.log.Log;
@@ -10,6 +11,7 @@
 import java.lang.reflect.InvocationTargetException;
 import java.net.URL;
 import java.util.Collection;
+import java.util.List;
 import java.util.Set;
 
 /**
@@ -43,6 +45,20 @@ public void processAnnotations(String basePackage, boolean fromFairyIoCSingleton
         processAnnotations(ClasspathHelper.forPackage(basePackage, classLoader), fromFairyIoCSingleton);
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * @param basePackages          {@inheritDoc}
+     * @param fromFairyIoCSingleton {@inheritDoc}
+     * @param classLoader           {@inheritDoc}
+     */
+    @Override
+    public void processAnnotations(List<String> basePackages, boolean fromFairyIoCSingleton, ClassLoader... classLoader) {
+        Collection<URL> urls = Sets.newHashSet();
+        basePackages.forEach(basePackage -> urls.addAll(ClasspathHelper.forPackage(basePackage, classLoader)));
+        processAnnotations(urls, fromFairyIoCSingleton);
+    }
+
     /**
      * {@inheritDoc}
      *

annotation/src/main/java/me/qwqdev/library/annotation/service/AnnotationProcessingServiceInterface.java

@@ -2,6 +2,7 @@
 
 import java.net.URL;
 import java.util.Collection;
+import java.util.List;
 
 /**
  * Service interface for processing annotations using custom annotation processors.
@@ -28,6 +29,21 @@ public interface AnnotationProcessingServiceInterface {
      */
     void processAnnotations(String basePackage, boolean fromFairyIoCSingleton, ClassLoader... classLoader);
 
+    /**
+     * Processes annotations within the specified list of base packages using the default annotation processors.
+     *
+     * <p>This method scans the specified base packages and their sub-packages for classes annotated with specific
+     * annotations, and then processes them using default annotation processors. The method supports scanning
+     * multiple base packages and allows for optional class loaders to be specified for classpath scanning.
+     *
+     * @param basePackages          the list of base packages to scan for annotated classes
+     * @param fromFairyIoCSingleton whether handlerClass should be injected into a singleton by the Fairy framework
+     *                              If false, it will be created by reflection without parameters,
+     *                              but it still supports setter injection with Fairy {@link io.fairyproject.container.Autowired} annotation
+     * @param classLoader           optional class loaders to use for classpath scanning; if not provided, the default class loader is used
+     */
+    void processAnnotations(List<String> basePackages, boolean fromFairyIoCSingleton, ClassLoader... classLoader);
+
     /**
      * Processes annotations within the specified collection of URLs using default annotation processors.
      *

commons/README.md

@@ -53,4 +53,41 @@ public class Test {
         InjectorFactory.createVarHandleReflectionInjector().inject(Test.class);
     }
 }
-```
+```
+
+### [Task](src/main/java/me/qwqdev/library/commons/task)
+
+The [TaskInterface](src/main/java/me/qwqdev/library/commons/task/TaskInterface.java)
+simplifies task scheduling by providing convenience methods with consistent naming and argument order with the Fairy Framework (MCScheduler)[https://docs.fairyproject.io/core/minecraft/scheduler].
+
+```java
+public class Example {
+    public static void main(String[] args) {
+        TaskInterface taskInterface = new TaskInterface() {
+            @Override
+            public ScheduledTask<?> start() {
+                // This is a simple example of a task that prints "Hello, world!" every second.
+                return scheduleAtFixedRate(() -> System.out.println("Hello, world!"), 0, 1000);
+            }
+        };
+
+        // start the task
+        taskInterface.start();
+    }
+}
+```
+
+It also provides [TaskAutoStartAnnotation](src/main/java/me/qwqdev/library/commons/task/annotation/TaskAutoStartAnnotation.java) to handle some tasks that need to be automatically started at a specific time. When there are many tasks to start, annotation automation will help us avoid manually managing the creation and calling of these instances, thereby simplifying the code.
+
+```java
+@TaskAutoStartAnnotation(isFromFairyIoC = false)
+public class Example implements TaskInterface {
+    @Override
+    public ScheduledTask<?> start() {
+        // This is a simple example of a task that prints "Hello, world!" every second.
+        return scheduleAtFixedRate(() -> System.out.println("Hello, world!"), 0, 1000);
+    }
+}
+```
+
+As for how to make annotation processors work on your own plugins, please see the [annotation](../annotation/README.md) module.

commons/src/main/java/me/qwqdev/library/commons/injector/VarHandleReflectionInjector.java

@@ -9,7 +9,7 @@
 import java.lang.reflect.Method;
 
 /**
- * Utility class for injecting {@link VarHandle} instances into static fields annotated with {@link VarHandleAutoInjection}.
+ * Injector class for injecting {@link VarHandle} instances into static fields annotated with {@link VarHandleAutoInjection}.
  * This class automatically injects {@link VarHandle} instances into the static fields of a class based on the annotations
  * present on those fields.
  *
@@ -46,8 +46,8 @@
 public class VarHandleReflectionInjector implements StaticInjectorInterface {
     /**
      * {@inheritDoc}
-     * <p>
-     * Injects {@link VarHandle} instances into static fields of the given class that are annotated with
+     *
+     * <p>Injects {@link VarHandle} instances into static fields of the given class that are annotated with
      * {@link VarHandleAutoInjection}. This method uses reflection to find the appropriate {@link VarHandle}
      * for each annotated field and assigns it to the field.
      *