Krontab

This project was inspired by a Linux util Crontab. In context of this library you will have opportunity to set up scheduled running of some things. In the base realization it works on the Kotlin Coroutines

Introduction tutorial

Here will be described examples and some easy how-to-use steps and things

Introduction tutorial

Including in project

In two words, you must add dependency dev.inmo:krontab:$krontab_version to your project. The latest version presented by next badge:

Maven Central

Notice about repository

To use this library, you will need to include MavenCentral repository in you project

build.gradle
mavenCentral()

Dependencies

Next snippets must be placed into your dependencies part of build.gradle (for gradle) or pom.xml (for maven).

Gradle

implementation "dev.inmo:krontab:$krontab_version"

Maven

<dependency>
    <groupId>dev.inmo</groupId>
    <artifactId>krontab</artifactId>
    <version>${krontab_version}</version>
</dependency>
Introduction tutorial

How to use

Previous pages

buildSchedule

Custom KronScheduler
You always able to create your own scheduler. In this section will be presented different ways and examples around standard CronDateTimeScheduler builders buildSchedule. You can read about schedulers in KrontabScheduler

Currently, buildSchedule is the recommended start point for every scheduler. Usually, it is look like:

val scheduler = buildSchedule("5 * * * *")

Or:

val scheduler = buildSchedule {
  seconds {
    at(5)
  }
}

On the top of any KronScheduler currently there are several groups of extensions:

Executes

All executes are look like do.... All executes are described below:

Shortcuts

Shortcuts are the constants that are initializing in a lazy way to provide preset KronSchedulers. For more info about KrontabScheduler you can read its own page.

Flows

Here currently there is only one extension for KronScheduler: KronScheduler#asFlow. As a result you will get Flow<DateTime> (in fact SchedulerFlow) which will trigger next emit on each not null next DateTime

Introduction tutorial

FAQ

How oftern new versions are releasing?

Not very often. It depend on libraries (coroutines, korlibs/klock) updates and on some new awesome, but lightweight, features coming.

Where this library could be useful?

First of all, this library will be useful for long uptime applications which have some tasks to do from time to time.

How to use crontab-like syntax?

In two words, you should call buildSchedule or createSimpleScheduler:

buildSchedule("5 * * * *").asFlow().collect { /* do something */ }

You can read more about syntax in String format section.

Describing

In this chapter will be described how and why library things working as they working

Describing

String format

As in crontab util, this library have almost the same format of string:

Seconds Minutes Hours Days of months Months Years Timezone Offset Week days Milliseconds
Range 0..59 0..59 0..23 0..30 0..11 Any Int Any Int 0..6 0..999
Suffix - - - - - - o w ms
Optional
Full syntax support
Position 0 1 2 3 4 Any after months Any after months Any after months Any after months
Examples 0, */15, 30 0, */15, 30 0, */15, 22 0, */15, 30 0, */5, 11 0, */15, 30 60o (UTC+1) 0w, */2w, 4w 0ms, */150ms, 300ms

Example with almost same description:

/-------------------- (0-59) ············ Seconds
| /------------------ (0-59) ············ Minutes
| | /---------------- (0-23) ············ Hours
| | | /-------------- (0-30) ············ Days of months
| | | | /------------ (0-11) ············ Months
| | | | | /---------- (optional, any int) Year
| | | | | | /-------- (optional) ········ Timezone offset
| | | | | | |  /----- (optional, 0-6) ··· Week days
| | | | | | |  |  /-- (optional, 0-999) · Milliseconds (0 by default)
* * * * * * 0o *w 0ms

Years, timezone, week days and milliseconds are optional settings. Next snippets are equal:

*/15 * * * *
*/15 * * * * * // with year
*/15 * * * * * 0ms // with year and milliseconds

Supported syntax

Currently the library support next syntax for date/time elements:

Ranges

Ranges are working like common rangeTo (or ..) in kotlin:

0-5 * * * *

In the example above scheduler will trigger every second from the beginning of the minute up to fifth second of minute.

Start/Step

Start/step is a little bit more complicated syntax. It means start from the first element, repeat triggering every second element. Examples:

5/15 * * * *

Means that each minute starting from fifth second it will repeat triggering every fifteenth second: 5, 20, 35, 50.

Every

Every is more simple syntax and could be explained as a shortcut for 0/{int}. Example:

*/15 * * * *

Means that each minute it will repeat triggering every fifteenth second: 0, 15, 30, 45.

Just at the time

The most simple syntax. It means, that scheduler will call triggering every time when element was reached:

15 * * * *

Means that each minute scheduler will call triggering at the fifteenth second.

Listing

All the previous elements can be combined with listing. Lets just see several examples:

0,10 * * * *

Will trigger every minute at the 0 and 10 seconds (see Just at the time)

0-5,10 * * * *

Will trigger every minute from 0 to 5 seconds and at the 10 seconds (see Ranges)

Examples

Describing

KrontabScheduler

KronScheduler is the simple interface with only one function next. This function optionally get as a parameter DateTime which will be used as start point for the calculation of next trigger time. This function will return the next DateTime when something must happen.

Default realisation

Default realisation (CronDateTimeScheduler) can be created using several ways:

In the examples below the result of created scheduler will be the same.

Crontab-like way

Crontab-like syntax
See String format for more info about the crontab-line syntax

This way will be very useful for cases when you need to configure something via external configuration (from file on startup or via some parameter from requests, for example):

val schedule = "5 * * * *"
val scheduler = buildSchedule(schedule)

scheduler.asFlow().onEach {
  // this block will be called every minute at 5 seconds
}.launchIn(someCoroutineScope)

Lambda way

In case of usage builder (lets call it lambda way), you will be able to configure scheduler in more type-safe way:

val scheduler = buildSchedule {
  seconds {
    at(5)
  }
}

scheduler.asFlow().onEach {
  // this block will be called every minute at 5 seconds
}.launchIn(someCoroutineScope)

Custom scheduler

You are always able to use your own realisation of scheduler. For example:

class RandomScheduler : KronScheduler {
  override suspend fun next(relatively: DateTime): DateTime {
    return relatively + DateTimeSpan(seconds = Random.nextInt() % 60)
  }
}

In the example above we have created RandomScheduler, which will return random next time in range 0-60 seconds since relatively argument.