diff --git a/common-toolbox/src/main/java/com/onixbyte/common/util/AesUtil.java b/common-toolbox/src/main/java/com/onixbyte/common/util/AesUtil.java index 62ee697..84cfb82 100644 --- a/common-toolbox/src/main/java/com/onixbyte/common/util/AesUtil.java +++ b/common-toolbox/src/main/java/com/onixbyte/common/util/AesUtil.java @@ -168,8 +168,9 @@ public final class AesUtil { /** * Decrypts the specified Base64-encoded string data using the AES algorithm with the provided secret key. * - * @param data the Base64-encoded string data to be decrypted - * @param secret the secret key used for decryption + * @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 */ diff --git a/gradle.properties b/gradle.properties index 00e3c6a..526a544 100644 --- a/gradle.properties +++ b/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 diff --git a/settings.gradle.kts b/settings.gradle.kts index d5b4d12..415ef24 100644 --- a/settings.gradle.kts +++ b/settings.gradle.kts @@ -24,3 +24,5 @@ include( "crypto-toolbox", "math-toolbox", ) + +include("tuple") \ No newline at end of file diff --git a/tuple/README.md b/tuple/README.md new file mode 100644 index 0000000..b0eb7d1 --- /dev/null +++ b/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 + + com.onixbyte + tuple + $artefactVersion + +``` + +### 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. diff --git a/tuple/build.gradle.kts b/tuple/build.gradle.kts new file mode 100644 index 0000000..a9eb008 --- /dev/null +++ b/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 { + options.encoding = "UTF-8" +} + +tasks.withType { + 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("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() + } + } + } + } +} diff --git a/tuple/src/main/java/com/onixbyte/tuple/BiTuple.java b/tuple/src/main/java/com/onixbyte/tuple/BiTuple.java new file mode 100644 index 0000000..6c7e8ff --- /dev/null +++ b/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. + *

+ * 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 the type of the left element + * @param the type of the right element + * @author siujamo + * @author zihluwang + */ +public final class BiTuple { + + /** + * 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. + *

+ * 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}. + *

+ * 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}. + *

+ * 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 the type of the left element + * @param 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 BiTuple of(L left, R right) { + return new BiTuple<>(left, right); + } +} diff --git a/tuple/src/main/java/com/onixbyte/tuple/ImmutableBiTuple.java b/tuple/src/main/java/com/onixbyte/tuple/ImmutableBiTuple.java new file mode 100644 index 0000000..48b38b3 --- /dev/null +++ b/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. + *

+ * 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 the type of the left element + * @param 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 left, + R right +) { + + /** + * Creates a new {@code ImmutableBiTuple} with the specified left and right elements. + * + * @param the type of the left element + * @param 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 ImmutableBiTuple of(L left, R right) { + return new ImmutableBiTuple<>(left, right); + } +} diff --git a/tuple/src/main/java/com/onixbyte/tuple/ImmutableTriTuple.java b/tuple/src/main/java/com/onixbyte/tuple/ImmutableTriTuple.java new file mode 100644 index 0000000..1db986b --- /dev/null +++ b/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. + *

+ * 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 the type of the left element + * @param the type of the middle element + * @param 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 left, + M middle, + R right +) { + + /** + * Creates a new {@code ImmutableTriTuple} with the specified left, middle, and right elements. + * + * @param the type of the left element + * @param the type of the middle element + * @param 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 ImmutableTriTuple of(L left, M middle, R right) { + return new ImmutableTriTuple<>(left, middle, right); + } +} diff --git a/tuple/src/main/java/com/onixbyte/tuple/TriTuple.java b/tuple/src/main/java/com/onixbyte/tuple/TriTuple.java new file mode 100644 index 0000000..3f0ffe1 --- /dev/null +++ b/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. + *

+ * The generic types {@code L}, {@code M} and {@code R} denote the types of the left, middle and + * right elements respectively. + * + * @param the type of the left element + * @param the type of the middle element + * @param the type of the right element + * @author siujamo + * @author zihluwang + */ +public final class TriTuple { + + /** + * 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 the type of the left element + * @param the type of the middle element + * @param the type of the right element + * @return a new {@code TriTuple} instance + */ + public static TriTuple of(L left, M middle, R right) { + return new TriTuple<>(left, middle, right); + } +}