Merge branch '2.0.x'

Conflicts:
	src/main/java/com/coreoz/wisp/JobStatus.java
	src/main/java/com/coreoz/wisp/JobThread.java

Author: amanteaux

README.md

@@ -6,10 +6,10 @@ Wisp Scheduler
 [![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.coreoz/wisp/badge.svg)](https://maven-badges.herokuapp.com/maven-central/com.coreoz/wisp)
 
 Wisp is a simple Java Scheduler with a minimal footprint.
-Wisp weighs only 30Kb and has zero dependency.
-It will only create threads that will be used: if one thread is enough to run all the jobs,
-then only one thread will be created.
-A second thread will only be created when 2 jobs have to run at the exact same time.
+Wisp weighs only 30Kb and has zero dependency except SLF4J.
+It will only create threads that will be used: if two threads are enough to run all the jobs,
+then only two threads will be created.
+A third thread will only be created when 2 jobs have to run at the same time.
 
 The scheduler precision will depend on the system load.
 Though a job will never be executed early, it will generally run after 1ms of the scheduled time.
@@ -24,7 +24,7 @@ Include Wisp in your project:
 <dependency>
     <groupId>com.coreoz</groupId>
     <artifactId>wisp</artifactId>
-    <version>1.0.0</version>
+    <version>2.0.0</version>
 </dependency>
 ```
 
@@ -43,6 +43,14 @@ A project should generally contain only one instance of a `Scheduler`.
 So either a dependency injection framework handles this instance,
 or either a static instance of `Scheduler` should be created.
 
+In production, it is generally a good practice to configure the
+[monitor for long running jobs detection](#long-running-jobs-detection).
+
+Upgrade from version 1.x.x to version 2.x.x
+-------------------------------------------
+- If a cron schedule is used, then cron-utils must be upgraded to version 8.0.0
+- The [monitor for long running jobs detection](#long-running-jobs-detection) might be configured
+
 Schedules
 ---------
 
@@ -75,7 +83,7 @@ So to use cron expression, cron-utils should be added in the project:
 <dependency>
     <groupId>com.cronutils</groupId>
     <artifactId>cron-utils</artifactId>
-    <version>6.0.4</version>
+    <version>8.0.0</version>
 </dependency>
 ```
 Then to create a job which is executed every hour at the 30th minute,
@@ -94,6 +102,20 @@ the associated job will never be executed again.
 At the first execution, if a past time is referenced a warning will be logged
 but no exception will be raised.
 
+### Long running jobs detection
+To detect jobs that are running for too long, an optional job monitor is provided.
+It can be setup with:
+```java
+scheduler.schedule(
+    new LongRunningJobMonitor(scheduler),
+    Schedules.fixedDelaySchedule(Duration.ofMinutes(1))
+);
+```
+This way, every minute, the monitor will check for jobs that are running for more than 5 minutes.
+A warning message with the job stack trace will be logged for any job running for more than 5 minutes.
+
+The detection threshold can also be configured this way: `new LongRunningJobMonitor(scheduler, Duration.ofMinutes(15))`
+
 Plume Framework integration
 ---------------------------
 

pom.xml

@@ -1,10 +1,12 @@
-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
 
 	<modelVersion>4.0.0</modelVersion>
 
 	<groupId>com.coreoz</groupId>
 	<artifactId>wisp</artifactId>
-	<version>1.0.1-SNAPSHOT</version>
+	<version>2.0.0-SNAPSHOT</version>
 	<packaging>jar</packaging>
 
 	<name>Wisp Scheduler</name>
@@ -157,17 +159,23 @@
 	</build>
 
 	<dependencies>
+		<dependency>
+			<groupId>org.slf4j</groupId>
+			<artifactId>slf4j-api</artifactId>
+			<version>1.7.25</version>
+		</dependency>
+
 		<dependency>
 			<groupId>org.projectlombok</groupId>
 			<artifactId>lombok</artifactId>
-			<version>1.16.18</version>
+			<version>1.18.6</version>
 			<scope>provided</scope>
 		</dependency>
 
 		<dependency>
 			<groupId>com.cronutils</groupId>
 			<artifactId>cron-utils</artifactId>
-			<version>6.0.4</version>
+			<version>8.0.0</version>
 			<optional>true</optional>
 		</dependency>
 

src/main/java/com/coreoz/wisp/Job.java

@@ -13,13 +13,16 @@
  */
 public class Job {
 
-	private volatile JobStatus status;
+	private JobStatus status;
 	private volatile long nextExecutionTimeInMillis;
 	private volatile int executionsCount;
 	private Long lastExecutionTimeInMillis;
+	private Long timeInMillisSinceJobRunning;
+	private Thread threadRunningJob;
 	private final String name;
-	private final Schedule schedule;
+	private Schedule schedule;
 	private final Runnable runnable;
+	private Runnable runningJob;
 
 	// public API
 
@@ -39,6 +42,19 @@ public Long lastExecutionTimeInMillis() {
 		return lastExecutionTimeInMillis;
 	}
 
+	/**
+	 * The time of the start of the job execution.
+	 *
+	 * Not null only when {@code #status() == JobStatus.RUNNING}.
+	 */
+	public Long timeInMillisSinceJobRunning() {
+		return timeInMillisSinceJobRunning;
+	}
+
+	public Thread threadRunningJob() {
+		return threadRunningJob;
+	}
+
 	public String name() {
 		return name;
 	}
@@ -64,24 +80,40 @@ public Runnable runnable() {
 		this.runnable = runnable;
 	}
 
-	Job status(JobStatus status) {
+	void status(JobStatus status) {
 		this.status = status;
-		return this;
 	}
 
-	Job nextExecutionTimeInMillis(long nextExecutionTimeInMillis) {
+	void nextExecutionTimeInMillis(long nextExecutionTimeInMillis) {
 		this.nextExecutionTimeInMillis = nextExecutionTimeInMillis;
-		return this;
 	}
 
-	Job executionsCount(int executionsCount) {
+	void executionsCount(int executionsCount) {
 		this.executionsCount = executionsCount;
-		return this;
 	}
 
-	Job lastExecutionTimeInMillis(Long lastExecutionTimeInMillis) {
+	void lastExecutionTimeInMillis(Long lastExecutionTimeInMillis) {
 		this.lastExecutionTimeInMillis = lastExecutionTimeInMillis;
-		return this;
+	}
+
+	void timeInMillisSinceJobRunning(Long timeInMillisSinceJobRunning) {
+		this.timeInMillisSinceJobRunning = timeInMillisSinceJobRunning;
+	}
+
+	void threadRunningJob(Thread threadRunningJob) {
+		this.threadRunningJob = threadRunningJob;
+	}
+
+	void schedule(Schedule schedule) {
+		this.schedule = schedule;
+	}
+
+	void runningJob(Runnable runningJob) {
+		this.runningJob = runningJob;
+	}
+
+	Runnable runningJob() {
+		return runningJob;
 	}
 
 	// toString

src/main/java/com/coreoz/wisp/JobStatus.java

@@ -6,19 +6,23 @@
 public enum JobStatus {
 
 	/**
-	 * will not be run ever again
+	 * The job will not be run ever again
 	 */
 	DONE,
 	/**
-	 * will be executed again, but not right now
+	 * The job will be executed at his scheduled time
 	 */
 	SCHEDULED,
 	/**
-	 * a scheduled job that is attached to a thread from the pool and ready to be executed when its time comes
+	 * This is an intermediate status before {@link #RUNNING},
+	 * it means that the job is placed on the thread pool executor
+	 * and is waiting to be executed as soon as a thread is available.
+	 * This status should not last more than a few µs/ms except if the
+	 * thread pool is full and running tasks are not terminating.
 	 */
 	READY,
 	/**
-	 * a job currently running
+	 * The job is currently running
 	 */
 	RUNNING,