Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/knowm/Sundial

A Light-weight Job Scheduling Framework
https://github.com/knowm/Sundial

cron java quartz scheduled-jobs scheduler trigger

Last synced: about 2 months ago
JSON representation

A Light-weight Job Scheduling Framework

Awesome Lists containing this project

README

        

## [![Sundial](https://raw.githubusercontent.com/knowm/Sundial/develop/etc/Sundial_64_64.png)](http://knowm.org/open-source/sundial/) Sundial

A Lightweight Job Scheduling Framework for Java.

## In a Nutshell

Sundial makes adding scheduled jobs to your Java application a walk in the park. Simply define jobs, define triggers, and start the Sundial scheduler.

## Long Description

Sundial is a lightweight Java job scheduling framework forked from Quartz (http://www.quartz-scheduler.org/) stripped down to the bare essentials. Sundial also hides the nitty-gritty configuration details of Quartz, reducing the time needed to get a simple RAM job scheduler up and running. Sundial
uses a ThreadLocal wrapper for each job containing a HashMap for job key-value pairs. Convenience methods allow easy access to these parameters. JobActions are reusable components that also have access to the context parameters. If you are looking for a hassle-free 100% Java job scheduling framework that is easy to integrate into your applications, look no further.

## Features

* [x] Apache 2.0 license
* [x] ~150 KB Jar
* [x] In-memory multi-threaded jobs
* [x] Define jobs and triggers in jobs.xml
* [x] or define jobs and triggers via annotations
* [x] or define jobs and triggers programmatically
* [x] Cron Triggers
* [x] Simple Triggers
* [x] Java 8 and up
* [x] Depends only on slf4j

## Create a Job Class

```java
public class SampleJob extends org.knowm.sundial.Job {

@Override
public void doRun() throws JobInterruptException {
// Do something interesting...
}
}
```
## ...with CronTrigger or SimpleTrigger Annotation
```java
@CronTrigger(cron = "0/5 * * * * ?")
```
```java
@SimpleTrigger(repeatInterval = 30, timeUnit = TimeUnit.SECONDS)
```

## Start Sundial Job Scheduler

```java
public static void main(String[] args) {

SundialJobScheduler.startScheduler("org.knowm.sundial.jobs"); // package with annotated Jobs
}
```
If you need a bigger thread pool (default size is 10) use `startScheduler(int threadPoolSize, String annotatedJobsPackageName)` instead.

## Alternatively, Put an XML File Called jobs.xml on Classpath

```xml



SampleJob3
com.foo.bar.jobs.SampleJob3
true



SampleJob3-Trigger
SampleJob3
*/15 * * * * ?



SampleJob2
com.foo.bar.jobs.SampleJob2


MyParam
42





SampleJob2-Trigger
SampleJob2
5
5000

```

## Or, Define Jobs and Triggers Manually

```java
SundialJobScheduler.addJob("SampleJob", "org.knowm.sundial.jobs.SampleJob");
SundialJobScheduler.addCronTrigger("SampleJob-Cron-Trigger", "SampleJob", "0/10 * * * * ?");
SundialJobScheduler.addSimpleTrigger("SampleJob-Simple-Trigger", "SampleJob", -1, TimeUnit.SECONDS.toMillis(3));
```

## More Functions

```java
// asynchronously start a job by name
SundialJobScheduler.startJob("SampleJob");

// interrupt a running job
SundialJobScheduler.stopJob("SampleJob");

// remove a job from the scheduler
SundialJobScheduler.removeJob("SampleJob");

// remove a trigger from the scheduler
SundialJobScheduler.removeTrigger("SampleJob-Trigger");

// lock scheduler
SundialJobScheduler.lockScheduler();

// unlock scheduler
SundialJobScheduler.unlockScheduler();

// check if job a running
SundialJobScheduler.isJobRunning("SampleJob");
```
And many more useful functions. See all here: https://github.com/knowm/Sundial/blob/develop/src/main/java/org/knowm/sundial/SundialJobScheduler.java

## Job Data Map
```java
// asynchronously start a job by name with data map
Map params = new HashMap<>();
params.put("MY_KEY", new Integer(660));
SundialJobScheduler.startJob("SampleJob1", params);
```
```java
// annotate CronTrigger with data map (separate key/values with ":" )
@CronTrigger(cron = "0/5 * * * * ?", jobDataMap = { "KEY_1:VALUE_1", "KEY_2:1000" })
public class SampleJob extends Job {
}
```
```xml

SampleJob
org.knowm.sundial.jobs.SampleJob


MyParam
42

```
```java
// access data inside Job
String value1 = getJobContext().get("KEY_1");
logger.info("value1 = " + value1);
```

## Get Organized with Job Actions!

With `JobAction`s, you can encapsule logic that can be shared by different `Job`s.
```java
public class SampleJobAction extends JobAction {

@Override
public void doRun() {

Integer myValue = getJobContext().get("MyValue");

// Do something interesting...
}
}
```
```java
// Call the JobAction from inside a Job
getJobContext().put("MyValue", new Integer(123));
new SampleJobAction().run();
```

## Job Termination

To terminate a Job asynchronously, you can call the `SundialJobScheduler.stopJob(String jobName)` method. The Job termination mechanism works by setting a flag that the Job should be terminated, but it is up to the logic in the Job to decide at what point termination should occur. Therefore, in any long-running job that you anticipate the need to terminate, put the method call `checkTerminated()` at an appropriate location.

For an example see `SampleJob9.java`. In a loop within the Job you should just add a call to `checkTerminated();`.

If you try to shutdown the SundialScheduler and it just hangs, it's probably because you have a Job defined with an infinite loop with no `checkTerminated();` call. You may see a log message like: `Waiting for Job to shutdown: SampleJob9 : SampleJob9-trigger`.

## Concurrent Job Execution

By default jobs are not set to concurrently execute. This means if a job is currently running and a trigger is fired for that job, it will skip running the job. In some cases concurrent job execution is desired and there are a few ways to configure it.

1. You can add `true` in jobs.xml.
1. You can add it to the Sundial annotations like this: `@SimpleTrigger(repeatInterval = 30, timeUnit = TimeUnit.SECONDS, isConcurrencyAllowed = true)` Same idea for cron annotation too.

Now go ahead and [study some more examples](http://knowm.org/open-source/sundial/sundial-example-code), [download the thing](http://knowm.org/open-source/sundial/sundial-change-log/) and [provide feedback](https://github.com/knowm/Sundial/issues).

## Getting the Goods

### Non-Maven

Download Jar: http://knowm.org/open-source/sundial/sundial-change-log/

#### Dependencies

* org.slf4j.slf4j-api-2.0.12

### Maven

The Sundial release artifacts are hosted on Maven Central.

Add the Sundial library as a dependency to your pom.xml file:

```xml

org.knowm
sundial
2.3.0

```

For snapshots, add the following to your pom.xml file:

```xml

sonatype-oss-snapshot

https://oss.sonatype.org/content/repositories/snapshots

org.knowm
sundial
2.3.1-SNAPSHOT

```

## Building

mvn clean package
mvn javadoc:javadoc
mvn com.spotify.fmt:fmt-maven-plugin:format

### Dependency Updates

mvn versions:display-dependency-updates

## Cron Expressions in jobs.xml

See the Cron Trigger tutorial over at [quartz-scheduler.org](http://www.quartz-scheduler.org/documentation/quartz-2.2.2/tutorials/crontrigger).
Here are a few examples:

Expression | Meaning
------------- | -------------
0 0 12 * * ? | Fire at 12pm (noon) every day
0 15 10 * * ? | Fire at 10:15am every day
0 15 10 ? * MON-FRI | Fire at 10:15am every Monday, Tuesday, Wednesday, Thursday and Friday
0 0/10 * * * ? | Fire every 10 mintes starting at 12 am (midnight) every day

## Bugs
Please report any bugs or submit feature requests to [Sundial's Github issue tracker](https://github.com/knowm/Sundial/issues).

## Continuous Integration
[![Java CI with Maven on Push](https://github.com/knowm/Sundial/actions/workflows/maven_on_push.yml/badge.svg)](https://github.com/knowm/Sundial/actions/workflows/maven_on_push.yml)