Skip to content

# krontab

Library was created to give opportunity to launch some things from time to time according to some schedule in runtime of applications.

## How to use

Here you may find the builder for `Krontab` templates creation.

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
    }

Another 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 `KronScheduler` can be 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 (as well as years and offsets) are optional and can be placed anywhere after `month`