Name |
time scheduler which works on Vert.x event bus |
---|---|
Backends | JVM |
Maven coordinates | |
Compatible Ceylon release |
JVM: 1.2.x, 1.3.x (latest) |
Published | May 4, 2017 |
Stats |
Downloads (JVM): 33337 Source downloads: 212 |
Authors |
Lis |
License | The MIT License (MIT) Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
Description |
Chime is time scheduler verticle which works on Vert.x event bus and provides:
> Chime communicates over event bus with Content.<a name ="running"></a> Running the Chime.Deploy Chime using import io.vertx.ceylon.core {vertx} import herd.schedule.chime {Chime} Chime().deploy(vertx.vertx()); Or with <a name ="configuration"></a> Configuration.Following parameters could be specified in JsonObject { // address _Chime_ is listen to, default is "chime" "address" -> String, // limiting scheduling period in years, default is 10 years "max year period limit" -> Integer, // tolerance in milliseconds used to compare actual and requested times // default is 10 milliseconds "tolerance" -> Integer }; <a name ="scheduling"></a> Scheduling.Chime operates by two structures: timer and scheduler.
<a name ="requests-and-responses"></a> Requests and responses.Chime communicates over event bus with Each request must contain
<a name ="scheduler"></a> Scheduler.At least one scheduler has to be created before creating timers.
Each timer operates within some particular scheduler. <a name ="scheduler-request"></a> Scheduler request.In order to maintain schedulers send JsonObject { // operation code, mandatory "operation" -> String, // scheduler name, mandatory "name" -> String|JsonArray, // state, mandatory only if operation = 'state' otherwise optional "state" -> String, // default time zone ID, overriden by timer time zone, optional "time zone" -> String }; > Chime listens event bus at scheduler name address with messages for the given scheduler. > Complete list of messages is available at Github. There are two limitations for the scheduler name:
> <a name ="scheduler-example"></a> Scheduler example.// create scheduler with name 'scheduler' eventBus.send<JsonObject> ( "chime", JsonObject { "operation" -> "create", "name" -> "scheduler" }, (Throwable|Message<JsonObject> msg) { if (is Message<JsonObject> msg) { // scheduler has been successfully created } else { // error while creating scheduler } } ); // set scheduler state to paused eventBus.send<JsonObject> ( "chime", JsonObject { "operation" -> "state", "name" -> "scheduler", "state" -> "paused" }, (Throwable|Message<JsonObject> msg) { if (is Message<JsonObject> msg) { // scheduler state is set to paused } else { // error while setting scheduler state } } ); <a name ="timer"></a> Timer.Once scheduler is created timers can be run within. There are two ways to access a given timer:
> Timer full name is scheduler name and timer name separated with ':', i.e. scheduler name:timer name. > Timer fire message is sent to timer full name address. > Both scheduler and timer names must not contain :,
since it is used as separator of scheduler name:timer name. <a name ="timer-request"></a> Request.> Complete list of requests and responses is available
at Github. Request has to be sent in Request format: JsonObject { // operation code, mandatory "operation" -> String, // timer short or full name, mandatory "name" -> String|JsonArray, // state, optional, except if operation = 'state' "state" -> String, // fields for create operation: // maximum number of fires, default - unlimited "maximum count" -> Integer, // if true message to be published and to be sent otherwise, optional, default is false "publish" -> Boolean, // start time, optional, if doesn't exist timer will start immediately "start time" -> JsonObject { // seconds, mandatory "seconds" -> Integer, // minutes, mandatory "minutes" -> Integer, // hours, mandatory "hours" -> Integer, // days of month, mandatory "day of month" -> Integer, // months, mandatory "month" -> Integer|String, // year, mandatory "year" -> Integer }, // end time, nonmadatory, default no end time "end time" -> JsonObject { // seconds, mandatory "seconds" -> Integer, // minutes, mandatory "minutes" -> Integer, // hours, mandatory "hours" -> Integer, // days of month, mandatory "day of month" -> Integer, // months, mandatory "month" -> Integer|String, // year, mandatory "year" -> Integer }, // time zone, optional, default is scheduler time zone // or server local if not given at both scheduler and timer "time zone" -> String, // message which is attached to timer fire event, optional "message" -> String|Boolean|Integer|Float|JsonObject|JsonArray // delivery options the timer fire event is sent with, optional "delivery options" -> JsonObject, // timer desciption, mandatoty for create operation "description" -> JsonObject }; Notes:
> <a name ="unique-timer-name"></a> Unique timer name.The Chime may generate unique timer name automatically. Just follow next steps:
> <a name ="supported-timers"></a> Supported timers.Timer is specified within description field of timer create request. >
Details of cron specification is listed below. > Month and day of week may be specified either with digits or names.
> Names are case insensitive and might be either short or full. >
> Interval timer delay is in seconds
This may be useful to fire at specific dates / times. For example, following timer fires
at 8-00 each Monday with "Monday morning" message and at 17-00 each Friday with "Friday evening" message: JsonObject { "type" -> "union", "timers" -> JsonArray { JsonObject { "type" -> "cron", "seconds" -> "0", "minutes" -> "0", "hours" -> "8", "days of month" -> "*", "months" -> "*", "days of week" -> "Monday", "message" -> "Monday morning" }, JsonObject { "type" -> "cron", "seconds" -> "0", "minutes" -> "0", "hours" -> "17", "days of month" -> "*", "months" -> "*", "days of week" -> "Friday", "message" -> "Friday evening" } } }; > Each sub-timer may fire with each own message, just put > <a name ="timer-events"></a> EventsTimer sends or publishes to full timer name address ('scheduler name:timer name') two types of events in
> Fire event is sent or published with delivery options given at timer create request. > Complete event is always published in order every listener receives it. > The value at the 'event' key indicates the event type (fire or complete). > Timer full name is scheduler name and timer name separated with ':', i.e. "scheduler name:timer name". > String formatted time / date is per ISO 8601. <a name ="time-zones"></a> Time zones.Available time zones,
actual availability may depend on particular JVM installation. See also time zones and JRE. Time zone may be set at either scheduler or timer level.
If no time zone is set at timer then scheduler time zone is applied
otherwise timer timezone is used. If no timezone is given at all
then time zone local for the machine is used. <a name ="timer-example"></a> Example.// creat new Scheduler with name "scheduler" at first and then create timer eventBus.send<JsonObject> ( "chime", JsonObject { "operation" -> "create", "name" -> "scheduler" }, (Throwable|Message<JsonObject> msg) { if (is Message<JsonObject> msg) { // create timer eventBus.send<JsonObject>( "chime", JsonObject { "operation" -> "create", // full timer name == address to listen timer "name" -> "scheduler:timer", "max count" -> 3, "time zone" -> "Europe/Paris", "descirption" -> JsonObject { // timer type is 'cron' "type" -> "cron", // 27 with step 30 leads to fire at 27 and 57 seconds "seconds" -> "27/30", // every minute "minutes" -> "*", // every hour "hours" -> "*", // every day "days of month" -> "*", // from January and up to October "months" -> "january-OCTOBER", // at second Saturday and at each Sunday "days of week" -> "sat#2,sunday", "years" -> "2015-2019" } }, (Throwable|Message<JsonObject?> msg) { // Chime replies if timer successfully created or some error occured print(msg); } ); } else { print("error while creating scheduler: ``msg``"); } } ); // listen timer eventBus.consumer ( "scheduler:timer", (Throwable | Message<JsonObject?> msg) { ... } ); <a name ="scheduler-timer-interfaces"></a> Scheduler and Timer interfaces.
Example: connectToScheduler ( (Throwable|Scheduler scheduler) { if (is Scheduler scheduler) { scheduler.createIntervalTimer ( (Throwable|Timer timer) { if (is Timer timer) { timer.handler ( (TimerEvent event) {...} ); } else { // error while creating timer } }, 5 // fires each 5 seconds ); } else { // error while creating / connecting to scheduler } }, "chime", eventBus, "scheduler name" ); <a name ="error-messages"></a> Error messages.The error is sent using possible errors (see
<a name ="cron-expression"></a> Cron expression.<a name ="cron-expression-fields"></a> Expression fields.
Following notations are applicable:
> Names of months and days of the week are case insensitive. > Sunday is the first day of week. <a name ="cron-special-characters"></a> Special characters.
<a name ="cron-expression-builder"></a> Cron expression builder.
Example: JsonObject cron = CronBuilder().withSeconds(3).withMinutes(0).withHours(1).withAllDays().withAllMonths().build(); > Note that 'seconds', 'minutes', 'hours', 'days of month' and 'month' are required fields.
While 'years' and 'days of week' are optional. |
Dependencies |
ceylon.time/1.3.2
shared
io.vertx.ceylon.core/3.4.1
shared
|
Usage |
import herd.schedule.chime "0.2.1"; |
Module links |
Members Imported By Home Code repository Issue tracker Browse Download .car No .js archive Download source archive Download module documentation View API documentation |