knowm / 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 6 and up
• [x] Depends only on slf4j

Create a Job Class

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

  @Override
  public void doRun() throws JobInterruptException {
    // Do something interesting...
  }
}

...with CronTrigger or SimpleTrigger Annotation

@CronTrigger(cron = "0/5 * * * * ?")

@SimpleTrigger(repeatInterval = 30, timeUnit = TimeUnit.SECONDS)

Start Sundial Job Scheduler

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 version='1.0' encoding='utf-8'?>
<job-scheduling-data>

	<schedule>

		<!-- job with cron trigger -->
		<job>
			<name>SampleJob3</name>
			<job-class>com.foo.bar.jobs.SampleJob3</job-class>
			<concurrency-allowed>true</concurrency-allowed>
		</job>
		<trigger>
			<cron>
				<name>SampleJob3-Trigger</name>
				<job-name>SampleJob3</job-name>
				<cron-expression>*/15 * * * * ?</cron-expression>
			</cron>
		</trigger>

		<!-- job with simple trigger -->
		<job>
			<name>SampleJob2</name>
			<job-class>com.foo.bar.jobs.SampleJob2</job-class>
			<job-data-map>
				<entry>
					<key>MyParam</key>
					<value>42</value>
				</entry>
			</job-data-map>
		</job>
		<trigger>
			<simple>
				<name>SampleJob2-Trigger</name>
				<job-name>SampleJob2</job-name>
				<repeat-count>5</repeat-count>
				<repeat-interval>5000</repeat-interval>
			</simple>
		</trigger>

	</schedule>

</job-scheduling-data>

Or, Define Jobs and Triggers Manually

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

// 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

// asynchronously start a job by name with data map
Map<String, Object> params = new HashMap<>();
params.put("MY_KEY", new Integer(660));
SundialJobScheduler.startJob("SampleJob1", params);

// 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 {
}

<!-- configure data map in jobs.xml -->
<job>
  <name>SampleJob</name>
  <job-class>org.knowm.sundial.jobs.SampleJob</job-class>
  <job-data-map>
    <entry>
      <key>MyParam</key>
      <value>42</value>
    </entry>
  </job-data-map>
</job>

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

Get Organized with Job Actions!

With JobActions, you can encapsule logic that can be shared by different Jobs.

public class SampleJobAction extends JobAction {

  @Override
  public void doRun() {

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

    // Do something interesting...
  }
}

// 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 <concurrency-allowed>true</concurrency-allowed> in jobs.xml.
2. 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, download the thing and provide feedback.

Getting the Goods

Non-Maven

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

Dependencies

• org.slf4j.slf4j-api-1.7.26

Maven

The Sundial release artifacts are hosted on Maven Central.

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

<dependency>
    <groupId>org.knowm</groupId>
    <artifactId>sundial</artifactId>
    <version>2.2.1</version>
</dependency>

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

<repository>
  <id>sonatype-oss-snapshot</id>
  <snapshots/>
  <url>https://oss.sonatype.org/content/repositories/snapshots</url>
</repository>

<dependency>
    <groupId>org.knowm</groupId>
    <artifactId>sundial</artifactId>
    <version>2.2.2-SNAPSHOT</version>
</dependency>

Building

mvn clean package  
mvn javadoc:javadoc  

Dependency Updates

mvn versions:display-dependency-updates

Cron Expressions in jobs.xml

See the Cron Trigger tutorial over at quartz-scheduler.org. Here are a few examples:

Bugs

Please report any bugs or submit feature requests to Sundial's Github issue tracker.

Continuous Integration

Build History