onixbyte/onixbyte-bom
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: added docs

Browse Source
This commit is contained in:
zihluwang
2025-01-18 14:06:13 +08:00
parent 566a960c14
commit a85c562b66
22 changed files with 357 additions and 147 deletions
Download Patch File Download Diff File Expand all files Collapse all files
guid/src/main/java/com/onixbyte/guid/GuidCreator.java
+25 -5
View File
@@ -18,10 +18,33 @@
package com.onixbyte.guid;
/**
* The {@code GuidCreator} is a generic interface for generating globally unique
* identifiers (GUIDs) of a specific type.
* The {@code GuidCreator} is a generic interface for generating globally unique identifiers (GUIDs)
* of a specific type.
* <p>
* The type of ID is determined by the class implementing this interface.
* </p>
*
* <p><b>Example usage:</b></p>
* <pre>
* {@code
* public class StringGuidCreator implements GuidCreator<String> {
* private final AtomicLong counter = new AtomicLong();
*
* @Override
* public String nextId() {
* return UUID.randomUUID().toString() + "-" + counter.incrementAndGet();
* }
* }
*
* public class Example {
* public static void main(String[] args) {
* GuidCreator<String> guidCreator = new StringGuidCreator();
* String guid = guidCreator.nextId();
* System.out.println("Generated GUID: " + guid);
* }
* }
* }
* </pre>
*
* @param <IdType> this represents the type of the Global Unique Identifier
* @author Zihlu Wang
@@ -32,9 +55,6 @@ public interface GuidCreator<IdType> {
/**
* Generates and returns the next globally unique ID.
* <p>
* The exact implementation of how the globally unique ID is generated and
* returned will depend on the class implementing this method.
*
* @return the next globally unique ID
*/
guid/src/main/java/com/onixbyte/guid/exceptions/TimingException.java
+12 -14
View File
@@ -18,13 +18,12 @@
package com.onixbyte.guid.exceptions;
/**
* The {@code TimingException} class represents an exception that is thrown
* when there is an error related to time sequence.
* The {@code TimingException} class represents an exception that is thrown when there is an error
* related to time sequence.
* <p>
* Instances of TimingException can be created with or without a message and a
* cause. The message provides a description of the exception, while the cause
* represents the underlying cause of the exception and provides additional
* information about the error.
* Instances of TimingException can be created with or without a message and a cause. The message
* provides a description of the exception, while the cause represents the underlying cause of the
* exception and provides additional information about the error.
*
* @author Zihlu Wang
* @since 1.0.0
@@ -32,15 +31,14 @@ package com.onixbyte.guid.exceptions;
public class TimingException extends RuntimeException {
/**
* A custom exception that is thrown when there is an issue with timing or
* scheduling.
* A custom exception that is thrown when there is an issue with timing or scheduling.
*/
public TimingException() {
}
/**
* A custom exception that is thrown when there is an issue with timing or
* scheduling with customised error message.
* A custom exception that is thrown when there is an issue with timing or scheduling with
* customised error message.
*
* @param message customised message
*/
@@ -49,8 +47,8 @@ public class TimingException extends RuntimeException {
}
/**
* A custom exception that is thrown when there is an issue with timing or
* scheduling with customised error message.
* A custom exception that is thrown when there is an issue with timing or scheduling with
* customised error message.
*
* @param message customised message
* @param cause the cause of this exception
@@ -60,8 +58,8 @@ public class TimingException extends RuntimeException {
}
/**
* A custom exception that is thrown when there is an issue with timing or
* scheduling with customised error message.
* A custom exception that is thrown when there is an issue with timing or scheduling with
* customised error message.
*
* @param cause the cause of this exception
*/
guid/src/main/java/com/onixbyte/guid/exceptions/package-info.java
+12 -14
View File
@@ -16,25 +16,23 @@
*/
/**
* This package contains the custom exception classes related to GUID
* generation. These exceptions are thrown when there are issues or errors
* during the generation or processing of global unique identifiers (GUIDs).
* This package contains the custom exception classes related to GUID generation. These exceptions
* are thrown when there are issues or errors during the generation or processing of global unique
* identifiers (GUIDs).
* <p>
* The main exception class in this package is {@link
* com.onixbyte.guid.exceptions.TimingException}, which is a runtime
* exception and serves as the base exception for all other custom exceptions
* The main exception class in this package is {@link com.onixbyte.guid.exceptions.TimingException},
* which is a runtime exception and serves as the base exception for all other custom exceptions
* related to GUID generation.
* <p>
* Custom exceptions in this package provide specific information about the
* type of error that occurred during GUID generation, making it easier for
* developers to handle and respond to different scenarios when dealing with
* GUIDs. They are designed to enhance the robustness and reliability of the
* GUID generation process by providing clear and meaningful error messages to
* Custom exceptions in this package provide specific information about the type of error that
* occurred during GUID generation, making it easier for developers to handle and respond to
* different scenarios when dealing with GUIDs. They are designed to enhance the robustness and
* reliability of the GUID generation process by providing clear and meaningful error messages to
* the developers.
* <p>
* Developers using the GUID generation module should be aware of the possible
* exceptions that can be thrown and handle them appropriately to ensure smooth
* operation and error handling in their applications.
* Developers using the GUID generation module should be aware of the possible exceptions that can
* be thrown and handle them appropriately to ensure smooth operation and error handling in
* their applications.
*
* @since 1.0.0
*/
guid/src/main/java/com/onixbyte/guid/impl/SnowflakeGuidCreator.java
+22 -27
View File
@@ -24,10 +24,9 @@ import java.time.LocalDateTime;
import java.time.ZoneId;
/**
* The {@code SnowflakeGuidCreator} generates unique identifiers using the
* Snowflake algorithm, which combines a timestamp, worker ID, and data centre
* ID to create 64-bit long integers. The bit distribution for the generated
* IDs is as follows:
* The {@code SnowflakeGuidCreator} generates unique identifiers using the Snowflake algorithm,
* which combines a timestamp, worker ID, and data centre ID to create 64-bit long integers. The bit
* distribution for the generated IDs is as follows:
* <ul>
* <li>1 bit for sign</li>
* <li>41 bits for timestamp (in milliseconds)</li>
@@ -36,11 +35,10 @@ import java.time.ZoneId;
* <li>12 bits for sequence number (per millisecond)</li>
* </ul>
* <p>
* When initializing a {@link SnowflakeGuidCreator}, you must provide the
* worker ID and data centre ID, ensuring they are within the valid range
* defined by the bit size. The generator maintains an internal sequence number
* that increments for IDs generated within the same millisecond. If the system
* clock moves backward, an exception is thrown to prevent generating IDs with
* When initializing a {@link SnowflakeGuidCreator}, you must provide the worker ID and data centre
* ID, ensuring they are within the valid range defined by the bit size. The generator maintains an
* internal sequence number that increments for IDs generated within the same millisecond. If the
* system clock moves backward, an exception is thrown to prevent generating IDs with
* repeated timestamps.
*
* @author Zihlu Wang
@@ -50,8 +48,8 @@ import java.time.ZoneId;
public final class SnowflakeGuidCreator implements GuidCreator<Long> {
/**
* Constructs a SnowflakeGuidGenerator with the default start epoch and
* custom worker ID, data centre ID.
* Constructs a SnowflakeGuidGenerator with the default start epoch and custom worker ID, data
* centre ID.
*
* @param dataCentreId the data centre ID (between 0 and 31)
* @param workerId the worker ID (between 0 and 31)
@@ -61,16 +59,13 @@ public final class SnowflakeGuidCreator implements GuidCreator<Long> {
}
/**
* Constructs a SnowflakeGuidGenerator with a custom epoch, worker ID, and
* data centre ID.
* Constructs a SnowflakeGuidGenerator with a custom epoch, worker ID, and data centre ID.
*
* @param dataCentreId the data centre ID (between 0 and 31)
* @param workerId the worker ID (between 0 and 31)
* @param startEpoch the custom epoch timestamp (in milliseconds) to
* start generating IDs from
* @throws IllegalArgumentException if the start epoch is greater than the
* current timestamp, or if the worker ID
* or data centre ID is out of range
* @param startEpoch the custom epoch timestamp (in milliseconds) to start generating IDs from
* @throws IllegalArgumentException if the start epoch is greater than the current timestamp,
* or if the worker ID or data centre ID is out of range
*/
public SnowflakeGuidCreator(long dataCentreId, long workerId, long startEpoch) {
if (startEpoch > currentTimestamp()) {
@@ -98,37 +93,37 @@ public final class SnowflakeGuidCreator implements GuidCreator<Long> {
* Generates the next unique ID.
*
* @return the generated unique ID
* @throws TimingException if the system clock moves backwards,
* indicating an invalid sequence of timestamps.
* @throws TimingException if the system clock moves backwards, indicating an invalid sequence
* of timestamps.
*/
@Override
public synchronized Long nextId() {
var timestamp = currentTimestamp();
// If the current time is less than the timestamp of the last ID generation, it means that the system clock
// has been set back and an exception should be thrown.
// if the current time is less than the timestamp of the last ID generation, it means that
// the system clock has been set back and an exception should be thrown
if (timestamp < lastTimestamp) {
throw new TimingException("Clock moved backwards. Refusing to generate id for %d milliseconds"
.formatted(lastTimestamp - timestamp));
}
// If generated at the same time, perform intra-millisecond sequences
// if generated at the same time, perform intra-millisecond sequences
long sequenceBits = 12L;
if (lastTimestamp == timestamp) {
long sequenceMask = ~(-1L << sequenceBits);
sequence = (sequence + 1) & sequenceMask;
// Sequence overflow in milliseconds
// sequence overflow in milliseconds
if (sequence == 0) {
// Block to the next millisecond, get a new timestamp
// block to the next millisecond, get a new timestamp
timestamp = awaitToNextMillis(lastTimestamp);
}
}
// Timestamp change, sequence reset in milliseconds
// timestamp change, sequence reset in milliseconds
else {
sequence = 0L;
}
// Timestamp of last ID generation
// timestamp of last ID generation
lastTimestamp = timestamp;
// shifted and put together by or operations to form a 64-bit ID
guid/src/main/java/com/onixbyte/guid/package-info.java
+3 -5
View File
@@ -16,12 +16,10 @@
*/
/**
* The package provides a set of tools for generating globally unique
* identifiers (GUIDs).
* The package provides a set of tools for generating globally unique identifiers (GUIDs).
* <p>
* The goal of this library is to provide an efficient, reliable way to
* generate globally unique identifiers without requiring any specific
* environment or configuration.
* The goal of this library is to provide an efficient, reliable way to generate globally unique
* identifiers without requiring any specific environment or configuration.
* <p>
* Key features include:
* <ul>