+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+krontab
+
+
+
+
+
+
+
+Library was created to give oppotunity to launch some things from time to time according to some schedule in
+runtime of applications.
+How to use
+There are several ways to configure and use this library:
+
+- From some string
+- From builder
+
+Anyway, to start some action from time to time you will need to use one of extensions/functions:
+val kronScheduler = /* creating of KronScheduler instance */;
+
+kronScheduler.doWhile {
+ // some action
+ true // true - repeat on next time
+}
+
Including in project
+If you want to include krontab in your project, just add next line to your
+dependencies part:
+implementation "dev.inmo:krontab:$krontab_version"
+
Next version is the latest currently for the library:
+
+For old version of Gradle, instead of implementation word developers must use compile.
+Config from string
+Developers can use more simple way to configure repeat times is string. String configuring
+like a crontab, but with a little bit different meanings:
+/--------------- Seconds
+| /------------- Minutes
+| | /----------- Hours
+| | | /--------- Days of months
+| | | | /------- Months
+| | | | | /----- (optional) Year
+| | | | | | /--- (optional) Timezone offset
+| | | | | | | / (optional) Week days
+* * * * * * 0o *w
+
It is different with original crontab syntax for the reason, that expected that in practice developers
+will use seconds and minutes with more probability than months (for example) or even years. In fact, developers will use
+something like:
+doWhile("/5 * * * *") {
+ println("Called")
+ true // true - repeat on next time
+}
+
An other version:
+doInfinity("/5 * * * *") {
+ println("Called")
+}
+
Both of examples will print Called message every five seconds.
+Config via builder
+Also, this library currently supports DSL for creating the same goals:
+val kronScheduler = buildSchedule {
+ seconds {
+ from (0) every 5
+ }
+}
+kronScheduler.doWhile {
+ println("Called")
+ true // true - repeat on next time
+}
+
Or
+val kronScheduler = buildSchedule {
+ seconds {
+ 0 every 5
+ }
+}
+kronScheduler.doWhile {
+ println("Called")
+ true // true - repeat on next time
+}
+
Or
+val kronScheduler = buildSchedule {
+ seconds {
+ 0 every 5
+ }
+}
+kronScheduler.doInfinity {
+ println("Called")
+}
+
All of these examples will do the same things: print Called message every five seconds.
+do* functions
+With regular doOnce/doWhile/doInfinity there are two types of their variations: local and timezoned. Local
+variations (doOnceLocal/doWhileLocal/doInfinityLocal) will pass DateTime as an argument into the block:
+doInfinityLocal("/5 * * * *") {
+ println(it) // will print current date time
+}
+
Timezoned variations (doOnceTz/doWhileTz/doInfinityTz) will do the same thing but pass as an argument DateTimeTz:
+doInfinityTz("/5 * * * * 0o") {
+ println(it) // will print current date time in UTC
+}
+
It is useful in cases when you need to get the time of calling and avoid extra calls to system time.
+Helpful table for
+
+
+
+ |
+No args |
+Local DateTime |
+Local DateTimeTz with offset of KronScheduler |
+
+
+
+
+| Call only near time |
+doOnce |
+doOnceLocal |
+doOnceTz |
+
+
+| Call while condition is true |
+doWhile |
+doWhileLocal |
+doWhileTz |
+
+
+| Work infinity* |
+doInfinity |
+doInfinityLocal |
+doInfinityTz |
+
+
+
+*Here there is an important notice, that Work infinity is not exactly infinity. Actually, that means that do while
+coroutine is alive and in fact executing will be stopped when coroutine became cancelled.
+KronScheduler as a Flow
+Any KronSchedulercan e converted to a Flow<DateTime using extension asFlow:
+val kronScheduler = buildSchedule {
+ seconds {
+ 0 every 1
+ }
+}
+
+val flow = kronScheduler.asFlow()
+
So, in this case any operations related to flow are available and it is expected that they will work correctly. For
+example, it is possible to use this flow with takeWhile:
+flow.takeWhile {
+ condition()
+}.collect {
+ action()
+}
+
Offsets
+Offsets in this library works via passing parameter ending with o in any place after month config. Currently
+there is only one format supported for offsets: minutes of offsets. To use time zones you will need to call next
+method with DateTimeTz argument or nextTimeZoned method with any KronScheduler instance, but in case if this
+scheduler is not instance of KronSchedulerTz it will work like you passed just DateTime.
+Besides, in case you wish to use time zones explicitly, you will need to get KronSchedulerTz. It is possible by:
+
+- Using
createSimpleScheduler/buildSchedule/KrontabTemplate#toSchedule/KrontabTemplate#toKronScheduler methods
+ with passing defaultOffset parameter
+- Using
SchedulerBuilder#build/createSimpleScheduler/buildSchedule/KrontabTemplate#toSchedule/KrontabTemplate#toKronScheduler
+ methods with casting to KronSchedulerTz in case you are pretty sure that it is timezoned KronScheduler
+- Creating your own implementation of
KronSchedulerTz
+
+Note about week days
+Unlike original CRON, here week days:
+
+- Works as
AND: cron date time will search first day which will pass requirement according all parameters including
+ week days
+- You may use any related to numbers syntax with week days:
0-3w, 0,1,2,3w, etc.
+- Week days (like years and offsets) are optional and can be placed anywhere after
month
+
+
+
+
+
+
+
+
+
+