search

enragedginger / akka-quartz-scheduler

Quartz Extension and utilities for cron-style scheduling in Akka
Other
559 stars 115 forks source link

readme

akka-quartz-scheduler

Build Status

Quartz Extension and utilities for true scheduling in Akka 2.6.x.

Current release is built for Scala 2.13.x and Akka 2.6.x and is available on Maven Central. If you would like support for a different combination of Scala and Akka, simply post your request on the issues page (as well as a reason as to why the currently available versions won't work for you. I'm always curious about these things).

Why Akka and Quartz?

Note that this is named and targeted as akka-quartz-scheduler for a reason: it is not a complete port of Quartz. Rather, we utilize the concepts of Quartz' scheduling system to provide a more robust and reliable scheduling component to Akka than the one already available.

The goal here is to provide Akka with a scheduling system that is closer to what one would expect for Cron type jobs – set up long-running ActorSystems that can have certain events kicked off by Quartz.

There aren't currently any plans on having anything to do with the distributed transaction, persistence, clustering or any other nonsense anytime soon. This is for cron-ey type timing and scheduling.

There is the ability in Quartz to pass JobDataMaps around that accrue mutable state across job ticks; we currently do NOT support that to enforce integrity, but may expose a deeper actor structure later that gives some ability to work around that, if need arises.

Why Not Use $OtherComparableTool Instead?

  1. What's wrong with Akka's existing Scheduler? As Viktor Klang points out, 'Perhaps the name "Scheduler" was unfortunate, "Deferer" is probably more indicative of what it does.'

    The Akka Scheduler is designed to setup events that happen based on durations from the current moment: You can say "fire this job in 15 minutes, every 30 minutes thereafter" but not "fire a job every day at 3pm".

    Furthermore, Akka's default scheduler is executed around a HashedWheelTimer – a potential precision loss for jobs, as it does not provide strong guarantees on the timeliness of execution.

  2. Why not just use the Quartz component in Akka's Camel Extension?

    1. To begin with, Akka's Camel extension was not available in Akka 2.0.x, only in 2.1+
    2. Camel brings with it a whole architecture change (Consumers, Producers, etc) and is not exactly "lightweight" to plug in if all you want is Quartz support.
    3. We wanted to bring the scheduling concept of Quartz into Akka as cleanly as possible with native configuration integration and a lightweight feel.

  3. What about that other akka-quartz component up on GitHub?

    The interface to this aforementioned akka-quartz component is via Actors - one creates an instance of an Actor that has its own Quartz Scheduler underneath it, and sends messages to that Actor to schedule jobs. Because it is an Actor which provides no "Singleton"-like guarantee, it becomes too easy for users to accidentally spin up multiple scheduler instances, each of which is backed by its own threadpool. Instead, with akka-quartz-scheduler we use Akka's Extension system which provides a plugin model – we guarantee only one Quartz Scheduler is ever spun up per ActorSystem. This means we will never create anything but one single Thread Pool which you have control over the size of, for any given ActorSystem.

Finally, a common failure of the above listed alternatives is that configuration of things like a repeating schedule should be separated from code in a configuration file which an operations team (not the developers) can control. Thus, akka-quartz-scheduler only allows specifying the following in code: the name of a job, what actor to send the tick to, and the message to send on a tick. The configuration of how frequently to 'tick' on a schedule is externalised to the Akka configuration file; when a schedule request is made its name is matched up with an entry in the config which specifies the rules the actual scheduling should follow.

Thus, development can outline the skeleton of repeating jobs in their code, specifying only what to do WHEN a 'tick' of the schedule fires. Then, operations has complete control over how often a job runs and what rules it follows to determine the schedule of firing.

This, among other things, prevents accidental mistakes such as changing a schedule in development for testing. A change of that sort is fixable without Operations needing to require a recompilation of source code.

TODO

Usage

See CHANGELOG.md for a list of changes by release.

Usage of the akka-quartz-scheduler component first requires including the necessary dependency in your SBT project:

// For Akka 2.6.x and Akka Typed Actors 2.6.x and Scala 2.12.x, 2.13.x, 3.1.x
libraryDependencies += "com.enragedginger" %% "akka-quartz-scheduler" % "1.9.3-akka-2.6.x"

// For Akka 2.6.x and Scala 2.12.x, 2.13.x
libraryDependencies += "com.enragedginger" %% "akka-quartz-scheduler" % "1.8.5-akka-2.6.x"

// For Akka 2.5.x and Scala 2.11.x, 2.12.x, 2.13.x
libraryDependencies += "com.enragedginger" %% "akka-quartz-scheduler" % "1.8.1-akka-2.5.x"

// For Akka 2.4.x and Scala 2.11.x, 2.12.x
libraryDependencies += "com.enragedginger" %% "akka-quartz-scheduler" % "1.6.0-akka-2.4.x"

Note: As of Akka 2.6, Scala 2.11 is no longer supported. If you wish to use newer versions of akka-quartz-scheduler, but you're stuck on Scala 2.11 for some reason, please open an issue / PR and we'll see what we can do.

//Older versions of the artifact for those that require pre Akka 2.3 or pre Scala 2.11
//If you would like a current version of the artifact to be published for your required version
//of Akka and Scala, simply file on issue on the project page.
resolvers += "Typesafe Repository" at "http://repo.typesafe.com/typesafe/releases/"

// For Akka 2.0.x
libraryDependencies += "com.typesafe.akka" %% "akka-quartz-scheduler" % "1.2.0-akka-2.0.x"
// For Akka 2.1.x
libraryDependencies += "com.typesafe.akka" %% "akka-quartz-scheduler" % "1.2.0-akka-2.1.x"
// For Akka 2.2.x
libraryDependencies += "com.typesafe.akka" %% "akka-quartz-scheduler" % "1.2.0-akka-2.2.x"
// For Akka 2.3.x and Scala 2.10.4
libraryDependencies += "com.typesafe.akka" % "akka-quartz-scheduler_2.10" % "1.4.0-akka-2.3.x"

Note that the version name includes the Akka revision (Previous releases included the Akka release in the artifact name, which broken Maven).

Akka Typed Actor (2.6.x)

If you use newer Akka Actor version then, from within your Akka project you can create and access a Typed Scheduler:

// Akka Typed Actors sample.
import com.typesafe.akka.extension.quartz.QuartzSchedulerTypedExtension

val scheduler = QuartzSchedulerTypedExtension(typedSystem)

Where typedSystem represents an instance of an Akka Typed ActorSystem[-T] – note that QuartzSchedulerTypedExtension is scoped to that ActorSystem[-T] and there will only ever be one instance of it per ActorSystem[-T].

The primary external method on the scheduler instance is schedule, used for scheduling a job:

def scheduleTyped[T](name: String, receiver: ActorRef[T], msg: T): java.util.Date

OR

def scheduleTyped[T](name: String, receiver: ActorRef[T], msg: T, startDate: Option[Date]): java.util.Date

The arguments to schedule are:

Invoking scheduleTyped[A] returns an instance of java.util.Date, representing the first time the newly setup schedule will fire.

Each time the Quartz schedule trigger fires, Quartz will send a copy of msg to your receiver actor.

Note that you can use the same logic for scheduling Quartz with Akka Typed Actor as the older version.

Akka Actor (2.5.x)

If you use old Akka Actor version then, from within your Akka project you can create and access a Scheduler:

// Akka Actors sample.
import com.typesafe.akka.extension.quartz.QuartzSchedulerExtension

val scheduler = QuartzSchedulerExtension(system)

Where system represents an instance of an Akka ActorSystem – note that QuartzSchedulerExtension is scoped to that ActorSystem and there will only ever be one instance of it per ActorSystem.

The primary external method on the scheduler instance is schedule, used for scheduling a job:

def schedule(name: String, receiver: ActorRef, msg: AnyRef, startDate: Option[Date]): java.util.Date

OR

def schedule(name: String, receiver: ActorSelection, msg: AnyRef, startDate: Option[Date]): java.util.Date

The arguments to schedule are:

Invoking schedule returns an instance of java.util.Date, representing the first time the newly setup schedule will fire.

Each time the Quartz schedule trigger fires, Quartz will send a copy of msg to your receiver actor.

Here is an example, using a schedule called Every30Seconds, which sends a Tick message to a CleanupActor (which does hand wavy cleanup things):

case object Tick

val cleaner = system.actorOf(Props[CleanupActor])

QuartzSchedulerExtension(system).schedule("Every30Seconds", cleaner, Tick)

Where the Tick message is handled normally inside the Actor's message loop. If one wanted to ensure that schedule messages were dealt with more immediately than "normal" actor messages, they could utilize Priority Mailboxes.

The details on the configuration of a job is outlined below in the section 'Schedule Configuration'.

Returning scheduled Fire Time

There are situations where the fire time is helpful. For example, when an error occurs, we know which job trigger is being processed and can be recovered.

Here is an example using the case class MessageRequireFireTime wrapping the Tick message. This will send a MessageWithFireTime(Tick, previousFireTime, scheduledFireTime, nextFireTime) message to a WorkerActor:

case object Tick

val worker = system.actorOf(Props[WorkerActor])

QuartzSchedulerExtension(system).schedule("Every30Seconds", worker, MessageRequireFireTime(Tick))

Configuration of Quartz Scheduler

All configuration of akka-quartz-scheduler is done inside of the Akka configuration file in an akka.quartz config block. Like Akka's configuration file, this follows the HOCON Configuration Format. Thus, any entries specified as foo.bar.baz = x can also be expressed as foo { bar { baz = x } }.

At the top level of the configuration, optional values may be set which override the defaults for:

There are two 'primary' sub-blocks of the akka.quartz configuration, which are schedules and calendars.

Schedule Configuration

Schedules are our abstraction over Quartz' Job & Trigger concepts. They allow you to define a named schedule, which will fire a schedule event (sending a message to an actor, as specified in code) each time the Quartz trigger fires.

Currently, you can only specify "Cron" schedules, which follow Quartz' CronExpression Language, which is designed to match the standard Unix cron syntax with a few nice additions.

The schedule name in the configuration will be used to match it up with a requested job when schedule is invoked; case does not matter as the "Is there a matching job?" configuration lookup is case insensitive.

The configuration block for schedules is in akka.quartz.schedules, with sub-entries being specified inside of a named block, such that the configuration for a schedule named Every30Seconds would have its configuration values specified inside the configuration block akka.quartz.schedules.Every30Seconds.

The entries that can be placed inside of a schedule configuration are:

An example schedule called Every30Seconds which, aptly, fires off every 30 seconds:

akka {
  quartz {
    schedules {
      Every30Seconds {
        description = "A cron job that fires off every 30 seconds"
        expression = "*/30 * * ? * *"
        calendar = "OnlyBusinessHours"
      }
    }
  }
}

This Schedule specifies a Cron Expression which executes every 30 seconds of every day, but is modified by the calendar "OnlyBusinessHours", which excludes triggers from firing outside of between 8am and 6pm (and is detailed below).

Calendar Configuration

Calendars in the akka-quartz-scheduler mirror the concept of Quartz' Calendars – most specifically, they allow you to specify exclusions that override a schedule.

Calendars are configured globally, in the akka.quartz.calendars configuration block. The definition of a calendar and what it excludes is made within this block. By default, no Calendars are applied to a Schedule. Instead, you must reference a named Calendar inside the calendars array of a Schedule's configuration, as outlined above.

The configuration block for calendars is in akka.quartz.calendars, with sub-entries being specified inside of a named block, such that the configuration for a calendar named OnlyBusinessHours would have it's configuration values specified inside the configuration block akka.quartz.calendars.OnlyBusinessHours.

There are several types of Calendar, each with its own specific configurations. The configuration values which are common to all types of Calendar are:

Each specific Calendar type and its particular configuration entries are...

'Annual' Calendar

An annual calendar excludes specific days of a given year, e.g. bank holidays which fall on the same date every year (Christmas and Gregorian New Year's for example) This calendar does not take year into account, and will apply to all years.

It has only one configuration entry:

An example:

WinterClosings {
  type = Annual
  description = "Major holiday dates that occur in the winter time every year, non-moveable (The year doesn't matter)"
  excludeDates = ["12-25", "01-01"]
}
'Holiday' Calendar

A holiday calendar excludes specific dates, with a fully month, day, year taken into account. It is mostly useful for moving Bank Holidays (e.g. President's Day) and Moveable Feasts (e.g. Easter, which is based on a Lunar calendar).

It has only one configuration entry:

An example:

Easter {
  type = Holiday
  description = "The easter holiday (a moveable feast) for the next five years"
  excludeDates = ["2013-03-31", "2014-04-20", "2015-04-05", "2016-03-27", "2017-04-16"]
}
'Daily' Calendar

A daily calendar excludes a specified time range each day. It may not cross daily boundaries, and Quartz will enforce this. i.e. You cannot specify "11PM to 1AM" – to do that you'll need to specify two separate daily calendars.

Exclusions in a Daily calendar are specified in a exclude with a startTime and endTime entry. Each of these fields follows a time format of HH:MM[:SS[:mmm]] where:

An example, which doesn't allow jobs to run between 3AM and 5AM during the PST Timezone:

HourOfTheWolf {
  type = Daily
  description = "A period every day in which cron jobs are quiesced, during night hours"
  exclude {
    startTime = "03:00"
    endTime   = "05:00:00"
  }
  timezone = PST
}
'Monthly' Calendar

A monthly calendar excludes a set of days of the month, i.e. "Don't run a job on the 1st or 15th days of the month"

It has only one configuration entry:

An example:

FirstAndLastOfMonth {
  type = Monthly
  description = "A thinly veiled example to test monthly exclusions"
  excludeDays = [1, 31]
}
'Weekly' Calendar

A weekly calendar excludes a set of days of the week. By default, Saturday and Sunday are always excluded

The configuration entries:

An example, which excludes jobs from running on any Monday:

MondaysSuck {
  type = Weekly
  description = "Everyone, including this calendar, hates mondays as an integer"
  excludeDays = [2]
  excludeWeekends = false
}

Note that by default, excludeWeekends would be true and thus excludeDays would implicitly be [1, 2, 7]

'Cron' Calendar

A cron calendar excludes the set of times expressed by a given Quartz CronExpression.

It has only one configuration entry:

An example Calendar, which specifies an exclusion set of 00:00 - 07:59 and 18:00 - 23:59 (thereby only allowing jobs to run from 08:00 - 17:59):

OnlyBusinessHours {
  type = Cron
  excludeExpression = "* * 0-7,18-23 ? * *"
}

Dynamic create, update, delete JobSchedule operations

These JobSchedule operations let you programatically manage job and job scheduling all at once. For working examples please check test section: "The Quartz Scheduling Extension with Dynamic create, update, delete JobSchedule operations" in com.typesafe.akka.extension.quartz.QuartzSchedulerFunctionalSpec

Create JobSchedule

createJobSchedule let you create a new job and schedule it all at once: 

val scheduleJobName : String = "myJobName_1"
val messageReceiverActor: ActorRef = myActorRef
val messageSentToReceiver : AnyRef = myCaseClassMessage 
val scheduleCronExpression: String = "*/10 * * ? * *" // Will fire every ten seconds

try { 
  scheduler.createJobSchedule(
    name = scheduleJobName, 
    receiver = messageReceiverActor, 
    msg = messageSentToReceiver, 
    cronExpression = scheduleCronExpression)
} catch {
  case iae: IllegalArgumentException => iae // Do something useful with it.
}

In addition you can specify the following optional description, calendar and timezone parameters: 

val scheduleJobDescriptionOpt : Option[String] = Some("Scheduled job for test purposes.")
val aCalendarName: Option[String] = Some("HourOfTheWolf")
val aTimeZone: java.util.TimeZone = java.util.TimeZone.getTimeZone("UTC")

try { 
  scheduler.createJobSchedule(
    name = scheduleJobName, 
    receiver = messageReceiverActor, 
    msg = messageSentToReceiver, 
    cronExpression = scheduleCronExpression, 
    description = Some(job.description), 
    calendar = aCalendarName, 
    timezone = aTimeZone
  )
} catch {
  case iae: IllegalArgumentException => iae // Do something useful with it.
}

Update JobSchedule

updateJobSchedule has exactely the same signature as create JobSchedule but tries to perform an update of an existing scheduleJobName 

try { 
  scheduler.updateJobSchedule(
    name = scheduleJobName, 
    receiver = messageReceiverActor, 
    msg = messageSentToReceiver, 
    cronExpression = scheduleCronExpression, 
    description = Some(job.description), 
    calendar = aCalendarName, 
    timezone = aTimeZone
  )
} catch {
  case iae: IllegalArgumentException => iae // Do something useful with it.
}

Delete JobSchedule

try {
  if (scheduler.deleteJobSchedule(name = scheduleJobName)) { 
    // Do something if deletion succeeded
  } else {
    // Do something else if deletion failed
  }
} catch {
  case e: Exception =>
    // Take action in case an exception is thrown 
}

Mass operations suspendAll, resumeAll, deleteAll

These mass operations let you manage many JobSchedules at once. For working examples please check test section: "The Quartz Scheduling Extension with Dynamic mass methods" in com.typesafe.akka.extension.quartz.QuartzSchedulerFunctionalSpec

Suspend All Schedules

Suspends (pauses) all jobs in the scheduler.

try {
  scheduler.suspendAll()
} catch {
  case e: SchedulerException =>
    // Take action in case an exception is thrown 
}

Resume All Schedules

Unpauses all paused jobs in the scheduler.

try {
  scheduler.resumeAll()
} catch {
  case e: SchedulerException =>
    // Take action in case an exception is thrown 
}

Delete All Schedules

Deletes all jobs in the scheduler without shutting down the scheduler.

try {
  scheduler.deleteAll()
} catch {
  case e: SchedulerException =>
    // Take action in case an exception is thrown 
}