Merge pull request #81 from onixbyte/release/v3.1.0

common-toolbox/src/main/java/com/onixbyte/common/util/AesUtil.java

@@ -170,6 +170,7 @@ public final class AesUtil {
      *
      * @param data    the Base64-encoded string data to be decrypted
      * @param secret  the secret key used for decryption
+     * @param ivParam the initialization vector parameter used for AES decryption
      * @return the decrypted string data
      * @throws GeneralSecurityException if any cryptographic error occurs during decryption
      */

gradle.properties

@@ -20,7 +20,7 @@
 # SOFTWARE.
 #
 
-artefactVersion=3.0.0
+artefactVersion=3.1.0
 projectUrl=https://onixbyte.com/projects/onixbyte-toolbox
 projectGithubUrl=https://github.com/onixbyte/onixbyte-toolbox
 licenseName=MIT

settings.gradle.kts

@@ -24,3 +24,5 @@ include(
     "crypto-toolbox",
     "math-toolbox",
 )
+
+include("tuple")

tuple/README.md

@@ -0,0 +1,74 @@
+# Tuple
+
+## Introduction
+
+The `tuple` module provides simple and efficient implementations of mutable and immutable bi-tuples and tri-tuples. These tuples allow you to group two or three values together without creating custom classes, supporting convenient usage in various programming scenarios.
+
+## Features
+
+- Immutable and mutable versions of bi-tuples (pairs) and tri-tuples (triplets);
+- Factory method of() for easy instantiation of all tuple types;
+- Simple, lightweight implementation compatible with standard Java usage;
+- Clear distinction between mutable and immutable tuples for flexibility.
+
+## Installation
+
+### Maven
+
+Add the following dependency to your `pom.xml`:
+
+```xml
+<dependency>
+    <groupId>com.onixbyte</groupId>
+    <artifactId>tuple</artifactId>
+    <version>$artefactVersion</version>
+</dependency>
+```
+
+### Gradle
+
+#### Version Catalogue
+
+Add the following codes to you `gradle/libs.versions.toml`:
+
+```toml
+[version]
+onixbyteToolbox = "$artefactVersion"
+
+[libraries]
+onixbyteToolbox-tuple = { group = "com.onixbyte", name = "tuple", version.ref = "onixbyteToolbox" }
+```
+
+Then add the following codes to your `build.gradle.kts` or `build.gradle` dependencies block:
+
+```kotlin
+implementation(libs.onixbyteToolbox.tuple)
+```
+
+```groovy
+implementation libs.onixbyteToolbox.tuple
+```
+
+#### Kotlin DSL
+
+Add the following line to your `build.gradle.kts` dependencies block:
+
+```kotlin
+implementation("com.onixbyte:tuple:$artefactVersion")
+```
+
+#### Groovy DSL
+
+Add the following line to your `build.gradle` dependencies block:
+
+```groovy
+implementation 'com.onixbyte:tuple:${artefactVersion}'
+```
+
+## Dependencies
+
+This module has no external dependencies other than the standard Java SDK.
+
+## Acknowledgement
+
+Thanks to all contributors who helped develop this module, improving its design, performance, and documentation over time.

tuple/build.gradle.kts

@@ -0,0 +1,132 @@
+/*
+ * Copyright (c) 2024-2025 OnixByte
+ *
+ * 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 above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * 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. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import java.net.URI
+
+plugins {
+    java
+    id("java-library")
+    id("maven-publish")
+    id("signing")
+}
+
+val artefactVersion: String by project
+val projectUrl: String by project
+val projectGithubUrl: String by project
+val licenseName: String by project
+val licenseUrl: String by project
+
+group = "com.onixbyte"
+version = artefactVersion
+
+repositories {
+    mavenCentral()
+}
+
+java {
+    sourceCompatibility = JavaVersion.VERSION_17
+    targetCompatibility = JavaVersion.VERSION_17
+    withSourcesJar()
+    withJavadocJar()
+}
+
+tasks.withType<JavaCompile> {
+    options.encoding = "UTF-8"
+}
+
+tasks.withType<Jar> {
+    exclude("logback.xml")
+}
+
+dependencies {
+    compileOnly(libs.slf4j)
+    implementation(libs.logback)
+    testImplementation(platform(libs.junit.bom))
+    testImplementation(libs.junit.jupiter)
+}
+
+tasks.test {
+    useJUnitPlatform()
+}
+
+publishing {
+    publications {
+        create<MavenPublication>("tuple") {
+            groupId = group.toString()
+            artifactId = "tuple"
+            version = artefactVersion
+
+            pom {
+                name = "OnixByte Tuple"
+                description =
+                    "The tuple module is designed to offer a convenient and efficient way to handle grouped data."
+                url = projectUrl
+
+                licenses {
+                    license {
+                        name = licenseName
+                        url = licenseUrl
+                    }
+                }
+
+                scm {
+                    connection = "scm:git:git://github.com:onixbyte/onixbyte-toolbox.git"
+                    developerConnection = "scm:git:git://github.com:onixbyte/onixbyte-toolbox.git"
+                    url = projectGithubUrl
+                }
+
+                developers {
+                    developer {
+                        id = "zihluwang"
+                        name = "Zihlu Wang"
+                        email = "really@zihlu.wang"
+                        timezone = "Asia/Hong_Kong"
+                    }
+
+                    developer {
+                        id = "siujamo"
+                        name = "Siu Jam'o"
+                        email = "jamo.siu@outlook.com"
+                        timezone = "Asia/Shanghai"
+                    }
+                }
+            }
+
+            from(components["java"])
+
+            signing {
+                sign(publishing.publications["tuple"])
+            }
+        }
+
+        repositories {
+            maven {
+                name = "sonatypeNexus"
+                url = URI(providers.gradleProperty("repo.maven-central.host").get())
+                credentials {
+                    username = providers.gradleProperty("repo.maven-central.username").get()
+                    password = providers.gradleProperty("repo.maven-central.password").get()
+                }
+            }
+        }
+    }
+}

tuple/src/main/java/com/onixbyte/tuple/BiTuple.java

@@ -0,0 +1,151 @@
+/*
+ * 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.tuple;
+
+import java.util.Objects;
+
+/**
+ * Represents an ordered pair of elements, where the first element is of type {@code L} and the
+ * second is of type {@code R}. This class provides a simple way to group two related
+ * values together.
+ * <p>
+ * The class is mutable, allowing the values of the left and right elements to be changed
+ * after creation. It also overrides the {@code equals}, {@code hashCode}, and {@code toString}
+ * methods to provide meaningful comparisons and string representations.
+ *
+ * @param <L> the type of the left element
+ * @param <R> the type of the right element
+ * @author siujamo
+ * @author zihluwang
+ */
+public final class BiTuple<L, R> {
+
+    /**
+     * The left element of the tuple.
+     */
+    private L left;
+
+    /**
+     * The right element of the tuple.
+     */
+    private R right;
+
+    /**
+     * Constructs a new {@code BiTuple} with the specified left and right elements.
+     *
+     * @param left  the left element to be stored in the tuple
+     * @param right the right element to be stored in the tuple
+     */
+    public BiTuple(L left, R right) {
+        this.left = left;
+        this.right = right;
+    }
+
+    /**
+     * Retrieves the left element of the tuple.
+     *
+     * @return the left element of the tuple
+     */
+    public L getLeft() {
+        return left;
+    }
+
+    /**
+     * Sets the left element of the tuple to the specified value.
+     *
+     * @param left the new value for the left element of the tuple
+     */
+    public void setLeft(L left) {
+        this.left = left;
+    }
+
+    /**
+     * Retrieves the right element of the tuple.
+     *
+     * @return the right element of the tuple
+     */
+    public R getRight() {
+        return right;
+    }
+
+    /**
+     * Sets the right element of the tuple to the specified value.
+     *
+     * @param right the new value for the right element of the tuple
+     */
+    public void setRight(R right) {
+        this.right = right;
+    }
+
+    /**
+     * Compares this {@code BiTuple} with the specified object for equality.
+     * <p>
+     * Two {@code BiTuple}s are considered equal if they are of the same type and their left and
+     * right elements are equal according to their respective {@code equals} methods.
+     *
+     * @param object the object to compare with this {@code BiTuple}
+     * @return {@code true} if the specified object is equal to this {@code BiTuple},
+     * {@code false} otherwise
+     */
+    @Override
+    public boolean equals(Object object) {
+        if (!(object instanceof BiTuple<?, ?> biTuple)) return false;
+        return Objects.equals(left, biTuple.left) && Objects.equals(right, biTuple.right);
+    }
+
+    /**
+     * Returns a hash code value for the {@code BiTuple}.
+     * <p>
+     * The hash code is calculated based on the hash codes of the left and right elements.
+     *
+     * @return a hash code value for this {@code BiTuple}
+     */
+    @Override
+    public int hashCode() {
+        return Objects.hash(left, right);
+    }
+
+    /**
+     * Returns a string representation of the {@code BiTuple}.
+     * <p>
+     * The string representation consists of the class name, followed by the values of
+     * the left and right elements in the format {@code "BiTuple{left=value1, right=value2}"}.
+     *
+     * @return a string representation of the {@code BiTuple}
+     */
+    @Override
+    public String toString() {
+        return "BiTuple{" +
+            "left=" + left +
+            ", right=" + right +
+            '}';
+    }
+
+    /**
+     * Creates a new {@code BiTuple} with the specified left and right elements.
+     *
+     * @param <L>   the type of the left element
+     * @param <R>   the type of the right element
+     * @param left  the left element
+     * @param right the right element
+     * @return a new {@code BiTuple} containing the specified elements
+     */
+    public static <L, R> BiTuple<L, R> of(L left, R right) {
+        return new BiTuple<>(left, right);
+    }
+}

tuple/src/main/java/com/onixbyte/tuple/ImmutableBiTuple.java

@@ -0,0 +1,52 @@
+/*
+ * 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.tuple;
+
+/**
+ * Represents an immutable pair of two elements, referred to as 'left' and 'right'. This class
+ * provides a simple way to group two values without the need to create a custom class for each
+ * specific pair.
+ * <p>
+ * The generic types {@code L} and {@code R} denote the types of the left and right elements,
+ * respectively. Instances of this class are immutable once created.
+ *
+ * @param <L>   the type of the left element
+ * @param <R>   the type of the right element
+ * @param left  the left element of this tuple
+ * @param right the right element of this tuple
+ * @author siujamo
+ * @author zihluwang
+ */
+public record ImmutableBiTuple<L, R>(
+    L left,
+    R right
+) {
+
+    /**
+     * Creates a new {@code ImmutableBiTuple} with the specified left and right elements.
+     *
+     * @param <L>   the type of the left element
+     * @param <R>   the type of the right element
+     * @param left  the left element
+     * @param right the right element
+     * @return a new {@code ImmutableBiTuple} containing the specified elements
+     */
+    public static <L, R> ImmutableBiTuple<L, R> of(L left, R right) {
+        return new ImmutableBiTuple<>(left, right);
+    }
+}

tuple/src/main/java/com/onixbyte/tuple/ImmutableTriTuple.java

@@ -0,0 +1,57 @@
+/*
+ * 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.tuple;
+
+/**
+ * Represents an immutable triple of three elements, referred to as 'left', 'middle', and 'right'.
+ * This class provides a generic way to group three values without the need to create a custom class
+ * for each specific combination.
+ * <p>
+ * The generic types {@code L}, {@code M}, and {@code R} denote the types of the left, middle, and
+ * right elements, respectively. Instances of this class are immutable once created.
+ *
+ * @param <L>    the type of the left element
+ * @param <M>    the type of the middle element
+ * @param <R>    the type of the right element
+ * @param left   the left element of this triple
+ * @param middle the middle element of this triple
+ * @param right  the right element of this triple
+ * @author siujamo
+ * @author zihluwang
+ */
+public record ImmutableTriTuple<L, M, R>(
+    L left,
+    M middle,
+    R right
+) {
+
+    /**
+     * Creates a new {@code ImmutableTriTuple} with the specified left, middle, and right elements.
+     *
+     * @param <L>    the type of the left element
+     * @param <M>    the type of the middle element
+     * @param <R>    the type of the right element
+     * @param left   the left element
+     * @param middle the middle element
+     * @param right  the right element
+     * @return a new {@code ImmutableTriTuple} containing the specified elements
+     */
+    public static <L, M, R> ImmutableTriTuple<L, M, R> of(L left, M middle, R right) {
+        return new ImmutableTriTuple<>(left, middle, right);
+    }
+}

tuple/src/main/java/com/onixbyte/tuple/TriTuple.java

@@ -0,0 +1,172 @@
+/*
+ * 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.tuple;
+
+import java.util.Objects;
+
+/**
+ * Represents a mutable triple of three elements, referred to as 'left', 'middle' and 'right'.
+ * This class provides a way to group three values of different types.
+ * <p>
+ * The generic types {@code L}, {@code M} and {@code R} denote the types of the left, middle and
+ * right elements respectively.
+ *
+ * @param <L> the type of the left element
+ * @param <M> the type of the middle element
+ * @param <R> the type of the right element
+ * @author siujamo
+ * @author zihluwang
+ */
+public final class TriTuple<L, M, R> {
+
+    /**
+     * The left element of the triple.
+     */
+    private L left;
+
+    /**
+     * The middle element of the triple.
+     */
+    private M middle;
+
+    /**
+     * The right element of the triple.
+     */
+    private R right;
+
+    /**
+     * Constructs a new {@code TriTuple} with the given left, middle and right elements.
+     *
+     * @param left   the left element
+     * @param middle the middle element
+     * @param right  the right element
+     */
+    public TriTuple(L left, M middle, R right) {
+        this.left = left;
+        this.middle = middle;
+        this.right = right;
+    }
+
+    /**
+     * Retrieves the left element of the triple.
+     *
+     * @return the left element
+     */
+    public L getLeft() {
+        return left;
+    }
+
+    /**
+     * Sets the left element of the triple.
+     *
+     * @param left the new left element
+     */
+    public void setLeft(L left) {
+        this.left = left;
+    }
+
+    /**
+     * Retrieves the middle element of the triple.
+     *
+     * @return the middle element
+     */
+    public M getMiddle() {
+        return middle;
+    }
+
+    /**
+     * Sets the middle element of the triple.
+     *
+     * @param middle the new middle element
+     */
+    public void setMiddle(M middle) {
+        this.middle = middle;
+    }
+
+    /**
+     * Retrieves the right element of the triple.
+     *
+     * @return the right element
+     */
+    public R getRight() {
+        return right;
+    }
+
+    /**
+     * Sets the right element of the triple.
+     *
+     * @param right the new right element
+     */
+    public void setRight(R right) {
+        this.right = right;
+    }
+
+    /**
+     * Checks if this {@code TriTuple} is equal to the specified object.
+     * Two {@code TriTuple}s are considered equal if their left, middle and right elements are equal.
+     *
+     * @param object the object to compare with
+     * @return {@code true} if the objects are equal, {@code false} otherwise
+     */
+    @Override
+    public boolean equals(Object object) {
+        if (!(object instanceof TriTuple<?, ?, ?> triTuple)) return false;
+        return Objects.equals(left, triTuple.left) &&
+            Objects.equals(middle, triTuple.middle) &&
+            Objects.equals(right, triTuple.right);
+    }
+
+    /**
+     * Calculates the hash code for this {@code TriTuple} based on its left, middle and right elements.
+     *
+     * @return the hash code value for this object
+     */
+    @Override
+    public int hashCode() {
+        return Objects.hash(left, middle, right);
+    }
+
+    /**
+     * Returns a string representation of this {@code TriTuple}, including its left, middle and right elements.
+     *
+     * @return a string representation of the object
+     */
+    @Override
+    public String toString() {
+        return "TriTuple{" +
+            "left=" + left +
+            ", middle=" + middle +
+            ", right=" + right +
+            '}';
+    }
+
+    /**
+     * Factory method to create a new {@code TriTuple} instance with the given left, middle and right elements.
+     *
+     * @param left   the left element
+     * @param middle the middle element
+     * @param right  the right element
+     * @param <L>    the type of the left element
+     * @param <M>    the type of the middle element
+     * @param <R>    the type of the right element
+     * @return a new {@code TriTuple} instance
+     */
+    public static <L, M, R> TriTuple<L, M, R> of(L left, M middle, R right) {
+        return new TriTuple<>(left, middle, right);
+    }
+}