Skip to content

Commit 75f9bf3

Browse files
committed
docs(core): update document
1 parent 7967534 commit 75f9bf3

29 files changed

+397
-56
lines changed

docs/build.gradle.kts

+3
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
import cloud.playio.gradle.antora.tasks.AntoraCopyTask
22
import cloud.playio.gradle.generator.docgen.AsciidocGenTask
3+
import cloud.playio.gradle.shared.prop
34

45
plugins {
56
id(PlayioPlugin.antora)
@@ -19,10 +20,12 @@ documentation {
1920
antora {
2021
asciiAttributes.set(
2122
mapOf(
23+
"project-url" to "https://github.com/${prop(rootProject, "github.repo")}",
2224
"project-group" to project.group,
2325
"project-name" to mainProject,
2426
"project-version" to project.version,
2527
"vertx-version" to VertxLibs.Version.defaultVersion,
28+
"mutiny-version" to MutinyLibs.Version.mutiny,
2629
)
2730
)
2831
javadocTitle.set("${project.ext["title"]} ${project.version} API")
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
= Scheduler.x API Reference
22
:navtitle: API Reference
33

4-
Provides a straightforward API focusing on scalability and low overhead to create and run a time-based scheduler that relies on `Vert.x timer` or an event-based scheduler that relies on `Vert.x eventbus`.
4+
This API empowers you to seamlessly create and execute time-based and event-based schedulers. With its scalable and low-overhead design, it is the ultimate tool for all your scheduling requirements.
55

66
include::partial$nav-api-reference.adoc[]

docs/src/antora/modules/ROOT/pages/core-how-it-works.adoc

+6
Original file line numberDiff line numberDiff line change
@@ -21,3 +21,9 @@ The `scheduler` lifecycle event is one of:
2121
* The trigger is completed, which means no more scheduled fire time in the future.
2222

2323
== Flow
24+
25+
.How scheduler.x works
26+
[plantuml, how-it-works, format=svg, options=interactive]
27+
....
28+
include::partial$how-it-works.puml[]
29+
....
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,8 @@
11
= Scheduler.x Quickstart
22
:navtitle: Quickstart
33

4-
== Prerequisite
4+
`Scheduler.x` provides a builder pattern that allows you to create custom schedules for different business applications.
5+
6+
You can design a loop of recurrence from simple to complex in the `Trigger` object, step by step. After that, you can build a corresponding `Scheduler` object to manage the scheduling lifecycle, which contains a `Job` that performs your business operations.
7+
8+
include::partial$basic.adoc[tag=getStarted]

docs/src/antora/modules/ROOT/pages/core-usage.adoc

-18
Original file line numberDiff line numberDiff line change
@@ -60,21 +60,3 @@ dependencies {
6060
== Reactive version
6161

6262
Reference to xref:features-rxify.adoc[reactive version] for more detail.
63-
64-
== Logging
65-
66-
`scheduler.x` reuses the Vert.x logging mechanism. Please, refers to https://vertx.io/docs/vertx-core/java/#_logging
67-
68-
So in short, you can use `slf4j`, `log4j2`, or `jdk logging` by simple below configuration before start your application. Remember add your flavor log library in your classpath.
69-
70-
[source,java]
71-
----
72-
// for slf4j
73-
System.setProperty("vertx.logger-delegate-factory-class-name", "io.vertx.core.logging.SLF4JLogDelegateFactory");
74-
75-
// for log4j2
76-
System.setProperty("vertx.logger-delegate-factory-class-name", "io.vertx.core.logging.Log4j2LogDelegateFactory");
77-
78-
// fallback to jdk logging or config explicitly
79-
System.setProperty("vertx.logger-delegate-factory-class-name", "io.vertx.core.logging.JULLogDelegateFactory");
80-
----
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
= Configuration and Option
2+
3+
== Logging
4+
5+
`scheduler.x` reuses the Vert.x logging mechanism. Please, refers to https://vertx.io/docs/vertx-core/java/#_logging
6+
7+
So in short, you can use `slf4j`, `log4j2`, or `jdk logging` by simple below configuration before start your application. Remember add your flavor log library in your classpath.
8+
9+
[source,java]
10+
----
11+
// for slf4j
12+
System.setProperty("vertx.logger-delegate-factory-class-name", "io.vertx.core.logging.SLF4JLogDelegateFactory");
13+
14+
// for log4j2
15+
System.setProperty("vertx.logger-delegate-factory-class-name", "io.vertx.core.logging.Log4j2LogDelegateFactory");
16+
17+
// fallback to jdk logging or config explicitly
18+
System.setProperty("vertx.logger-delegate-factory-class-name", "io.vertx.core.logging.JULLogDelegateFactory");
19+
----
20+
21+
`scheduler.x` logging in very low level, you can enable it by
22+
23+
[source,xml]
24+
---
25+
<?xml version="1.0" encoding="UTF-8"?>
26+
<Configuration>
27+
<Loggers>
28+
<!-- other logger -->
29+
...
30+
<!-- LOG "io.github.zero88.schedulerx*" at TRACE level -->
31+
<Logger name="io.github.zero88.schedulerx" level="trace" />
32+
<!-- at TRACE level for `Scheduler` lifecycle -->
33+
<Logger name="io.github.zero88.schedulerx.Scheduler" level="trace" />
34+
<!-- at DEBUG level for `SchedulingLogMonitor` -->
35+
<Logger name="io.github.zero88.schedulerx.SchedulingLogMonitor" level="debug" />
36+
</Loggers>
37+
</Configuration>
38+
---
39+
40+
== Options
41+
42+
You have the power to assert your customization preferences by overriding the default `scheduler.x` configurations to suit your specific application requirements.
43+
44+
Check it out in xref:attachment$javadoc/io/github/zero88/schedulerx/DefaultOptions.html[DefaultOptions] javadoc.
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,9 @@
11
= Job
22

33
This is a place that does your business that you wish to have executed by the scheduler.
4+
5+
== How to implement Job
6+
7+
== Job Data
8+
9+
== Timeout control
Original file line numberDiff line numberDiff line change
@@ -1 +1,3 @@
11
= Monitor the scheduling
2+
3+
This feature helps you listen the event per scheduling lifecycle.

docs/src/antora/modules/ROOT/pages/features-rxify.adoc

+14-4
Original file line numberDiff line numberDiff line change
@@ -31,9 +31,9 @@ In your `pom.xml`
3131
<version>{mutiny-version}</version>
3232
</dependency>
3333
<dependency>
34-
<groupId>io.github.zero88</groupId>
35-
<artifactId>jooqx</artifactId>
36-
<version>{jooqx-version}</version>
34+
<groupId>{project-group}</groupId>
35+
<artifactId>{project-name}</artifactId>
36+
<version>{project-version}</version>
3737
</dependency>
3838
</dependencies>
3939
----
@@ -78,7 +78,7 @@ dependencies {
7878

7979
Well done, now you can enjoy `Rxify` version with a little effort
8080

81-
== Examples
81+
== Cookbook
8282

8383
=== `Rx3` - By `schedulerx` instance
8484

@@ -91,3 +91,13 @@ include::partial$features-rxify.adoc[tag=rx3Builder]
9191
=== `Mutiny` - By `schedulerx` builder
9292

9393
include::partial$features-rxify.adoc[tag=mutinyBuilder]
94+
95+
=== `Mutiny` Job
96+
97+
You can create a new `Job` that compatible to `Mutiny` version also
98+
99+
include::partial$features-rxify.adoc[tag=mutinyBuilderWithMutinyJob]
100+
101+
And then, pass it to the `Mutiny` builder
102+
103+
include::partial$features-rxify.adoc[tag=mutinyBuilderWithMutinyJob]
Original file line numberDiff line numberDiff line change
@@ -1 +1,3 @@
11
= Cron trigger
2+
3+
`CronTrigger` provides cron-based scheduling capabilities, making scheduling periodic jobs that recur based on calendar-like notions easier. It leverages the cron implementation in https://www.quartz-scheduler.org/[Quartz] to parse cron expressions and schedule jobs accordingly in the `Vert.x timer`.
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
= Trigger evaluator
2+
Original file line numberDiff line numberDiff line change
@@ -1 +1,10 @@
11
= Event trigger
2+
3+
An event trigger is a mechanism that initiates a certain action in response to an event or change in state.
4+
5+
`Vert.x` provides a nervous system called https://vertx.io/docs/vertx-core/java/#event_bus[event bus] that distributes the message around different parts of your application, or different applications and services to communicate with each other in a loosely coupled way.
6+
7+
`Scheduler.x` _Event Trigger_ acts as a `subscriber` in `publish/subscriber` messaging pattern of `event bus` system.
8+
9+
The advanced feature allows you to customize a *predicate* that converts event bus messages to expected message data, and then verify that the incoming data matches your configuration. If the condition is met, the `EventTrigger` will be activated to perform your business task.
10+
Original file line numberDiff line numberDiff line change
@@ -1 +1,5 @@
11
= Interval trigger
2+
3+
An interval trigger is a type of timer repeatedly at specified intervals.
4+
5+
For example, if you want the trigger to fire at exactly 00:30:00 AM on January 01, 2024, or if you want it to fire at that time, and then fire ten more times, every thirty seconds.
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
= Trigger
2+
3+
`Trigger` is a component defines the schedule upon which a given `Job` will be executed.
4+
There are different types of triggers that you can select from to meet different scheduling needs.
5+
6+
* xref:features-trigger-interval.adoc[Interval trigger]
7+
* xref:features-trigger-cron.adoc[Cron trigger]
8+
* xref:features-trigger-event.adoc[Event trigger]
9+
10+
There are some advanced configurations to enforce complex scheduling recurrences
11+
12+
* xref:features-trigger-rule.adoc[Trigger rule]
13+
* xref:features-trigger-evaluator.adoc[Trigger evaluator]
14+
15+
In order to help humans understand the configuration of triggers, you can utilize its representation.
16+
17+
* xref:features-trigger-repr.adoc[Trigger representation]
18+
19+
== Shutdown trigger
20+
21+
There are several ways to cancel the trigger
22+
23+
- By a specific `repeat` configuration in `IntervalTrigger`
24+
- By `until` configuration in `TriggerRule`
25+
- By marking `cancel` flag in the job execution
26+
27+
include::partial$basic.adoc[tag=CancelTriggerInJob]
28+
29+
- By manual `cancel` in `Scheduler`
30+
31+
include::partial$basic.adoc[tag=cancelInScheduler]
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
= Worker thread management

docs/src/antora/modules/ROOT/pages/index.adoc

+22-2
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ zero88
44

55
A pluggable `lightweight scheduler` based on plain https://vertx.io/[Vert.x] core without any external libs for scheduling on *time-based*: _cron_ and _interval_ or on *event-based*.
66

7-
`Scheduler.x` follows an event-driven architecture.
7+
`Scheduler.x` follows a modularization design and an event-driven architecture.
88

99
== Overview
1010

@@ -34,6 +34,26 @@ You can easily extend these interfaces to explore your task in the business mode
3434

3535
`Scheduler.x` is an event-driven system that decouple the job execution and job reporting.
3636

37-
Without requiring explicit notifications from the `Job` itself, the client application can register a scheduling monitor.
37+
Without requiring explicit notifications from the `Job` itself, the client application(your program) can register a scheduling monitor.
3838
Then, `Scheduler.x` can uniformly notify the client of any events occurring within the scheduler.
3939
These events may include the execution result after the trigger is fired and the job is executed, a trigger misfiring for some reason and so on.
40+
41+
=== Data JSON serializable
42+
43+
The component API in `scheduler.x` is designed to be friendly with https://vertx.io/docs/vertx-core/java/#_json[Vert.x JSON], is also compatible with https://github.com/FasterXML/jackson[Jackson].
44+
45+
This makes it easy to serialize all objects into a JSON-formatted string with minimal effort. The resulting string can be transmitted over a network or stored in a file or database, allowing you to store the work data configuration in your desired storage.
46+
47+
Once you restart your program, `scheduler.x` will deserialize the JSON data into appropriate objects, which will enable your scheduling work to continue seamlessly.
48+
49+
This allows `scheduler.x` to function in both stateful and stateless modes.
50+
51+
=== Modularization, fluent API and type-safe programming
52+
53+
`scheduler.x` is designed based on
54+
55+
* https://en.wikipedia.org/wiki/Modular_programming[modularity] mechanism is by breaking down the functionality into smaller independent parts that are extensible and interchangeable.
56+
* a https://martinfowler.com/bliki/FluentInterface.html[fluent API concept], where multiple methods calls can be chained together
57+
* type-safe programming, which enforces rules to ensure that operations are performed on compatible types.
58+
59+
I strongly believe that implementing this approach significantly reduces the likelihood of errors, enhances code clarity, maximizes extensibility, and simplifies maintenance for the client application.

docs/src/antora/modules/ROOT/pages/pg-copyright-and-license.adoc

+1-1
Original file line numberDiff line numberDiff line change
@@ -7,4 +7,4 @@ Copyright (C) 2021-present https://github.com/zero88[@zero88].
77

88
== License
99

10-
Use of Scheduler.x is granted under the terms of the https://github.com/zero88/jooqx/blob/main/LICENSE[Apache License 2.0].
10+
Use of Scheduler.x is granted under the terms of the {project-url}/blob/main/LICENSE[Apache License 2.0].

docs/src/antora/modules/ROOT/pages/pg-release-schedule.adoc

+1-1
Original file line numberDiff line numberDiff line change
@@ -26,4 +26,4 @@ Once a release candidate (rc) has been thoroughly tested, the stable release wil
2626
[#roadmap]
2727
== Roadmap
2828

29-
Refer to https://github.com/zero88/schedulerx/milestones[Scheduler.x’s milestones] and https://github.com/zero88/schedulerx/issues[issue tracker] for a list of the currently scheduled development tasks. The milestones are intended for informational purposes only. The proposed features, their scope, and the release timeframes are estimates, not firm commitments.
29+
Refer to {project-url}/milestones[Scheduler.x’s milestones] and {project-url}/issues[issue tracker] for a list of the currently scheduled development tasks. The milestones are intended for informational purposes only. The proposed features, their scope, and the release timeframes are estimates, not firm commitments.

docs/src/antora/modules/ROOT/pages/pg-upgrade-notes.adoc

+5-5
Original file line numberDiff line numberDiff line change
@@ -3,14 +3,14 @@
33

44
== From v1 to v2
55

6-
This is a list of importance breaking-changes from `v1` to `v2`: https://github.com/zero88/schedulerx/issues?q=label%3Abreaking-changes+milestone%3A%22Version+2.0.0-rc1%22[breaking-changes]
6+
This is a list of importance breaking-changes from `v1` to `v2`: {project-url}/issues?q=label%3Abreaking-changes+milestone%3A%222.0.0%22[breaking-changes]
77

8-
In most case, the main API that means how to initialize `schedulerx` instance and how to execute SQL query via `schedulerx`, was not changed.
9-
But, some importance changes in package/module level and project artifact name need to be updated by yourself:
8+
In most case, the main API that means how to initialize and start `schedulerx` instance was not changed. But, some importance changes in package/module level and project artifact name need to be updated by yourself:
109

1110
. Update library dependency:
12-
* Rename main artifact from `io.github.zero88:schedulerx-core` to `io.github.zero88:schedulerx`
11+
* Rename main artifact from `io.github.zero88:vertx-scheduler` to `io.github.zero88:schedulerx`
1312
* So you have to update the build descriptor. Follow xref:core-usage.adoc[]
1413

1514
. Change package name:
16-
* Replace all `import` statement in java files from `import io.zero88.schedulerx` => `import io.github.zero88.schedulerx`
15+
* Replace all `import` statement in java files from `import io.github.zero88.vertx.scheduler` => `import io.github.zero88.schedulerx`
16+
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
@startuml
2+
'https://plantuml.com/sequence-diagram
3+
skinparam ParticipantPadding 30
4+
skinparam BoxPadding 10
5+
skinparam backgroundColor #EEEBDC
6+
skinparam handwritten true
7+
8+
skinparam sequence {
9+
LifeLineBackgroundColor #ddd7ba
10+
11+
ParticipantBorderColor DeepSkyBlue
12+
ParticipantBackgroundColor DodgerBlue
13+
ParticipantFontName Impact
14+
ParticipantFontSize 17
15+
ParticipantFontColor #A9DCDF
16+
}
17+
18+
actor dev
19+
box "Vert.x event-loop threads" #LightYellow
20+
participant "Scheduler.x" as scheduler
21+
participant "Vertx Timer" as timer
22+
end box
23+
24+
box "Scheduler.x threads" #dce8ee
25+
collections "Worker threads" as worker
26+
collections "Monitor threads" as monitor
27+
end box
28+
participant "External system" as extSys
29+
extSys++
30+
31+
== Initialization ==
32+
dev -> scheduler++: Build an instance \nwith trigger and job
33+
dev -> scheduler: Start scheduler
34+
35+
scheduler -> timer++: register timer
36+
alt #Lightblue trigger is scheduled
37+
timer --> scheduler++#466ede: success
38+
scheduler -> monitor++#466ede: notify trigger \n**is scheduled** event
39+
monitor -> extSys--: publish **scheduled** result
40+
scheduler--
41+
else #ffe9f0 trigger is unable to scheduled
42+
timer --> scheduler++#f00: error
43+
scheduler -> monitor++#f00: notify trigger \n**is unscheduled** event
44+
monitor -> extSys--: publish **unscheduled** result
45+
scheduler--
46+
end alt
47+
48+
||10||
49+
== Scheduling Loop ==
50+
51+
loop
52+
timer -> scheduler++#fbb: tick timing event
53+
scheduler -> worker++: send trigger \nevaluation event
54+
||5||
55+
...evaluating trigger condition...
56+
alt #Lightblue trigger is READY
57+
worker --> scheduler++#5D935D: accepted
58+
worker++#5D935D
59+
worker--
60+
scheduler -> worker++#5D935D: send execution event
61+
||5||
62+
...executing the job...
63+
worker --> scheduler--: returns job result
64+
scheduler -> monitor++#5D935D: notify trigger \n**round is finished** event
65+
monitor -> extSys--: publish **job** result
66+
scheduler--
67+
else #ffe9f0 trigger is unable to run
68+
worker --> scheduler ++#gold: refused
69+
worker++#gold
70+
worker--
71+
scheduler -> monitor++#gold: notify trigger \n**tick is misfired** event
72+
monitor -> extSys--: publish **misfire** result
73+
scheduler--
74+
end alt
75+
worker--
76+
scheduler--
77+
||5||
78+
end group
79+
80+
||10||
81+
== Shutdown ==
82+
dev -> scheduler++#466ede: Cancel scheduler
83+
scheduler -> timer++#466ede: unregister timer
84+
return
85+
timer--
86+
scheduler -> monitor++#466ede: notify trigger \n**is completed** event
87+
monitor -> extSys--: publish **complete** result
88+
scheduler--
89+
90+
||5||
91+
scheduler--
92+
extSys--
93+
@enduml

0 commit comments

Comments
 (0)