Merge pull request #51 from onixbyte/develop

docs: use unified comments on private constructor

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

@@ -158,7 +158,7 @@ public final class AesUtil {
     }
 
     /**
-     * Private constructor will protect this class from being instantiated.
+     * Private constructor to prevent instantiation of this utility class.
      */
     private AesUtil() {
     }

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

@@ -109,7 +109,7 @@ public final class Base64Util {
     }
 
     /**
-     * Private constructor to prevent instantiation of the class.
+     * Private constructor to prevent instantiation of this utility class.
      */
     private Base64Util() {
     }

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

@@ -98,7 +98,7 @@ public final class BoolUtil {
     }
 
     /**
-     * Private constructor prevent from being initialised.
+     * Private constructor to prevent instantiation of this utility class.
      */
     private BoolUtil() {}
 

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

@@ -0,0 +1,112 @@
+/*
+ * Copyright (C) 2024-2025 OnixByte.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.onixbyte.devkit.utils;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.List;
+import java.util.Objects;
+import java.util.function.Supplier;
+
+/**
+ * A utility class providing static methods for manipulating collections.
+ *
+ * @author zihluwang
+ */
+public final class CollectionUtil {
+
+    private static final Logger log = LoggerFactory.getLogger(CollectionUtil.class);
+
+    /**
+     * Private constructor to prevent instantiation of this utility class.
+     */
+    private CollectionUtil() {
+    }
+
+    /**
+     * Splits a collection into a list of sub-collections, each with a maximum size specified by
+     * the caller.
+     * <p>
+     * This method takes an original collection and divides it into smaller sub-collections,
+     * ensuring that each sub-collection contains no more than the specified maximum size. If the
+     * original collection's size is less than or equal to the maximum size, it is returned as a
+     * single sub-collection. The sub-collections are created using the provided collection factory.
+     *
+     * @param <T>                the type of elements in the collection
+     * @param <C>                the type of the collection, which must extend {@link Collection}
+     * @param originalCollection the collection to be split into sub-collections
+     * @param maxSize            the maximum number of elements allowed in each sub-collection
+     * @param collectionFactory  a supplier that creates new instances of the sub-collection type
+     * @return a list of sub-collections, each containing up to {@code maxSize} elements
+     * @throws IllegalArgumentException if {@code originalCollection} is {@code null},
+     *                                  {@code maxSize} is less than zero, or
+     *                                  {@code collectionFactory} is {@code null}
+     */
+    public static <T, C extends Collection<T>> List<C> chunk(C originalCollection,
+                                                             int maxSize,
+                                                             Supplier<C> collectionFactory) {
+        // check inputs
+        if (Objects.isNull(originalCollection)) {
+            throw new IllegalArgumentException("Collection must not be null.");
+        }
+
+        if (maxSize < 0) {
+            throw new IllegalArgumentException("maxSize must greater than 0.");
+        }
+
+        if (Objects.isNull(collectionFactory)) {
+            throw new IllegalArgumentException("Factory method cannot be null.");
+        }
+
+        var result = new ArrayList<C>();
+        var size = originalCollection.size();
+
+        // if original collection is empty or the size less than maxSize, return it as a single
+        // sub collection
+        if (size <= maxSize) {
+            var singleCollection = collectionFactory.get();
+            singleCollection.addAll(originalCollection);
+            result.add(singleCollection);
+            return result;
+        }
+
+        // use iterator to split the given collection
+        var iter = originalCollection.iterator();
+        var count = 0;
+        var currentSubCollection = collectionFactory.get();
+
+        while (iter.hasNext()) {
+            var element = iter.next();
+            currentSubCollection.add(element);
+            count++;
+
+            // add sub collection to result when current sub collection reached maxSize or
+            // collection traverse is completed
+            if (count % maxSize == 0 || !iter.hasNext()) {
+                result.add(currentSubCollection);
+                currentSubCollection = collectionFactory.get();
+            }
+        }
+
+        return result;
+    }
+
+}

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

@@ -229,7 +229,7 @@ public final class HashUtil {
     }
 
     /**
-     * Private constructor will protect this class from being instantiated.
+     * Private constructor to prevent instantiation of this utility class.
      */
     private HashUtil() {
     }

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

@@ -19,25 +19,77 @@ package com.onixbyte.devkit.utils;
 
 import java.util.ArrayList;
 import java.util.List;
+import java.util.Objects;
+import java.util.function.Supplier;
 
 /**
- * A utility class for splitting a List into multiple sub lists, where each sublist has a maximum
+ * A utility class providing static methods for manipulating lists.
- * number of elements specified by the user.
  *
  * @author siujamo
+ * @author zihluwang
  */
 public final class ListUtil {
 
     /**
      * Private constructor to prevent instantiation of this utility class.
-     * <p>
-     * This class provides static methods for list manipulation and is not intended to be
-     * instantiated. The private constructor ensures that no instances can be created, enforcing
-     * the utility nature of the class.
      */
     private ListUtil() {
     }
 
+    /**
+     * Splits a given List into a List of sub lists, where each sublist contains at most
+     * {@code maxSize} elements. The original list is not modified, and new sub lists are created
+     * to hold the partitioned data.
+     * <p>
+     * If the original list's size is less than or equal to {@code maxSize}, a single sublist
+     * containing all elements is returned. If the list is empty, an empty list of sub lists
+     * is returned.
+     *
+     * @param <T>          the type of elements in the list
+     * @param originalList the list to be split, must not be null
+     * @param maxSize      the maximum number of elements in each sublist, must be positive
+     * @param listFactory  list factory
+     * @return a List of sub lists, where each sublist has at most {@code maxSize} elements
+     * @throws IllegalArgumentException if {@code originalList} is null or {@code maxSize} is less
+     *                                  than or equal to 0
+     */
+    public static <T> List<List<T>> chunk(List<T> originalList, int maxSize, Supplier<List<T>> listFactory) {
+        // check input
+        if (Objects.isNull(originalList)) {
+            throw new IllegalArgumentException("List cannot be null");
+        }
+
+        if (maxSize <= 0) {
+            throw new IllegalArgumentException("Max size should be greater than 0");
+        }
+
+        if (Objects.isNull(listFactory)) {
+            throw new IllegalArgumentException("List factory cannot be null");
+        }
+
+        var result = new ArrayList<List<T>>();
+        var size = originalList.size();
+
+        // if the original list is empty or smaller than maxSize, return it as a single sublist
+        if (size <= maxSize) {
+            var singleSubList = listFactory.get();
+            singleSubList.addAll(originalList);
+            result.add(singleSubList);
+            return result;
+        }
+
+        // split the list
+        for (var i = 0; i < size; i += maxSize) {
+            var end = Math.min(i + maxSize, size); // ensure not to exceed list length
+            var subList = originalList.subList(i, end);
+            var subListWrapper = listFactory.get();
+            subListWrapper.addAll(subList);
+            result.add(subListWrapper); // create a new list to avoid reference issues
+        }
+
+        return result;
+    }
+
     /**
      * Splits a given List into a List of sub lists, where each sublist contains at most
      * {@code maxSize} elements. The original list is not modified, and new sub lists are created
@@ -53,30 +105,10 @@ public final class ListUtil {
      * @return a List of sub lists, where each sublist has at most {@code maxSize} elements
      * @throws IllegalArgumentException if {@code originalList} is null or {@code maxSize} is less
      *                                  than or equal to 0
+     * @see #chunk(List, int, Supplier)
      */
-    public static <T> List<List<T>> splitList(List<T> originalList, int maxSize) {
+    public static <T> List<List<T>> chunk(List<T> originalList, int maxSize) {
-        // check input
+        return chunk(originalList, maxSize, ArrayList::new);
-        if (originalList == null || maxSize <= 0) {
-            throw new IllegalArgumentException("List cannot be null and maxSize must be positive");
-        }
-
-        var result = new ArrayList<List<T>>();
-        var size = originalList.size();
-
-        // if the original list is empty or smaller than maxSize, return it as a single sublist
-        if (size <= maxSize) {
-            result.add(new ArrayList<>(originalList));
-            return result;
-        }
-
-        // split the list
-        for (var i = 0; i < size; i += maxSize) {
-            var end = Math.min(i + maxSize, size); // ensure not to exceed list length
-            List<T> subList = originalList.subList(i, end);
-            result.add(new ArrayList<>(subList)); // create a new list to avoid reference issues
-        }
-
-        return result;
     }
 
 }

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

@@ -113,7 +113,7 @@ public final class MapUtil {
     }
 
     /**
-     * Private constructor prevent class being instantiated.
+     * Private constructor to prevent instantiation of this utility class.
      */
     private MapUtil() {
     }

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

@@ -37,7 +37,7 @@ public final class RangeUtil {
     private final static Logger log = LoggerFactory.getLogger(RangeUtil.class);
 
     /**
-     * Private constructor prevent class being instantiated.
+     * Private constructor to prevent instantiation of this utility class.
      */
     private RangeUtil() {
     }

map-util-unsafe/src/main/java/com/onixbyte/devkit/utils/unsafe/ReflectMapUtil.java

@@ -240,7 +240,7 @@ public final class ReflectMapUtil {
     }
 
     /**
-     * Private constructor will protect this class from being instantiated.
+     * Private constructor to prevent instantiation of this utility class.
      */
     private ReflectMapUtil() {
     }

num4j/src/main/java/com/onixbyte/nums/PercentileCalculator.java

@@ -54,7 +54,7 @@ public final class PercentileCalculator {
     private final static Logger log = LoggerFactory.getLogger(PercentileCalculator.class);
 
     /**
-     * Private constructor prevents from being initialised.
+     * Private constructor to prevent instantiation of this utility class.
      */
     private PercentileCalculator() {
     }

num4j/src/main/java/com/onixbyte/nums/model/QuartileBounds.java

@@ -86,8 +86,7 @@ public record QuartileBounds(
         private Double lowerBound;
 
         /**
-         * Private constructor for {@code Builder}, ensuring it can only be instantiated through the
+         * Private constructor to prevent instantiation of this utility class.
-         * {@link QuartileBounds#builder()} method.
          */
         private Builder() {
         }

simple-jwt-authzero/src/main/java/com/onixbyte/simplejwt/authzero/AuthzeroTokenResolver.java

@@ -155,8 +155,7 @@ public class AuthzeroTokenResolver implements TokenResolver<DecodedJWT> {
         private ECPublicKey publicKey;
 
         /**
-         * Private constructor prevents this class being initialised at somewhere it should not
+         * Private constructor to prevent instantiation of this utility class.
-         * be initialised.
          */
         private Builder() {
         }
@@ -643,7 +642,7 @@ public class AuthzeroTokenResolver implements TokenResolver<DecodedJWT> {
     );
 
     /**
-     * Private constructor prevent this class being initialised mistakenly.
+     * Private constructor to prevent instantiation of this utility class.
      *
      * @param jtiCreator   a creator that can create JWT id
      * @param algorithm    an algorithm to sign this JWT

simple-jwt-facade/src/main/java/com/onixbyte/simplejwt/SecretCreator.java

@@ -128,7 +128,7 @@ public final class SecretCreator {
     }
 
     /**
-     * Private constructor will protect this class from being instantiated.
+     * Private constructor to prevent instantiation of this utility class.
      */
     private SecretCreator() {
     }

simple-jwt-facade/src/main/java/com/onixbyte/simplejwt/constants/PredefinedKeys.java

@@ -90,7 +90,7 @@ public final class PredefinedKeys {
             List.of(ISSUER, SUBJECT, AUDIENCE, EXPIRATION_TIME, NOT_BEFORE, ISSUED_AT, JWT_ID);
 
     /**
-     * Private constructor will protect this class from being instantiated.
+     * Private constructor to prevent instantiation of this utility class.
      */
     private PredefinedKeys() {
     }