diff --git a/docs/en-gb/projects/onixbyte-toolbox/api.md b/docs/en-gb/projects/onixbyte-toolbox/api.md new file mode 100644 index 0000000..c097076 --- /dev/null +++ b/docs/en-gb/projects/onixbyte-toolbox/api.md @@ -0,0 +1,209 @@ +--- +title: OnixByte Toolbox API +--- + +## Package Overview + +All modules are published under the `com.onixbyte` group ID. Each module has its own base package: + +| Module | Maven Artifact | Base Package | +|----------------------|------------------------|---------------------------------------| +| Common Toolbox | `common-toolbox` | `com.onixbyte.common` | +| Crypto Toolbox | `crypto-toolbox` | `com.onixbyte.crypto` | +| Math Toolbox | `math-toolbox` | `com.onixbyte.math` | +| Tuple | `tuple` | `com.onixbyte.tuple` | +| Identity Generator | `identity-generator` | `com.onixbyte.identitygenerator` | + +--- + +## Common Toolbox + +### Adapter + +`ObjectMapAdapter` — Converts between objects and maps. Useful for serialisation or data transformation scenarios where key-value representations are preferred. + +```java +import com.onixbyte.common.adapter.ObjectMapAdapter; +``` + +### Utility Classes + +| Class | Description | +|--------------------|----------------------------------------------------------| +| `AesUtil` | AES symmetric encryption/decryption with key generation | +| `Base64Util` | Base64 encoding and decoding with multiple charset support| +| `BoolUtil` | Boolean parsing and conversion utilities | +| `BranchUtil` | Conditional branching helpers with functional-style chains| +| `CollectionUtil` | Collection manipulation — grouping, partitioning, merging | +| `HashUtil` | Hashing utilities supporting MD5, SHA-1, SHA-256, SHA-512 | +| `MapUtil` | Map builder, merge, and transformation helpers | +| `RangeUtil` | Numeric range operations with boundary handling | + +**AesUtil Example:** + +```java +var key = AesUtil.generateKey(); +var encrypted = AesUtil.encrypt("hello world", key); +var decrypted = AesUtil.decrypt(encrypted, key); +``` + +**HashUtil Example:** + +```java +var md5 = HashUtil.md5("hello world"); +var sha256 = HashUtil.sha256("hello world"); +var fileSha = HashUtil.sha256(new File("data.bin")); +``` + +**CollectionUtil Example:** + +```java +var partitioned = CollectionUtil.partition(list, 100); +var grouped = CollectionUtil.groupBy(users, User::getDepartment); +``` + +--- + +## Crypto Toolbox + +Provides a clean abstraction for loading cryptographic keys in PEM format. Supports both RSA and ECDSA algorithms. + +### Key Loaders + +| Class | Description | +|---------------------------|--------------------------------------------| +| `RSAPrivateKeyLoader` | Load RSA private keys from PEM strings | +| `RSAPublicKeyLoader` | Load RSA public keys from PEM strings | +| `ECPrivateKeyLoader` | Load ECDSA private keys from PEM strings | +| `ECPublicKeyLoader` | Load ECDSA public keys from PEM strings | + +All key loaders implement either `PrivateKeyLoader` or `PublicKeyLoader` interfaces. + +**RSA Example:** + +```java +var privateKey = new RSAPrivateKeyLoader().load(pemString); +var publicKey = new RSAPublicKeyLoader().load(pemString); +``` + +**ECDSA Example:** + +```java +var ecPrivateKey = new ECPrivateKeyLoader().load(pemString); +var ecPublicKey = new ECPublicKeyLoader().load(pemString); +``` + +### Utility + +`CryptoUtil` — Provides convenient methods for digital signature creation and verification, as well as general-purpose cryptographic helpers. + +### Exceptions + +| Class | Description | +|------------------------|---------------------------------------------------| +| `KeyLoadingException` | Thrown when a PEM-formatted key fails to parse | + +--- + +## Math Toolbox + +Statistical computation utilities for working with numeric datasets. + +### Core Classes + +| Class | Description | +|-------------------------|----------------------------------------------------------| +| `Calculator` | Statistical calculator for mean, median, variance, standard deviation, sum, min, max | +| `PercentileCalculator` | Percentile computation with configurable interpolation strategies | + +**Calculator Example:** + +```java +var stats = new Calculator(Arrays.asList(1.0, 2.0, 3.0, 4.0, 5.0)); +double mean = stats.getMean(); +double median = stats.getMedian(); +double stdDev = stats.getStandardDeviation(); +``` + +**PercentileCalculator Example:** + +```java +var calculator = new PercentileCalculator(data); +double p95 = calculator.calculate(95); +double p99 = calculator.calculate(99); +``` + +### Model + +| Class | Description | +|-------------------|----------------------------------------------------------------| +| `QuartileBounds` | Holds Q1, median (Q2), Q3 values along with IQR and whisker bounds | + +--- + +## Tuple + +Lightweight generic tuple types for when you need to return multiple values without defining a dedicated class. + +### Classes + +| Class | Type Parameters | Mutability | +|--------------------|-----------------|------------| +| `Tuple` | Two elements | Mutable | +| `ImmutableTuple` | Two elements | Immutable | +| `Triple` | Three elements | Mutable | +| `ImmutableTriple` | Three elements | Immutable | + +**Example:** + +```java +var pair = Tuple.of("key", 42); +var triple = Triple.of("id", "name", 100); +var immutable = ImmutableTuple.of("constant", true); + +// Accessors +String first = pair.getFirst(); +Integer second = pair.getSecond(); + +// Triple accessors +String a = triple.getFirst(); +String b = triple.getSecond(); +Integer c = triple.getThird(); +``` + +--- + +## Identity Generator + +Generates unique identifiers suitable for use as database primary keys or distributed IDs. + +### Interface + +`IdentityGenerator` — Generates identities of type `T`. + +### Implementations + +| Class | Description | +|------------------------------|-----------------------------------------------------------------| +| `SequentialUuidGenerator` | Generates time-ordered, sequential UUIDs (optimised for DB indexes) | +| `SnowflakeIdentityGenerator` | Snowflake-style distributed unique ID generation | + +**Sequential UUID:** + +```java +var generator = new SequentialUuidGenerator(); +UUID id = generator.nextId(); // time-ordered UUID, B-tree friendly +``` + +**Snowflake:** + +```java +var generator = new SnowflakeIdentityGenerator(workerId, datacenterId); +long id = generator.nextId(); // 64-bit snowflake ID +``` + +### Exceptions + +| Class | Description | +|-------------------|----------------------------------------------------------------| +| `TimingException` | Thrown when the system clock moves backwards, compromising ID uniqueness | diff --git a/docs/en-gb/projects/onixbyte-toolbox/index.mdx b/docs/en-gb/projects/onixbyte-toolbox/index.mdx new file mode 100644 index 0000000..4063d3c --- /dev/null +++ b/docs/en-gb/projects/onixbyte-toolbox/index.mdx @@ -0,0 +1,54 @@ +--- +title: OnixByte Toolbox +--- + +## Introduction + +OnixByte Toolbox is a Development Kit for Java applications that provides a set of convenient, reusable tools for writing code efficiently. It is designed and maintained by OnixByte as a monorepo containing multiple purpose-built libraries, each addressing a specific development need — from common utilities and cryptography to mathematical computation and identity generation. + +The toolkit is available on Maven Central under the `com.onixbyte` group ID. Each module is independently versioned and can be included in any Java 17+ project. + +## Modules + +| Module | Artifact ID | Description | +|----------------------|-----------------------|-------------------------------------------------------| +| Common Toolbox | `common-toolbox` | Everyday utilities — AES, hashing, Base64, collections, branching, ranges | +| Crypto Toolbox | `crypto-toolbox` | Public/private key loading for RSA and ECDSA algorithms | +| Math Toolbox | `math-toolbox` | Statistical calculation, percentile analysis, quartile computation | +| Tuple | `tuple` | Generic 2-tuple and 3-tuple with immutable variants | +| Identity Generator | `identity-generator` | Snowflake-style and sequential UUID identity generation | +| Version Catalogue | `version-catalogue` | Centralised Gradle version catalogue for OnixByte projects | + +## Installation + +Add the desired module as a dependency in your build config: + +**Gradle (Kotlin DSL):** + +```kotlin +implementation("com.onixbyte:common-toolbox:$version") +implementation("com.onixbyte:crypto-toolbox:$version") +implementation("com.onixbyte:math-toolbox:$version") +implementation("com.onixbyte:tuple:$version") +implementation("com.onixbyte:identity-generator:$version") +``` + +**Maven:** + +```xml + + com.onixbyte + common-toolbox + ${version} + +``` + +Refer to the [changelog](https://codecrafters.org.cn/devkit/changelog) for available versions. + +## Requirements + +- Java 17 or later + +## License + +OnixByte Toolbox is open-source software released under the MIT License. diff --git a/docs/zh-hans/projects/onixbyte-toolbox/api.md b/docs/zh-hans/projects/onixbyte-toolbox/api.md new file mode 100644 index 0000000..ca82acf --- /dev/null +++ b/docs/zh-hans/projects/onixbyte-toolbox/api.md @@ -0,0 +1,209 @@ +--- +title: OnixByte Toolbox API +--- + +## 包结构概览 + +所有模块均在 `com.onixbyte` group ID 下发布。每个模块有自己独立的基础包： + +| 模块 | Maven Artifact | 基础包 | +|---|---|---| +| Common Toolbox | `common-toolbox` | `com.onixbyte.common` | +| Crypto Toolbox | `crypto-toolbox` | `com.onixbyte.crypto` | +| Math Toolbox | `math-toolbox` | `com.onixbyte.math` | +| Tuple | `tuple` | `com.onixbyte.tuple` | +| Identity Generator | `identity-generator` | `com.onixbyte.identitygenerator` | + +--- + +## Common Toolbox + +### 适配器 + +`ObjectMapAdapter` — 对象与 Map 之间的转换器。适用于需要键值表示的场景，如序列化或数据转换。 + +```java +import com.onixbyte.common.adapter.ObjectMapAdapter; +``` + +### 工具类 + +| 类 | 描述 | +|---|---| +| `AesUtil` | AES 对称加密/解密，支持密钥生成 | +| `Base64Util` | Base64 编解码，支持多种字符集 | +| `BoolUtil` | 布尔值解析与转换工具 | +| `BranchUtil` | 条件分支辅助，支持函数式链式调用 | +| `CollectionUtil` | 集合操作 — 分组、分区、合并 | +| `HashUtil` | 哈希工具，支持 MD5、SHA-1、SHA-256、SHA-512 | +| `MapUtil` | Map 构建、合并和转换辅助 | +| `RangeUtil` | 数值范围操作，支持边界处理 | + +**AesUtil 示例：** + +```java +var key = AesUtil.generateKey(); +var encrypted = AesUtil.encrypt("hello world", key); +var decrypted = AesUtil.decrypt(encrypted, key); +``` + +**HashUtil 示例：** + +```java +var md5 = HashUtil.md5("hello world"); +var sha256 = HashUtil.sha256("hello world"); +var fileSha = HashUtil.sha256(new File("data.bin")); +``` + +**CollectionUtil 示例：** + +```java +var partitioned = CollectionUtil.partition(list, 100); +var grouped = CollectionUtil.groupBy(users, User::getDepartment); +``` + +--- + +## Crypto Toolbox + +提供了加载 PEM 格式密钥的简洁抽象。支持 RSA 和 ECDSA 算法。 + +### 密钥加载器 + +| 类 | 描述 | +|---|---| +| `RSAPrivateKeyLoader` | 从 PEM 字符串加载 RSA 私钥 | +| `RSAPublicKeyLoader` | 从 PEM 字符串加载 RSA 公钥 | +| `ECPrivateKeyLoader` | 从 PEM 字符串加载 ECDSA 私钥 | +| `ECPublicKeyLoader` | 从 PEM 字符串加载 ECDSA 公钥 | + +所有密钥加载器实现 `PrivateKeyLoader` 或 `PublicKeyLoader` 接口。 + +**RSA 示例：** + +```java +var privateKey = new RSAPrivateKeyLoader().load(pemString); +var publicKey = new RSAPublicKeyLoader().load(pemString); +``` + +**ECDSA 示例：** + +```java +var ecPrivateKey = new ECPrivateKeyLoader().load(pemString); +var ecPublicKey = new ECPublicKeyLoader().load(pemString); +``` + +### 工具类 + +`CryptoUtil` — 提供便捷的数字签名生成和验证方法，以及通用密码学辅助功能。 + +### 异常 + +| 类 | 描述 | +|---|---| +| `KeyLoadingException` | PEM 格式密钥解析失败时抛出 | + +--- + +## Math Toolbox + +用于处理数值数据集的统计计算工具。 + +### 核心类 + +| 类 | 描述 | +|---|---| +| `Calculator` | 统计计算器 — 均值、中位数、方差、标准差、总和、最小值、最大值 | +| `PercentileCalculator` | 百分位数计算器，支持可配置的插值策略 | + +**Calculator 示例：** + +```java +var stats = new Calculator(Arrays.asList(1.0, 2.0, 3.0, 4.0, 5.0)); +double mean = stats.getMean(); +double median = stats.getMedian(); +double stdDev = stats.getStandardDeviation(); +``` + +**PercentileCalculator 示例：** + +```java +var calculator = new PercentileCalculator(data); +double p95 = calculator.calculate(95); +double p99 = calculator.calculate(99); +``` + +### 数据模型 + +| 类 | 描述 | +|---|---| +| `QuartileBounds` | 包含 Q1、中位数（Q2）、Q3 值及 IQR 和须线边界 | + +--- + +## Tuple + +轻量级泛型元组类型，适用于需要返回多个值但无需定义专用类的场景。 + +### 类 + +| 类 | 类型参数 | 可变性 | +|---|---|---| +| `Tuple` | 两个元素 | 可变 | +| `ImmutableTuple` | 两个元素 | 不可变 | +| `Triple` | 三个元素 | 可变 | +| `ImmutableTriple` | 三个元素 | 不可变 | + +**示例：** + +```java +var pair = Tuple.of("key", 42); +var triple = Triple.of("id", "name", 100); +var immutable = ImmutableTuple.of("constant", true); + +// 访问器 +String first = pair.getFirst(); +Integer second = pair.getSecond(); + +// 三元组访问器 +String a = triple.getFirst(); +String b = triple.getSecond(); +Integer c = triple.getThird(); +``` + +--- + +## Identity Generator + +生成适用于数据库主键或分布式 ID 的唯一标识符。 + +### 接口 + +`IdentityGenerator` — 生成类型为 `T` 的标识符。 + +### 实现 + +| 类 | 描述 | +|---|---| +| `SequentialUuidGenerator` | 生成时间排序的顺序 UUID（优化数据库索引性能） | +| `SnowflakeIdentityGenerator` | 雪花算法分布式唯一 ID 生成 | + +**顺序 UUID：** + +```java +var generator = new SequentialUuidGenerator(); +UUID id = generator.nextId(); // 时间排序 UUID，对 B-tree 友好 +``` + +**雪花：** + +```java +var generator = new SnowflakeIdentityGenerator(workerId, datacenterId); +long id = generator.nextId(); // 64 位雪花 ID +``` + +### 异常 + +| 类 | 描述 | +|---|---| +| `TimingException` | 系统时钟回拨时抛出，保证 ID 唯一性不受影响 | diff --git a/docs/zh-hans/projects/onixbyte-toolbox/index.mdx b/docs/zh-hans/projects/onixbyte-toolbox/index.mdx new file mode 100644 index 0000000..bc5ac2d --- /dev/null +++ b/docs/zh-hans/projects/onixbyte-toolbox/index.mdx @@ -0,0 +1,54 @@ +--- +title: OnixByte Toolbox +--- + +## 介绍 + +OnixByte Toolbox 是一个面向 Java 应用的开发工具包，提供了一系列便捷、可复用的工具，帮助开发者高效编写代码。它由 OnixByte 设计和维护，采用 monorepo 架构，包含多个专用库，每个库解决一个特定的开发需求 — 从通用工具类和密码学，到数学计算和标识符生成。 + +该工具包已发布到 Maven Central，使用 `com.onixbyte` 作为 group ID。每个模块独立版本管理，可在任何 Java 17+ 项目中使用。 + +## 模块 + +| 模块 | Artifact ID | 描述 | +|---|---|---| +| Common Toolbox | `common-toolbox` | 日常工具类 — AES 加密、哈希、Base64、集合、分支、范围 | +| Crypto Toolbox | `crypto-toolbox` | RSA 和 ECDSA 算法的公私钥加载 | +| Math Toolbox | `math-toolbox` | 统计计算、百分位数分析、四分位数计算 | +| Tuple | `tuple` | 泛型二元组和三元组，含不可变版本 | +| Identity Generator | `identity-generator` | 雪花算法和顺序 UUID 唯一标识符生成 | +| Version Catalogue | `version-catalogue` | OnixByte 项目的集中式 Gradle 版本目录 | + +## 安装 + +在构建配置中添加所需模块的依赖： + +**Gradle (Kotlin DSL):** + +```kotlin +implementation("com.onixbyte:common-toolbox:$version") +implementation("com.onixbyte:crypto-toolbox:$version") +implementation("com.onixbyte:math-toolbox:$version") +implementation("com.onixbyte:tuple:$version") +implementation("com.onixbyte:identity-generator:$version") +``` + +**Maven:** + +```xml + + com.onixbyte + common-toolbox + ${version} + +``` + +可查阅[更新日志](https://codecrafters.org.cn/devkit/changelog)了解可用版本。 + +## 要求 + +- Java 17 或更高版本 + +## 许可证 + +OnixByte Toolbox 是采用 MIT 许可证发布的开源软件。