Home

Awesome

Cron Scheduler for Eclipse Vert.x

This module allows you to schedule an event using a Cron specification. It can either send or publish a message to the address of your choice. If the consumer of that message returns a response, you can specify where to send that response when the consumer completes. You can also cancel the scheduled event at a future time.

It also provides an RxJava Observable for use with Vert.x Rx.

Tested with Eclipse Vert.x 3.8.5

Event Bus Cron Scheduler

Maven Dependency

<dependency>
    <groupId>com.diabolicallabs</groupId>
    <artifactId>vertx-cron</artifactId>
    <version>3.5.3</version>
</dependency>

Configuration

{
  "address_base": <string>
}

The Cron Scheduler will use the string specified as the <address_base> for registering the consumer your sender will interact with.

It will create a public consumer for:

<address_base>.schedule -- used to schedule an event

Configuration Example

{
  "address_base": "cron.scheduler"
}

This will cause the Cron Scheduler to create a public consumer named: "cron.scheduler.schedule"

Schedule an Event

To schedule an event, you need to send a message to this address: <address_base>.schedule where <address_base> is the name specified in the configuration. The consumer of the message will return an ID as a String that corresponds to the scheduled event. This can be used to cancel it later.

Scheduled events are not persistent. If Vertx restarts, you will have to schedule your events again.

The message you send will conform to the following JSON schema:

{
    "title": "A Cron Scheduler schedule message",
    "type":"object",
    "properties": {
        "cron_expression": {"type": "string"},
        "timezone_name": {"type": "string"},
        "address": {"type": "string"},
        "message": {"type": "object"},
        "action": {"enum": ["send", "publish"]},
        "result_address": {"type": "string"}
    },
    "required": ["cron_expression", "address"]
}

cron_expression is a standard cron expression as is frequently used on Linux systems. As an example, "*/5 * * * * ?" would result in an event being fired every 5 seconds on the 5's.

Most Cron implementation do not allow the scheduling of events down to the second, they will only allow minutely specifications. We are borrowing the org.quartz.CronExpression class from the Quartz Scheduler project that does allow the specification of seconds. Check this documentation [CronExpression] (http://quartz-scheduler.org/api/2.2.0/org/quartz/CronExpression.html) for allowed values.

This [CronMaker Calculator] (http://www.cronmaker.com/) may also help you form the cron_expression.

timezone_name if specified, the cron_expression will be interpreted with reference to that timezone. If none is specified, the default timezone of the machine your vertical is running on will be used. It is important to set the timezone if you anticipate that a vertical using this module may run in multiple timezones. It is also useful if you want to schedule an event relative to a particular timezone and don't want to calculate any time offset yourself when specifying the cron_expression.

A list of currently valid timezones is a the end of the document.

address is the address you want to send or publish a message to on a scheduled basis.

message is the message that you want to send to the aforementioned address. It is not required. If it is not specified, the Cron Scheduler will send or publish a null message to the address at the time mentioned by the cron_expression.

action is the action to take at the specified time. It can be "send" or "publish". If you specify "send" the Cron Scheduler will send the message to the address and wait for any result. If you specify a result_address, the result of the send will be forwarded to that address. If you specify "publish" the message will be published to the address specified and the Cron Scheduler will not wait to collect any result. The action is not required. If omitted, the default is "send".

result_address is the address to which you want any result sent.

Here is an example schedule message:

{
    "cron_expression": "0 0 16 1/1 * ? *",
    "timezone_name": "US/Eastern",
    "address": "stock.quotes.list",
    "message": {
        "ticker": "RHT"
    },
    "repeat": true,
    "action": "send",
    "result_address": "stock.quotes.persist"
}

This message would cause the Cron Scheduler to send the message {"ticker": "RHT"} to "stock.quotes.list" every day (including weekend days) at 16:00 in the US Eastern timezone. The Cron Scheduler would then wait for a response from "stock.quotes.list" and forward the result to "stock.quotes.persist"

Cancel a Scheduled Event

To cancel a scheduled event, you need to publish a message containing the ID of the scheduled event to this address: <address_base>.cancel where <address_base> is the name specified in the configuration. The ID was returned when you called <address_base>.schedule previously.

CronObservable

If you are using Vert.x Rx for reactive programming, you can make use of the CronObservable.

It requires a Vert.x Scheduler, the cron specification in the aforementioned format, and an optional timezone.

Each time the cron schedule fires, the CronObservable will emit a time stamp.

Scheduler scheduler = RxHelper.scheduler(vertx);
CronObservable.cronspec(scheduler, "0 0 16 1/1 * ? *", "US/Eastern")
  .take(5) //If you only want it to hit 5 times, add this, remove for continuous emission
  .subscribe(
    timed -> {
      //Perform the scheduled activity here
    },
    fault -> {
      //If there is some kind of fault, handle here
    }
  );

Possible Issues

Kindly ensure that you are starting the cron job only once. If there are multiple instances of the verticle from which you are setting up the cron job, it will also instantiate the job that many times. This can happen if you deploy the verticle to multiple members of a cluster or you deploy your verticle with DeploymentOptions.setInstances(int instances).

You can avoid this by ensuring that the vertical calling cron is deployed only once across the cluster. You can also use a system wide lock when setting up the job, then you don't have to worry about the number of deployed instances.

Valid Timezones