docs: added docs

Author: zihluwang

devkit-core/src/main/java/com/onixbyte/devkit/core/exceptions/NotImplementedException.java

@@ -18,12 +18,13 @@
 package com.onixbyte.devkit.core.exceptions;
 
 /**
- * The {@code NotImplementedException} class is a custom runtime exception that represents a situation where a
- * particular method or functionality is not implemented or is currently unavailable in the codebase.
+ * The {@code NotImplementedException} class is a custom runtime exception that represents a
+ * situation where a particular method or functionality is not implemented or is currently
+ * unavailable in the codebase.
  * <p>
- * This exception is typically thrown when developers need to indicate that a specific part of the code is incomplete
- * or requires further implementation. It serves as a placeholder to highlight unfinished sections of the application
- * during development and testing phases.
+ * This exception is typically thrown when developers need to indicate that a specific part of the
+ * code is incomplete or requires further implementation. It serves as a placeholder to highlight
+ * unfinished sections of the application during development and testing phases.
  * <p>
  * Usage Example:
  * <pre>
@@ -57,7 +58,8 @@ public NotImplementedException(String message) {
     }
 
     /**
-     * Creates a new {@code NotImplementedException} with the specified error message and a cause for this exception.
+     * Creates a new {@code NotImplementedException} with the specified error message and a cause
+     * for this exception.
      *
      * @param message the error message associated with this exception
      * @param cause   the cause of this exception
@@ -76,8 +78,8 @@ public NotImplementedException(Throwable cause) {
     }
 
     /**
-     * Creates a new {@code NotImplementedException} with the specified error message, cause, suppression flag, and
-     * stack trace writable flag.
+     * Creates a new {@code NotImplementedException} with the specified error message, cause,
+     * suppression flag, and stack trace writable flag.
      *
      * @param message            the error message associated with this
      *                           exception

devkit-core/src/main/resources/logback.xml

@@ -17,8 +17,10 @@
   -->
 
 <configuration>
-    <property name="COLOURFUL_OUTPUT" value="%black(%date{'dd MMM, yyyy HH:mm:ss', Asia/Hong_Kong, en-UK}) %highlight(%-5level) %black(---) %black([%10.10t]) %cyan(%-20.20logger{20}) %black(:) %msg%n"/>
-    <property name="STANDARD_OUTPUT" value="%date{'dd MMM, yyyy HH:mm:ss', Asia/Hong_Kong, en-UK} %-5level %black(---) [%10.10t] %-20.20logger{20} : %msg%n"/>
+    <property name="COLOURFUL_OUTPUT"
+              value="%black(%date{'dd MMM, yyyy HH:mm:ss', Asia/Hong_Kong, en-UK}) %highlight(%-5level) %black(---) %black([%10.10t]) %cyan(%-20.20logger{20}) %black(:) %msg%n"/>
+    <property name="STANDARD_OUTPUT"
+              value="%date{'dd MMM, yyyy HH:mm:ss', Asia/Hong_Kong, en-UK} %-5level %black(---) [%10.10t] %-20.20logger{20} : %msg%n"/>
 
     <statusListener class="ch.qos.logback.core.status.NopStatusListener" />
     <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">

devkit-utils/src/main/java/com/onixbyte/devkit/utils/AesUtil.java

@@ -34,7 +34,35 @@
 import java.util.UUID;
 
 /**
- * {@link AesUtil} can help you encrypt and decrypt data with specified secret by AES algorithm.
+ * The {@link AesUtil} class provides utility methods for encrypting and decrypting data using the
+ * AES algorithm. This class supports both byte array and string data, and uses a specified secret
+ * key for encryption and decryption.
+ * <p>
+ * The utility methods in this class are useful for scenarios where data needs to be securely
+ * encrypted and decrypted.
+ * </p>
+ * 
+ * <p><b>Example usage:</b></p>
+ * <pre>
+ * {@code
+ * // Encrypting and decrypting byte array data
+ * byte[] secretKey = "43f72073956d4c81".getBytes(StandardCharsets.UTF_8);
+ * byte[] data = "Hello World".getBytes(StandardCharsets.UTF_8);
+ * byte[] encryptedData = AesUtil.encrypt(data, secretKey);
+ * byte[] decryptedData = AesUtil.decrypt(encryptedData, secretKey);
+ * System.out.println(new String(decryptedData, StandardCharsets.UTF_8)); // Output: Hello World
+ * 
+ * // Encrypting and decrypting string data
+ * String secret = "43f72073956d4c81";
+ * String encryptedString = AesUtil.encrypt("Hello World", secret);
+ * String decryptedString = AesUtil.decrypt(encryptedString, secret);
+ * System.out.println(decryptedString); // Output: Hello World
+ * 
+ * // Generating a random secret key
+ * String randomSecret = AesUtil.generateRandomSecret();
+ * System.out.println(randomSecret); // Output: A ramdomly generated 16-character long secret 
+ * }
+ * </pre>
  *
  * @author hubin@baomidou
  * @version 1.1.0
@@ -54,7 +82,7 @@ public static byte[] encrypt(byte[] data, byte[] secret) {
         try {
             var secretKeySpec = new SecretKeySpec(new SecretKeySpec(secret, AES).getEncoded(), AES);
             var cipher = Cipher.getInstance(AES_CBC_CIPHER);
-            cipher.init(Cipher.ENCRYPT_MODE, secretKeySpec, new IvParameterSpec(secret));
+            cipher.init(Cipher.ENCRYPT_MODE, secretKeySpec, new IvParameterSpec(secret)); // set IV to secret
             return cipher.doFinal(data);
         } catch (NoSuchAlgorithmException | NoSuchPaddingException | UnsupportedOperationException |
                  InvalidKeyException | InvalidAlgorithmParameterException | IllegalBlockSizeException |
@@ -78,7 +106,7 @@ public static byte[] decrypt(byte[] data, byte[] secret) {
         try {
             var secretKeySpec = new SecretKeySpec(new SecretKeySpec(secret, AES).getEncoded(), AES);
             var cipher = Cipher.getInstance(AES_CBC_CIPHER);
-            cipher.init(Cipher.DECRYPT_MODE, secretKeySpec, new IvParameterSpec(secret));
+            cipher.init(Cipher.DECRYPT_MODE, secretKeySpec, new IvParameterSpec(secret)); // set IV to secret
             return cipher.doFinal(data);
         } catch (NoSuchAlgorithmException | NoSuchPaddingException |
                  UnsupportedOperationException | InvalidKeyException |

devkit-utils/src/main/java/com/onixbyte/devkit/utils/BoolUtil.java

@@ -22,10 +22,25 @@
 import java.util.function.BooleanSupplier;
 
 /**
- * A util for boolean calculations.
+ * The {@link BoolUtil} class provides utility methods for boolean calculations.
+ * This class offers methods to perform logical operations such as AND, OR, and NOT on boolean values.
+ * <p>
+ * The utility methods in this class are useful for scenarios where multiple boolean values need to be
+ * evaluated together, and for simplifying complex boolean expressions.
+ * </p>
+ * 
+ * <p><b>Example usage:</b></p>
+ * <pre>
+ * {@code
+ * boolean result1 = BoolUtil.and(true, true, false); // false
+ * boolean result2 = BoolUtil.or(true, false, false); // true
+ * boolean result3 = BoolUtil.not(false); // true
+ * }
+ * </pre>
  *
- * @author shaoxinke
+ * @author zihluwang
  * @version 1.6.2
+ * @since 1.6.2
  */
 public final class BoolUtil {
 

devkit-utils/src/main/java/com/onixbyte/devkit/utils/BranchUtil.java

@@ -32,8 +32,7 @@
  * <p>
  * <b>Example:</b>
  * <pre>
- * // If you want to simplify an if (exp1 || exp2), you can use the
- * // following code:
+ * // If you want to simplify an if (exp1 || exp2), you can use the following code:
  * String r1 = BranchUtil.or(1 == 1, 2 == 1)
  *     .handle(() -> "1 is equal to 1 or 2 is equal to 1.");
  *
@@ -49,8 +48,7 @@
  *     }, () -> {
  *         // do something
  *     });
- * // If you only need an if branch, you can remove the second Supplier
- * // instance.
+ * // If you only need an if branch, you can remove the second Supplier instance.
  *
  * // To check if all boolean expressions are true, use the 'and' method:
  * BranchUtil.and(1 == 1, 2 == 1)

devkit-utils/src/main/java/com/onixbyte/devkit/utils/HashUtil.java

@@ -55,8 +55,7 @@
  * The above examples demonstrate how to use the {@code HashUtil} class to calculate hash values
  * for a given string using different algorithms.
  * <p>
- * <b>Note:</b>
- * The hash functions provided by the HashUtil class are one-way hash functions, meaning the
+ * The hash functions provided by the {@link HashUtil} are one-way hash functions, meaning the
  * original data cannot be retrieved from the hash value. These hash functions are commonly used
  * for data integrity checks and password storage, but they should not be used for
  * encryption purposes.

devkit-utils/src/main/java/com/onixbyte/devkit/utils/MapUtil.java

@@ -24,11 +24,61 @@
 import java.util.Optional;
 
 /**
- * {@code MapUtil} is a utility class that provides methods for converting objects to maps and maps
- * to objects.
+ * The {@link MapUtil} class provides utility methods for converting between objects and maps.
+ * This class leverages the {@link ObjectMapAdapter} interface to perform the conversions.
  * <p>
- * Note: Since version 1.4.2, this util class removed reflection API and transferred to a safer API.
- * Please see documentation for more information.
+ * The utility methods in this class are useful for scenarios where objects need to be represented as maps for
+ * serialization, deserialization, or other purposes.
+ * </p>
+ * 
+ * <p><b>Example usage:</b></p>
+ * <pre>
+ * {@code
+ * public class User {
+ *     private String name;
+ *     private int age;
+ *     
+ *     // getters and setters
+ * }
+ * 
+ * public class UserMapAdapter implements ObjectMapAdapter<User> {
+ *     @Override
+ *     public Map<String, Object> toMap(User user) {
+ *         Map<String, Object> map = new HashMap<>();
+ *         map.put("name", user.getName());
+ *         map.put("age", user.getAge());
+ *         return map;
+ *     }
+ * 
+ *     @Override
+ *     public User fromMap(Map<String, Object> map) {
+ *         User user = new User();
+ *         user.setName((String) map.get("name"));
+ *         user.setAge((Integer) map.get("age"));
+ *         return user;
+ *     }
+ * }
+ * 
+ * public class Example {
+ *     public static void main(String[] args) {
+ *         User user = new User();
+ *         user.setName("John");
+ *         user.setAge(30);
+ *         
+ *         UserMapAdapter adapter = new UserMapAdapter();
+ *         
+ *         // Convert object to map
+ *         Map<String, Object> userMap = MapUtil.objectToMap(user, adapter);
+ *         System.out.println(userMap); // Output: {name=John, age=30}
+ *         
+ *         // Convert map to object
+ *         User newUser = MapUtil.mapToObject(userMap, adapter);
+ *         System.out.println(newUser.getName()); // Output: John
+ *         System.out.println(newUser.getAge());  // Output: 30
+ *     }
+ * }
+ * }
+ * </pre>
  *
  * @author zihluwang
  * @version 1.7.0

devkit-utils/src/main/java/com/onixbyte/devkit/utils/ObjectMapAdapter.java

@@ -20,9 +20,44 @@
 import java.util.Map;
 
 /**
- * Adapts an Object to a Map, making conversion between Map and Object much more safe.
+ * The {@link ObjectMapAdapter} interface provides methods to convert between objects and maps.
+ * This interface is useful for scenarios where objects need to be represented as maps for
+ * serialization, deserialization, or other purposes.
  *
- * @param <T> field type
+ * <p>Implementations of this interface should provide the logic to convert an object of type {@code T}
+ * to a {@link Map} and vice versa.</p>
+ *
+ * <p><b>Example usage:</b></p>
+ * <pre>
+ * {@code
+ * public class User {
+ *     private String name;
+ *     private int age;
+ *     
+ *     // getters and setters
+ * }
+ * 
+ * public class UserMapAdapter implements ObjectMapAdapter<User> {
+ *     @Override
+ *     public Map<String, Object> toMap(User user) {
+ *         Map<String, Object> map = new HashMap<>();
+ *         map.put("name", user.getName());
+ *         map.put("age", user.getAge());
+ *         return map;
+ *     }
+ * 
+ *     @Override
+ *     public User fromMap(Map<String, Object> map) {
+ *         User user = new User();
+ *         user.setName((String) map.get("name"));
+ *         user.setAge((Integer) map.get("age"));
+ *         return user;
+ *     }
+ * }
+ * }
+ * </pre>
+ *
+ * @param <T> the type of the object to be converted
  * @author zihluwang
  * @version 1.7.0
  * @since 1.4.2
@@ -40,7 +75,7 @@ public interface ObjectMapAdapter<T> {
     /**
      * Convert a Map to an object.
      *
-     * @param map the map that will be converted to Object
+     * @param map the map that will be converted to an object
      * @return the object that is converted from the Map
      */
     T toObject(Map<String, Object> map);

devkit-utils/src/main/java/com/onixbyte/devkit/utils/package-info.java

@@ -22,7 +22,6 @@
  * dev-utils, which contains a collection of common utility classes commonly
  * used in all Java Application development.
  *
- * @author Zihlu Wang
  * @since 1.0.0
  */
 package com.onixbyte.devkit.utils;

devkit-utils/src/main/resources/logback.xml

@@ -17,8 +17,10 @@
   -->
 
 <configuration>
-    <property name="COLOURFUL_OUTPUT" value="%black(%date{'dd MMM, yyyy HH:mm:ss', Asia/Hong_Kong, en-UK}) %highlight(%-5level) %black(---) %black([%10.10t]) %cyan(%-20.20logger{20}) %black(:) %msg%n"/>
-    <property name="STANDARD_OUTPUT" value="%date{'dd MMM, yyyy HH:mm:ss', Asia/Hong_Kong, en-UK} %-5level %black(---) [%10.10t] %-20.20logger{20} : %msg%n"/>
+    <property name="COLOURFUL_OUTPUT"
+              value="%black(%date{'dd MMM, yyyy HH:mm:ss', Asia/Hong_Kong, en-UK}) %highlight(%-5level) %black(---) %black([%10.10t]) %cyan(%-20.20logger{20}) %black(:) %msg%n"/>
+    <property name="STANDARD_OUTPUT"
+              value="%date{'dd MMM, yyyy HH:mm:ss', Asia/Hong_Kong, en-UK} %-5level %black(---) [%10.10t] %-20.20logger{20} : %msg%n"/>
 
     <statusListener class="ch.qos.logback.core.status.NopStatusListener" />
     <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">