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

This commit is contained in:
Zihlu Wang
2025-07-17 10:41:43 +08:00
committed by GitHub
9 changed files with 644 additions and 3 deletions
@@ -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
*/
+1 -1
View File
@@ -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
+2
View File
@@ -24,3 +24,5 @@ include(
"crypto-toolbox",
"math-toolbox",
)
include("tuple")
+74
View File
@@ -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.
+132
View File
@@ -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()
}
}
}
}
}
@@ -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);
}
}
@@ -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);
}
}
@@ -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);
}
}
@@ -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);
}
}