java.lang.Object

cloud.opencode.base.id.ksuid.KsuidGenerator

All Implemented Interfaces:: IdGenerator<String>

public final class KsuidGenerator extends Object implements IdGenerator<String>

KSUID (K-Sortable Unique Identifier) Generator KSUID（K可排序唯一标识符）生成器

Generates K-Sortable Unique Identifiers. KSUIDs are 20-byte identifiers encoded as 27-character Base62 strings. They are roughly sortable by creation time.

生成K可排序唯一标识符。KSUID是20字节的标识符，编码为27字符的Base62字符串。它们可以按创建时间大致排序。

KSUID Structure | KSUID结构 (160-bit / 20-byte):

|--------------------------------|------------------------------------------|
|    4 bytes timestamp           |         16 bytes random payload          |
|    (seconds since epoch)       |         (cryptographically secure)       |
|--------------------------------|------------------------------------------|

Features | 主要功能:

K-sortable (roughly time-ordered) - K可排序（大致时间有序）
Base62 encoded (URL-safe) - Base62编码（URL安全）
27 characters fixed length - 固定27字符长度
Cryptographically secure random payload - 加密安全的随机负载
~100 years from custom epoch (2014-05-13) - 从自定义起始时间起约100年

Comparison with ULID | 与ULID比较:

KSUID: 20 bytes, 27 chars, second precision - KSUID: 20字节，27字符，秒精度
ULID: 16 bytes, 26 chars, millisecond precision - ULID: 16字节，26字符，毫秒精度
KSUID has more random bits (128 vs 80) - KSUID有更多随机位（128 vs 80）

Usage Examples | 使用示例:

KsuidGenerator gen = KsuidGenerator.create();
String ksuid = gen.generate();
// -> "0ujtsYcgvSTl8PAuAdqWYSMnLOv"

// Get raw bytes
byte[] bytes = gen.generateBytes();

// Parse and extract timestamp
Instant time = KsuidGenerator.extractTimestamp(ksuid);

Security | 安全性:

Thread-safe: Yes - 线程安全: 是

Since:

JDK 25, opencode-base-id V1.1.0

Author:

Leon Soo www.LeonSoo.com

See Also:

Field Summary

Fields

Modifier and Type

Field

Description

static final long

EPOCH_SECONDS

KSUID epoch: 2014-05-13 16:53:20 UTC (1400000000) KSUID起始时间：2014-05-13 16:53:20 UTC
Method Summary

Modifier and Type

Method

Description

static int

compare(String ksuid1, String ksuid2)

Compares two KSUID strings 比较两个KSUID字符串

static KsuidGenerator

create()

Creates a KSUID generator 创建KSUID生成器

static byte[]

decode(String ksuid)

Decodes a KSUID string to raw bytes 将KSUID字符串解码为原始字节

static String

encode(byte[] bytes)

Encodes raw bytes to KSUID string 将原始字节编码为KSUID字符串

static byte[]

extractPayload(String ksuid)

Extracts the random payload from a KSUID string 从KSUID字符串提取随机负载

static Instant

extractTimestamp(byte[] bytes)

Extracts the timestamp from raw KSUID bytes 从KSUID原始字节提取时间戳

static Instant

extractTimestamp(String ksuid)

Extracts the timestamp from a KSUID string 从KSUID字符串提取时间戳

String

generate()

Generates the next ID 生成下一个ID

String

generate(long timestamp)

Generates a KSUID with specific timestamp 使用指定时间戳生成KSUID

byte[]

generateBytes()

Generates KSUID as raw bytes 生成KSUID原始字节

byte[]

generateBytes(long timestamp)

Generates KSUID as raw bytes with specific timestamp 使用指定时间戳生成KSUID原始字节

String

getType()

Gets the generator type name 获取生成器类型名称

static boolean

isValid(String ksuid)

Validates a KSUID string 验证KSUID字符串

static String

max()

Returns the maximum possible KSUID (all max values) 返回最大可能的KSUID（全最大值）

static String

min()

Returns the minimum possible KSUID (all zeros) 返回最小可能的KSUID（全零）

Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface IdGenerator
generateBatch

Field Details
- EPOCH_SECONDS
  public static final long EPOCH_SECONDS
  
  KSUID epoch: 2014-05-13 16:53:20 UTC (1400000000) KSUID起始时间：2014-05-13 16:53:20 UTC
  
  See Also:
  
  Constant Field Values
Method Details
- create
  
  public static KsuidGenerator create()
  
  Creates a KSUID generator 创建KSUID生成器
  
  Returns:
  
  generator | 生成器
- generate
  
  public String generate()
  
  Description copied from interface: IdGenerator
  
  Generates the next ID 生成下一个ID
  
  Specified by:
  
  generate in interface IdGenerator<String>
  
  Returns:
  
  generated ID | 生成的ID
- generate
  
  public String generate(long timestamp)
  
  Generates a KSUID with specific timestamp 使用指定时间戳生成KSUID
  
  Parameters:
  
  timestamp - the timestamp in seconds since Unix epoch | Unix纪元以来的秒数
  
  Returns:
  
  KSUID string (27 characters) | KSUID字符串（27字符）
- generateBytes
  
  public byte[] generateBytes()
  
  Generates KSUID as raw bytes 生成KSUID原始字节
  
  Returns:
  
  20-byte array | 20字节数组
- generateBytes
  
  public byte[] generateBytes(long timestamp)
  
  Generates KSUID as raw bytes with specific timestamp 使用指定时间戳生成KSUID原始字节
  
  Parameters:
  
  timestamp - the timestamp in seconds since Unix epoch | Unix纪元以来的秒数
  
  Returns:
  
  20-byte array | 20字节数组
- encode
  
  public static String encode(byte[] bytes)
  
  Encodes raw bytes to KSUID string 将原始字节编码为KSUID字符串
  
  Parameters:
  
  bytes - the 20-byte array | 20字节数组
  
  Returns:
  
  KSUID string (27 characters) | KSUID字符串（27字符）
- decode
  
  public static byte[] decode(String ksuid)
  
  Decodes a KSUID string to raw bytes 将KSUID字符串解码为原始字节
  
  Parameters:
  
  ksuid - the KSUID string | KSUID字符串
  
  Returns:
  
  20-byte array | 20字节数组
  
  Throws:
  
  IllegalArgumentException - if the string is invalid
- extractTimestamp
  
  public static Instant extractTimestamp(String ksuid)
  
  Extracts the timestamp from a KSUID string 从KSUID字符串提取时间戳
  
  Parameters:
  
  ksuid - the KSUID string | KSUID字符串
  
  Returns:
  
  the timestamp instant | 时间戳
- extractTimestamp
  
  public static Instant extractTimestamp(byte[] bytes)
  
  Extracts the timestamp from raw KSUID bytes 从KSUID原始字节提取时间戳
  
  Parameters:
  
  bytes - the 20-byte array | 20字节数组
  
  Returns:
  
  the timestamp instant | 时间戳
- extractPayload
  
  public static byte[] extractPayload(String ksuid)
  
  Extracts the random payload from a KSUID string 从KSUID字符串提取随机负载
  
  Parameters:
  
  ksuid - the KSUID string | KSUID字符串
  
  Returns:
  
  16-byte payload | 16字节负载
- isValid
  
  public static boolean isValid(String ksuid)
  
  Validates a KSUID string 验证KSUID字符串
  
  Parameters:
  
  ksuid - the KSUID string | KSUID字符串
  
  Returns:
  
  true if valid | 如果有效返回true
- compare
  
  public static int compare(String ksuid1, String ksuid2)
  
  Compares two KSUID strings 比较两个KSUID字符串
  
  Parameters:
  
  ksuid1 - first KSUID | 第一个KSUID
  
  ksuid2 - second KSUID | 第二个KSUID
  
  Returns:
  
  comparison result (negative if ksuid1 < ksuid2) | 比较结果
- min
  
  public static String min()
  
  Returns the minimum possible KSUID (all zeros) 返回最小可能的KSUID（全零）
  
  Returns:
  
  minimum KSUID string | 最小KSUID字符串
- max
  
  public static String max()
  
  Returns the maximum possible KSUID (all max values) 返回最大可能的KSUID（全最大值）
  
  Returns:
  
  maximum KSUID string | 最大KSUID字符串
- getType
  
  public String getType()
  
  Description copied from interface: IdGenerator
  
  Gets the generator type name 获取生成器类型名称
  
  Specified by:
  
  getType in interface IdGenerator<String>
  
  Returns:
  
  type name | 类型名称

Class KsuidGenerator

Field Summary

Method Summary

Methods inherited from class Object

Methods inherited from interface IdGenerator

Field Details

EPOCH_SECONDS

Method Details

create

generate

generate

generateBytes

generateBytes

encode

decode

extractTimestamp

extractTimestamp

extractPayload

isValid

compare

min

max

getType