Skip to content

Commit 42d40c3

Browse files
author
zihluwang
committed
docs: updated readme
1 parent 0b04bf2 commit 42d40c3

File tree

3 files changed

+55
-205
lines changed

3 files changed

+55
-205
lines changed

‎devkit-core/README.md‎

Lines changed: 1 addition & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -10,10 +10,4 @@ This whole `JDevKit` is developed by **JDK 17**, which means you have to use JDK
1010

1111
## Installation
1212

13-
You don't have to install this module at all, any module which is from `JDevKit` contains this `devkit-core` module.
14-
15-
## Contact
16-
17-
If you have any suggestions, ideas, don't hesitate contacting us via [GitHub Issues](https://github.com/CodeCraftersCN/jdevkit/issues/new) or [Discord Community](https://discord.gg/NQK9tjcBB8).
18-
19-
If you face any bugs while using our library and you are able to fix any bugs in our library, we would be happy to accept pull requests from you on [GitHub](https://github.com/CodeCraftersCN/jdevkit/compare).
13+
You don't have to install this module at all, any module which is from `JDevKit` contains this `devkit-core` module.

‎devkit-utils/README.md‎

Lines changed: 24 additions & 160 deletions
Original file line numberDiff line numberDiff line change
@@ -2,189 +2,53 @@
22

33
## Introduction
44

5-
This module is part of `JDevKit`, an open-source Java Development Kit that provides a set of convenient tools to streamline code development and enhance productivity. This module serves as the useful toolkit for the library, contains a collection of utility classes commonly used in all Java Application development.
5+
This module is part of `JDevKit`, an open-source Java Development Kit that provides a set of
6+
convenient tools to streamline code development and enhance productivity. This module serves as the
7+
useful toolkit for the library, contains a collection of utility classes commonly used in all Java
8+
Application development.
69

710
## Prerequisites
811

9-
This whole `JDevKit` is developed by **JDK 17**, which means you have to use JDK 17 for better experience.
12+
This whole `JDevKit` is developed by **JDK 17**, which means you have to use JDK 17 for
13+
better experience.
1014

1115
## Installation
1216

1317
### If you are using `Maven`
1418

15-
It is quite simple to install this module by `Maven`. The only thing you need to do is find your `pom.xml` file in the project, then find the `<dependencies>` node in the `<project>` node, and add the following codes to `<dependencies>` node:
19+
It is quite simple to install this module by `Maven`. The only thing you need to do is find your
20+
`pom.xml` file in the project, then find the `<dependencies>` node in the `<project>` node, and add
21+
the following codes to `<dependencies>` node:
1622

1723
```xml
1824
<dependency>
19-
<groupId>cn.org.codecrafters</groupId>
25+
<groupId>com.onixbyte</groupId>
2026
<artifactId>devkit-utils</artifactId>
2127
<version>${devkit-utils.version}</version>
2228
</dependency>
2329
```
2430

25-
And run `mvn dependency:get` in your project root folder(i.e., if your `pom.xml` is located at `/path/to/your/project/pom.xml`, then your current work folder should be `/path/to/your/project`), then `Maven` will automatically download the `jar` archive from `Maven Central Repository`. This could be **MUCH EASIER** if you are using IDE(i.e., IntelliJ IDEA), the only thing you need to do is click the refresh button of `Maven`.
31+
And run `mvn dependency:get` in your project root folder(i.e., if your `pom.xml` is located at
32+
`/path/to/your/project/pom.xml`, then your current work folder should be `/path/to/your/project`),
33+
then `Maven` will automatically download the `jar` archive from `Maven Central Repository`. This
34+
could be **MUCH EASIER** if you are using IDE(i.e., IntelliJ IDEA), the only thing you need to do
35+
is click the refresh button of `Maven`.
2636

27-
If you are restricted using the Internet, and have to make `Maven` offline, you could follow the following steps.
37+
If you are restricted using the Internet, and have to make `Maven` offline, you could follow the
38+
following steps.
2839

29-
1. Download the `jar` file from any place you can get and transfer the `jar` files to your work computer.
30-
2. Move the `jar` files to your local `Maven` Repository as the path of `/path/to/maven_local_repo/cn/org/codecrafters/devkit-utils/`.
40+
1. Download the `jar` file from any place you can get and transfer the `jar` files to your
41+
work computer.
42+
2. Move the `jar` files to your local `Maven` Repository as the path of
43+
`/path/to/maven_local_repo/com/onixbyte/devkit-utils/`.
3144

3245
### If you are using `Gradle`
3346

3447
Add this module to your project with `Gradle` is much easier than doing so with `Maven`.
3548

36-
Find `build.gradle` in the needed project, and add the following code to the `dependencies` closure in the build script:
49+
Find `build.gradle` in the needed project, and add the following code to the `dependencies` closure
50+
in the build script:
3751

3852
```groovy
39-
implementation 'cn.org.codecrafters:devkit-utils:${devkit-utils.version}'
53+
implementation 'com.onixbyte:devkit-utils:${devkit-utils.version}'
4054
```
41-
42-
### If you are not using `Maven` or `Gradle`
43-
44-
1. Download the `jar` file from the Internet.
45-
2. Create a folder in your project and name it as a name you like(i.e., for me, I prefer `vendor`).
46-
3. Put the `jar` file to the folder you just created in Step 2.
47-
4. Add this folder to your project `classpath`.
48-
49-
### Base64 Encode and Decode
50-
51-
If you are trying to encode a string to Base64 string or decode a Base64 string to normal string, then you can try this:
52-
53-
```java
54-
import utils.com.onixbyte.devkit.Base64Util;
55-
56-
// To reduce sample codes, let me use the simplified main method that is upcoming in Java 21
57-
void main(String... args) {
58-
var aString = "The string you need to encode.";
59-
// Encode it from original text.
60-
var encodedString = Base64Util.encode(aString);
61-
// Decode the encoded text.
62-
var decodedString = Base64Util.decode(encodedString);
63-
}
64-
```
65-
66-
## Reduce `if...else...`
67-
68-
I believe those `if...else...` blocks make you headache, and Java imported lambda since Java 8, why not try to replace those `if...else` with lambda expressions?
69-
70-
```java
71-
import utils.com.onixbyte.devkit.BranchUtil;
72-
73-
void main(String... args) {
74-
var a = 1;
75-
var b = 2;
76-
77-
if (a < b) {
78-
// do something...
79-
} else {
80-
// do something different...
81-
}
82-
// The codes above is really annoying, have a try of the lambda version.
83-
84-
BranchUtil.or(a < b) // If multiple logical expressions are combined using the OR operator.
85-
.handle(() -> {
86-
// do something if a < b.
87-
}, () -> {
88-
// do something if a > b.
89-
});
90-
91-
BranchUtil.and(a < b) // If multiple logical expressions are combined using the AND operator
92-
.handle(() -> {
93-
// do something if a < b.
94-
}, () -> {
95-
// do something if a > b.
96-
});
97-
}
98-
```
99-
100-
What if you have to get some data from this branch? Don't worry, those **lambda supports Supplier**. Just add a return in those lambda is fine.
101-
102-
## CHAINED High-precision Calculation
103-
104-
If you have faced high-precision mathematical calculation in Java, you might know it is very troubled to do it in **ANY** programming languages. I'm certain you remember that `0.1 + 0.2 != 0.3` right?
105-
106-
In Java, we usually do high-precision mathematical calculation with `BigDecimal` which is quite tricky when using it.
107-
108-
```java
109-
import utils.com.onixbyte.devkit.ChainedCalcUtil;
110-
111-
void main(String... args) {
112-
// If you are trying to calculate the expression of 1 * 2 / 2 - 3 + 4
113-
ChainedCalcUtil.startWith(1).multiply(2).divide(2).subtract(3).add(4).getInteger(); // you can also get a double by getDouble([int scale]), get a BigDecimal by getDecimal([int scale]) or get a long by getLong().
114-
}
115-
```
116-
117-
If you are facing a divide calculation which has an infinite decimal expansion, then DON'T use `divide(dividend)`, use `divideWithScale(dividend, scale, [beforeOperateScale])`.
118-
119-
## Hash a `String`
120-
121-
As is well known, storing plain text passwords in a database is very insecure. Therefore, you need to encrypt the passwords stored in the database, or at least make it difficult for hackers to see the real password at a glance. As a result, hash calculation is often used in database password obfuscation due to its ease of use.
122-
123-
This `HashUtil` supports these following hash or message digest algorithms:
124-
125-
- MD2
126-
- MD5
127-
- SHA-1
128-
- SHA-224
129-
- SHA-256
130-
- SHA-384
131-
- SHA-512
132-
133-
If you want to run a hash calculation to a string, you can use the following codes:
134-
135-
```java
136-
import utils.com.onixbyte.devkit.HashUtil;
137-
138-
void main(String... args) {
139-
var plaintext = "This is a plain text";
140-
var hashedText = HashUtil.md2(plaintext); // if you want to use other algorithm, just change the method name such as md5, sha1, sha224 and so on.
141-
}
142-
```
143-
144-
Besides, if you want to use other character set to do the hash calculation, you can add the specified charset after the text to be calculated.
145-
146-
```java
147-
HashUtil.$algorithm$(String textToCalculate, Charset charset);
148-
```
149-
150-
## Convert a Map to Any Object and Vice Versa
151-
152-
A Map is a data structure that allows you to store key-value pairs. The keys can be of any type and the values can be of any type. In this case, the key is the user's name and the value is the user's profile.
153-
154-
Imagine you are developing a website where users can register an account and store their profile. A profile can contain information like their name, age, address, and email address. You store the user's profile in a Map. When the user registers an account, you need to store their profile in a database. A database is a system for storing data. A database can store any type of data, including Maps.
155-
156-
In order to store the Map in a database, you need to convert the Map to an Object. An Object is a generic data type that can store any type of data.
157-
158-
```java
159-
import utils.com.onixbyte.devkit.MapUtil;
160-
161-
class Data {
162-
private String name;
163-
private Long id;
164-
private Integer age;
165-
166-
// Setters and getters here.
167-
168-
// No-args constructor and all-args constructor here.
169-
}
170-
171-
void main(String... args) {
172-
// Create a map.
173-
var dataMap = new HashMap<String, Object>();
174-
dataMap.put("name", "Zihlu Wang");
175-
dataMap.put("id", 1L);
176-
dataMap.put("age", 18);
177-
178-
// Convert this map to an instance of class Data
179-
var data = MapUtil.mapToObject(dataMap, Data.class); // Then you got an instance of Data("Zihlu Wang", 1L, 18);
180-
181-
// Then you can convert this object to a map.
182-
var anotherDataMap = MapUtil.objectToMap(data)
183-
}
184-
```
185-
186-
## Contact
187-
188-
If you have any suggestions, ideas, don't hesitate contacting us via [GitHub Issues](https://github.com/CodeCraftersCN/jdevkit/issues/new) or [Discord Community](https://discord.gg/NQK9tjcBB8).
189-
190-
If you face any bugs while using our library and you are able to fix any bugs in our library, we would be happy to accept pull requests from you on [GitHub](https://github.com/CodeCraftersCN/jdevkit/compare).

‎guid/README.md‎

Lines changed: 30 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -2,45 +2,63 @@
22

33
## Introduction
44

5-
Module `guid` is a library that provides utilities for generating and working with globally unique identifiers (GUIDs). GUIDs are globally unique across all devices and systems, making them ideal for various use cases like database record keys, distributed systems, and tracking objects.
5+
Module `guid` is a library that provides utilities for generating and working with globally unique
6+
identifiers (GUIDs). GUIDs are globally unique across all devices and systems, making them ideal
7+
for various use cases like database record keys, distributed systems, and tracking objects.
68

7-
The `guid` module offers a reliable and efficient GUID generator, allowing developers to create unique identifiers with low collision probability. It also provides features to customize the format of generated GUIDs, making it flexible and suitable for different applications.
9+
The `guid` module offers a reliable and efficient GUID generator, allowing developers to create
10+
unique identifiers with low collision probability. It also provides features to customize the
11+
format of generated GUIDs, making it flexible and suitable for different applications.
812

9-
With `guid`, developers can easily integrate globally unique identifiers into their projects, ensuring data integrity, avoiding duplicates, and simplifying the identification of objects across various systems. The module is designed to be simple to use, highly performant, and compatible with different programming languages and frameworks.
13+
With `guid`, developers can easily integrate globally unique identifiers into their projects,
14+
ensuring data integrity, avoiding duplicates, and simplifying the identification of objects across
15+
various systems. The module is designed to be simple to use, highly performant, and compatible with
16+
different programming languages and frameworks.
1017

1118
## Prerequisites
1219

13-
This whole `JDevKit` is developed by **JDK 17**, which means you have to use JDK 17 for better experience.
20+
This whole `JDevKit` is developed by **JDK 17**, which means you have to use JDK 17 for
21+
better experience.
1422

1523
## Installation
1624

1725
### If you are using `Maven`
1826

19-
It is quite simple to install this module by `Maven`. The only thing you need to do is find your `pom.xml` file in the project, then find the `<dependencies>` node in the `<project>` node, and add the following codes to `<dependencies>` node:
27+
It is quite simple to install this module by `Maven`. The only thing you need to do is find your
28+
`pom.xml` file in the project, then find the `<dependencies>` node in the `<project>` node, and add
29+
the following codes to `<dependencies>` node:
2030

2131
```xml
2232
<dependency>
23-
<groupId>cn.org.codecrafters</groupId>
33+
<groupId>com.onixbyte</groupId>
2434
<artifactId>devkit-utils</artifactId>
2535
<version>${devkit-utils.version}</version>
2636
</dependency>
2737
```
2838

29-
And run `mvn dependency:get` in your project root folder(i.e., if your `pom.xml` is located at `/path/to/your/project/pom.xml`, then your current work folder should be `/path/to/your/project`), then `Maven` will automatically download the `jar` archive from `Maven Central Repository`. This could be **MUCH EASIER** if you are using IDE(i.e., IntelliJ IDEA), the only thing you need to do is click the refresh button of `Maven`.
39+
And run `mvn dependency:get` in your project root folder(i.e., if your `pom.xml` is located at
40+
`/path/to/your/project/pom.xml`, then your current work folder should be `/path/to/your/project`),
41+
then `Maven` will automatically download the `jar` archive from `Maven Central Repository`. This
42+
could be **MUCH EASIER** if you are using IDE(i.e., IntelliJ IDEA), the only thing you need to do
43+
is click the refresh button of `Maven`.
3044

31-
If you are restricted using the Internet, and have to make `Maven` offline, you could follow the following steps.
45+
If you are restricted using the Internet, and have to make `Maven` offline, you could follow the
46+
following steps.
3247

33-
1. Download the `jar` file from any place you can get and transfer the `jar` files to your work computer.
34-
2. Move the `jar` files to your local `Maven` Repository as the path of `/path/to/maven_local_repo/cn/org/codecrafters/devkit-utils/`.
48+
1. Download the `jar` file from any place you can get and transfer the `jar` files to your work
49+
computer.
50+
2. Move the `jar` files to your local `Maven` Repository as the path of
51+
`/path/to/maven_local_repo/com/onixbyte/devkit-utils/`.
3552

3653
### If you are using `Gradle`
3754

3855
Add this module to your project with `Gradle` is much easier than doing so with `Maven`.
3956

40-
Find `build.gradle` in the needed project, and add the following code to the `dependencies` closure in the build script:
57+
Find `build.gradle` in the needed project, and add the following code to the `dependencies` closure
58+
in the build script:
4159

4260
```groovy
43-
implementation 'cn.org.codecrafters:devkit-utils:${devkit-utils.version}'
61+
implementation 'com.onixbyte:guid:${guid.version}'
4462
```
4563

4664
### If you are not using `Maven` or `Gradle`
@@ -49,29 +67,3 @@ implementation 'cn.org.codecrafters:devkit-utils:${devkit-utils.version}'
4967
2. Create a folder in your project and name it as a name you like(i.e., for me, I prefer `vendor`).
5068
3. Put the `jar` file to the folder you just created in Step 2.
5169
4. Add this folder to your project `classpath`.
52-
53-
## Implement a `GuidCreator`
54-
55-
You can build your own `GuidCreator` by implements the interface `GuidCreator`. This interface accepts a type parameter which determine the type of the GUID.
56-
57-
## Generate a `guid` with Snowflake Algorithm
58-
59-
If you are willing to use Snowflake algorithm to create a guid, just use `SnowflakeGuidCreator` is find. To create a guid in Snowflake algorithm, you'll need an instance of `SnowflakeGuidCreator` first.
60-
61-
To create an instance of `SnowflakeGuidCreator`, you should use its constructor.
62-
63-
```java
64-
var guidCreator = new SnowflakeGuidCreator(long workerId, long dataCentreId[, long startEpoch]);
65-
```
66-
67-
Then, use the instance to create a guid.
68-
69-
```java
70-
long guid = guidCreator.nextId();
71-
```
72-
73-
## Contact
74-
75-
If you have any suggestions, ideas, don't hesitate contacting us via [GitHub Issues](https://github.com/CodeCraftersCN/jdevkit/issues/new) or [Discord Community](https://discord.gg/NQK9tjcBB8).
76-
77-
If you face any bugs while using our library and you are able to fix any bugs in our library, we would be happy to accept pull requests from you on [GitHub](https://github.com/CodeCraftersCN/jdevkit/compare).

0 commit comments

Comments
 (0)