https://github.com/diabolicallabs/vertx-cron

This vertx module add the ability to schedule events using cron expressions.
https://github.com/diabolicallabs/vertx-cron

Last synced: 3 months ago
JSON representation

This vertx module add the ability to schedule events using cron expressions.

• Host: GitHub
• URL: https://github.com/diabolicallabs/vertx-cron
• Owner: diabolicallabs
• License: other
• Created: 2014-08-27T00:48:26.000Z (about 10 years ago)
• Default Branch: master
• Last Pushed: 2021-05-12T15:31:48.000Z (over 3 years ago)
• Last Synced: 2024-06-19T03:07:51.292Z (5 months ago)
• Language: Java
• Homepage:
• Size: 252 KB
• Stars: 63
• Watchers: 5
• Forks: 21
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE.txt

Awesome Lists containing this project

• vertx-awesome - Vert.x Cron - Schedule events with cron specifications. Has event bus and Observable versions. (Utilities)

README

        
# 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

```

    com.diabolicallabs

    vertx-cron

    3.5.3

```

## Configuration

    {

      "address_base": 

    }

    

The Cron Scheduler will use the string specified as the `` for registering the consumer your

sender will interact with.

It will create a public consumer for:

    

    .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: ``.schedule where ``

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: ``.cancel where ``

is the name specified in the configuration. The ID was returned when you called ``.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

- ACT

- AET

- AGT

- ART

- AST

- Africa/Abidjan

- Africa/Accra

- Africa/Addis_Ababa

- Africa/Algiers

- Africa/Asmara

- Africa/Asmera

- Africa/Bamako

- Africa/Bangui

- Africa/Banjul

- Africa/Bissau

- Africa/Blantyre

- Africa/Brazzaville

- Africa/Bujumbura

- Africa/Cairo

- Africa/Casablanca

- Africa/Ceuta

- Africa/Conakry

- Africa/Dakar

- Africa/Dar_es_Salaam

- Africa/Djibouti

- Africa/Douala

- Africa/El_Aaiun

- Africa/Freetown

- Africa/Gaborone

- Africa/Harare

- Africa/Johannesburg

- Africa/Juba

- Africa/Kampala

- Africa/Khartoum

- Africa/Kigali

- Africa/Kinshasa

- Africa/Lagos

- Africa/Libreville

- Africa/Lome

- Africa/Luanda

- Africa/Lubumbashi

- Africa/Lusaka

- Africa/Malabo

- Africa/Maputo

- Africa/Maseru

- Africa/Mbabane

- Africa/Mogadishu

- Africa/Monrovia

- Africa/Nairobi

- Africa/Ndjamena

- Africa/Niamey

- Africa/Nouakchott

- Africa/Ouagadougou

- Africa/Porto-Novo

- Africa/Sao_Tome

- Africa/Timbuktu

- Africa/Tripoli

- Africa/Tunis

- Africa/Windhoek

- America/Adak

- America/Anchorage

- America/Anguilla

- America/Antigua

- America/Araguaina

- America/Argentina/Buenos_Aires

- America/Argentina/Catamarca

- America/Argentina/ComodRivadavia

- America/Argentina/Cordoba

- America/Argentina/Jujuy

- America/Argentina/La_Rioja

- America/Argentina/Mendoza

- America/Argentina/Rio_Gallegos

- America/Argentina/Salta

- America/Argentina/San_Juan

- America/Argentina/San_Luis

- America/Argentina/Tucuman

- America/Argentina/Ushuaia

- America/Aruba

- America/Asuncion

- America/Atikokan

- America/Atka

- America/Bahia

- America/Bahia_Banderas

- America/Barbados

- America/Belem

- America/Belize

- America/Blanc-Sablon

- America/Boa_Vista

- America/Bogota

- America/Boise

- America/Buenos_Aires

- America/Cambridge_Bay

- America/Campo_Grande

- America/Cancun

- America/Caracas

- America/Catamarca

- America/Cayenne

- America/Cayman

- America/Chicago

- America/Chihuahua

- America/Coral_Harbour

- America/Cordoba

- America/Costa_Rica

- America/Creston

- America/Cuiaba

- America/Curacao

- America/Danmarkshavn

- America/Dawson

- America/Dawson_Creek

- America/Denver

- America/Detroit

- America/Dominica

- America/Edmonton

- America/Eirunepe

- America/El_Salvador

- America/Ensenada

- America/Fort_Wayne

- America/Fortaleza

- America/Glace_Bay

- America/Godthab

- America/Goose_Bay

- America/Grand_Turk

- America/Grenada

- America/Guadeloupe

- America/Guatemala

- America/Guayaquil

- America/Guyana

- America/Halifax

- America/Havana

- America/Hermosillo

- America/Indiana/Indianapolis

- America/Indiana/Knox

- America/Indiana/Marengo

- America/Indiana/Petersburg

- America/Indiana/Tell_City

- America/Indiana/Vevay

- America/Indiana/Vincennes

- America/Indiana/Winamac

- America/Indianapolis

- America/Inuvik

- America/Iqaluit

- America/Jamaica

- America/Jujuy

- America/Juneau

- America/Kentucky/Louisville

- America/Kentucky/Monticello

- America/Knox_IN

- America/Kralendijk

- America/La_Paz

- America/Lima

- America/Los_Angeles

- America/Louisville

- America/Lower_Princes

- America/Maceio

- America/Managua

- America/Manaus

- America/Marigot

- America/Martinique

- America/Matamoros

- America/Mazatlan

- America/Mendoza

- America/Menominee

- America/Merida

- America/Metlakatla

- America/Mexico_City

- America/Miquelon

- America/Moncton

- America/Monterrey

- America/Montevideo

- America/Montreal

- America/Montserrat

- America/Nassau

- America/New_York

- America/Nipigon

- America/Nome

- America/Noronha

- America/North_Dakota/Beulah

- America/North_Dakota/Center

- America/North_Dakota/New_Salem

- America/Ojinaga

- America/Panama

- America/Pangnirtung

- America/Paramaribo

- America/Phoenix

- America/Port-au-Prince

- America/Port_of_Spain

- America/Porto_Acre

- America/Porto_Velho

- America/Puerto_Rico

- America/Rainy_River

- America/Rankin_Inlet

- America/Recife

- America/Regina

- America/Resolute

- America/Rio_Branco

- America/Rosario

- America/Santa_Isabel

- America/Santarem

- America/Santiago

- America/Santo_Domingo

- America/Sao_Paulo

- America/Scoresbysund

- America/Shiprock

- America/Sitka

- America/St_Barthelemy

- America/St_Johns

- America/St_Kitts

- America/St_Lucia

- America/St_Thomas

- America/St_Vincent

- America/Swift_Current

- America/Tegucigalpa

- America/Thule

- America/Thunder_Bay

- America/Tijuana

- America/Toronto

- America/Tortola

- America/Vancouver

- America/Virgin

- America/Whitehorse

- America/Winnipeg

- America/Yakutat

- America/Yellowknife

- Antarctica/Casey

- Antarctica/Davis

- Antarctica/DumontDUrville

- Antarctica/Macquarie

- Antarctica/Mawson

- Antarctica/McMurdo

- Antarctica/Palmer

- Antarctica/Rothera

- Antarctica/South_Pole

- Antarctica/Syowa

- Antarctica/Troll

- Antarctica/Vostok

- Arctic/Longyearbyen

- Asia/Aden

- Asia/Almaty

- Asia/Amman

- Asia/Anadyr

- Asia/Aqtau

- Asia/Aqtobe

- Asia/Ashgabat

- Asia/Ashkhabad

- Asia/Baghdad

- Asia/Bahrain

- Asia/Baku

- Asia/Bangkok

- Asia/Beirut

- Asia/Bishkek

- Asia/Brunei

- Asia/Calcutta

- Asia/Choibalsan

- Asia/Chongqing

- Asia/Chungking

- Asia/Colombo

- Asia/Dacca

- Asia/Damascus

- Asia/Dhaka

- Asia/Dili

- Asia/Dubai

- Asia/Dushanbe

- Asia/Gaza

- Asia/Harbin

- Asia/Hebron

- Asia/Ho_Chi_Minh

- Asia/Hong_Kong

- Asia/Hovd

- Asia/Irkutsk

- Asia/Istanbul

- Asia/Jakarta

- Asia/Jayapura

- Asia/Jerusalem

- Asia/Kabul

- Asia/Kamchatka

- Asia/Karachi

- Asia/Kashgar

- Asia/Kathmandu

- Asia/Katmandu

- Asia/Khandyga

- Asia/Kolkata

- Asia/Krasnoyarsk

- Asia/Kuala_Lumpur

- Asia/Kuching

- Asia/Kuwait

- Asia/Macao

- Asia/Macau

- Asia/Magadan

- Asia/Makassar

- Asia/Manila

- Asia/Muscat

- Asia/Nicosia

- Asia/Novokuznetsk

- Asia/Novosibirsk

- Asia/Omsk

- Asia/Oral

- Asia/Phnom_Penh

- Asia/Pontianak

- Asia/Pyongyang

- Asia/Qatar

- Asia/Qyzylorda

- Asia/Rangoon

- Asia/Riyadh

- Asia/Saigon

- Asia/Sakhalin

- Asia/Samarkand

- Asia/Seoul

- Asia/Shanghai

- Asia/Singapore

- Asia/Taipei

- Asia/Tashkent

- Asia/Tbilisi

- Asia/Tehran

- Asia/Tel_Aviv

- Asia/Thimbu

- Asia/Thimphu

- Asia/Tokyo

- Asia/Ujung_Pandang

- Asia/Ulaanbaatar

- Asia/Ulan_Bator

- Asia/Urumqi

- Asia/Ust-Nera

- Asia/Vientiane

- Asia/Vladivostok

- Asia/Yakutsk

- Asia/Yekaterinburg

- Asia/Yerevan

- Atlantic/Azores

- Atlantic/Bermuda

- Atlantic/Canary

- Atlantic/Cape_Verde

- Atlantic/Faeroe

- Atlantic/Faroe

- Atlantic/Jan_Mayen

- Atlantic/Madeira

- Atlantic/Reykjavik

- Atlantic/South_Georgia

- Atlantic/St_Helena

- Atlantic/Stanley

- Australia/ACT

- Australia/Adelaide

- Australia/Brisbane

- Australia/Broken_Hill

- Australia/Canberra

- Australia/Currie

- Australia/Darwin

- Australia/Eucla

- Australia/Hobart

- Australia/LHI

- Australia/Lindeman

- Australia/Lord_Howe

- Australia/Melbourne

- Australia/NSW

- Australia/North

- Australia/Perth

- Australia/Queensland

- Australia/South

- Australia/Sydney

- Australia/Tasmania

- Australia/Victoria

- Australia/West

- Australia/Yancowinna

- BET

- BST

- Brazil/Acre

- Brazil/DeNoronha

- Brazil/East

- Brazil/West

- CAT

- CET

- CNT

- CST

- CST6CDT

- CTT

- Canada/Atlantic

- Canada/Central

- Canada/East-Saskatchewan

- Canada/Eastern

- Canada/Mountain

- Canada/Newfoundland

- Canada/Pacific

- Canada/Saskatchewan

- Canada/Yukon

- Chile/Continental

- Chile/EasterIsland

- Cuba

- EAT

- ECT

- EET

- EST

- EST5EDT

- Egypt

- Eire

- Etc/GMT

- Etc/GMT+0

- Etc/GMT+1

- Etc/GMT+10

- Etc/GMT+11

- Etc/GMT+12

- Etc/GMT+2

- Etc/GMT+3

- Etc/GMT+4

- Etc/GMT+5

- Etc/GMT+6

- Etc/GMT+7

- Etc/GMT+8

- Etc/GMT+9

- Etc/GMT-0

- Etc/GMT-1

- Etc/GMT-10

- Etc/GMT-11

- Etc/GMT-12

- Etc/GMT-13

- Etc/GMT-14

- Etc/GMT-2

- Etc/GMT-3

- Etc/GMT-4

- Etc/GMT-5

- Etc/GMT-6

- Etc/GMT-7

- Etc/GMT-8

- Etc/GMT-9

- Etc/GMT0

- Etc/Greenwich

- Etc/UCT

- Etc/UTC

- Etc/Universal

- Etc/Zulu

- Europe/Amsterdam

- Europe/Andorra

- Europe/Athens

- Europe/Belfast

- Europe/Belgrade

- Europe/Berlin

- Europe/Bratislava

- Europe/Brussels

- Europe/Bucharest

- Europe/Budapest

- Europe/Busingen

- Europe/Chisinau

- Europe/Copenhagen

- Europe/Dublin

- Europe/Gibraltar

- Europe/Guernsey

- Europe/Helsinki

- Europe/Isle_of_Man

- Europe/Istanbul

- Europe/Jersey

- Europe/Kaliningrad

- Europe/Kiev

- Europe/Lisbon

- Europe/Ljubljana

- Europe/London

- Europe/Luxembourg

- Europe/Madrid

- Europe/Malta

- Europe/Mariehamn

- Europe/Minsk

- Europe/Monaco

- Europe/Moscow

- Europe/Nicosia

- Europe/Oslo

- Europe/Paris

- Europe/Podgorica

- Europe/Prague

- Europe/Riga

- Europe/Rome

- Europe/Samara

- Europe/San_Marino

- Europe/Sarajevo

- Europe/Simferopol

- Europe/Skopje

- Europe/Sofia

- Europe/Stockholm

- Europe/Tallinn

- Europe/Tirane

- Europe/Tiraspol

- Europe/Uzhgorod

- Europe/Vaduz

- Europe/Vatican

- Europe/Vienna

- Europe/Vilnius

- Europe/Volgograd

- Europe/Warsaw

- Europe/Zagreb

- Europe/Zaporozhye

- Europe/Zurich

- GB

- GB-Eire

- GMT

- GMT0

- Greenwich

- HST

- Hongkong

- IET

- IST

- Iceland

- Indian/Antananarivo

- Indian/Chagos

- Indian/Christmas

- Indian/Cocos

- Indian/Comoro

- Indian/Kerguelen

- Indian/Mahe

- Indian/Maldives

- Indian/Mauritius

- Indian/Mayotte

- Indian/Reunion

- Iran

- Israel

- JST

- Jamaica

- Japan

- Kwajalein

- Libya

- MET

- MIT

- MST

- MST7MDT

- Mexico/BajaNorte

- Mexico/BajaSur

- Mexico/General

- NET

- NST

- NZ

- NZ-CHAT

- Navajo

- PLT

- PNT

- PRC

- PRT

- PST

- PST8PDT

- Pacific/Apia

- Pacific/Auckland

- Pacific/Chatham

- Pacific/Chuuk

- Pacific/Easter

- Pacific/Efate

- Pacific/Enderbury

- Pacific/Fakaofo

- Pacific/Fiji

- Pacific/Funafuti

- Pacific/Galapagos

- Pacific/Gambier

- Pacific/Guadalcanal

- Pacific/Guam

- Pacific/Honolulu

- Pacific/Johnston

- Pacific/Kiritimati

- Pacific/Kosrae

- Pacific/Kwajalein

- Pacific/Majuro

- Pacific/Marquesas

- Pacific/Midway

- Pacific/Nauru

- Pacific/Niue

- Pacific/Norfolk

- Pacific/Noumea

- Pacific/Pago_Pago

- Pacific/Palau

- Pacific/Pitcairn

- Pacific/Pohnpei

- Pacific/Ponape

- Pacific/Port_Moresby

- Pacific/Rarotonga

- Pacific/Saipan

- Pacific/Samoa

- Pacific/Tahiti

- Pacific/Tarawa

- Pacific/Tongatapu

- Pacific/Truk

- Pacific/Wake

- Pacific/Wallis

- Pacific/Yap

- Poland

- Portugal

- ROK

- SST

- Singapore

- SystemV/AST4

- SystemV/AST4ADT

- SystemV/CST6

- SystemV/CST6CDT

- SystemV/EST5

- SystemV/EST5EDT

- SystemV/HST10

- SystemV/MST7

- SystemV/MST7MDT

- SystemV/PST8

- SystemV/PST8PDT

- SystemV/YST9

- SystemV/YST9YDT

- Turkey

- UCT

- US/Alaska

- US/Aleutian

- US/Arizona

- US/Central

- US/East-Indiana

- US/Eastern

- US/Hawaii

- US/Indiana-Starke

- US/Michigan

- US/Mountain

- US/Pacific

- US/Pacific-New

- US/Samoa

- UTC

- Universal

- VST

- W-SU

- WET

- Zulu