| /////////////////////////////////////////////////////////////// |
| * Licensed to the Apache Software Foundation (ASF) under one |
| * or more contributor license agreements. See the NOTICE file |
| * distributed with this work for additional information |
| * regarding copyright ownership. The ASF licenses this file |
| * to you under the Apache License, Version 2.0 (the |
| * "License"); you may not use this file except in compliance |
| * with the License. You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, |
| * software distributed under the License is distributed on an |
| * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| * KIND, either express or implied. See the License for the |
| * specific language governing permissions and limitations |
| * under the License. |
| /////////////////////////////////////////////////////////////// |
| |
| [[library-scheduler,Scheduler Library]] |
| = Scheduler = |
| |
| [devstatus] |
| -------------- |
| source=libraries/scheduler/dev-status.xml |
| -------------- |
| |
| The Scheduler library provides an easy way to schedule tasks using cron expressions if needed. |
| |
| An optional Timeline allows you to browse past and future task runs. |
| |
| include::../../build/docs/buildinfo/artifact.txt[] |
| |
| == Logging == |
| |
| The SLF4J Logger used by this library is named "org.apache.zest.library.scheduler". |
| |
| == Assembly == |
| |
| Use SchedulerAssembler to add the Scheduler service to your Application. This |
| Assembler provide a fluent api to programmatically configure configuration defaults and activate the |
| Timeline service assembly that allow to browse in past and future Task runs. |
| |
| Here is a full example: |
| |
| [snippet,java] |
| ---- |
| source=libraries/scheduler/src/test/java/org/apache/zest/library/scheduler/SchedulerTest.java |
| tag=assembly |
| ---- |
| |
| == Configuration == |
| |
| SchedulerConfiguration defines configuration properties details: |
| |
| [snippet,java] |
| ---- |
| source=libraries/scheduler/src/main/java/org/apache/zest/library/scheduler/SchedulerConfiguration.java |
| tag=configuration |
| ---- |
| |
| == Writing Tasks == |
| |
| To write a schedulable Task, compose an Entity with the Task type to be able to schedule it. |
| |
| The Task contract is quite simple: |
| |
| [snippet,java] |
| ---- |
| source=libraries/scheduler/src/main/java/org/apache/zest/library/scheduler/Task.java |
| tag=task |
| ---- |
| |
| Tasks have a mandatory name property and an optional tags property. Theses properties get copied in |
| each TimelineRecord created when the Timeline feature is activated. |
| |
| The run() method of Tasks is wrapped in a UnitOfWork when called by the Scheduler. |
| Thanks to the UnitOfWork handling in Zest, you can split the work done in your Tasks in |
| several UnitOfWorks, the one around the Task#run() invocation will then be paused. |
| |
| Here is a simple example: |
| |
| [snippet,java] |
| ----------- |
| source=libraries/scheduler/src/test/java/org/apache/zest/library/scheduler/docsupport/SchedulerDocs.java |
| tag=1 |
| ----------- |
| |
| == Scheduling Tasks == |
| |
| Tasks are scheduled using the Scheduler service. This creates a Schedule associated to |
| the Task that allows you to know if it is running, to change it's cron expression and set it's |
| durability. |
| |
| By default, a Schedule is not durable. In other words, it do not survive an Application |
| restart. To make a Schedule durable, set it's durable property to true once its scheduled. |
| |
| There are two ways to schedule a Task using the Scheduler service: once or with a cron |
| expression. |
| |
| === Scheduling once === |
| |
| This is the easiest way to run a background Task once after a given initial delay in seconds. |
| |
| [snippet,java] |
| ----------- |
| source=libraries/scheduler/src/test/java/org/apache/zest/library/scheduler/docsupport/SchedulerDocs.java |
| tag=2 |
| ----------- |
| |
| Note that there is no point in making such a Schedule durable because it won't be run repeatedly. |
| |
| |
| === Scheduling using a cron expression === |
| |
| Cron expression parsing is based on the GNU crontab manpage that can be found here: |
| http://unixhelp.ed.ac.uk/CGI/man-cgi?crontab+5 . |
| |
| The following extensions are used: |
| |
| - a mandatory field is added at the begining: seconds. |
| - a special string is added: @minutely |
| - a special character is added: ? to choose between dayOfMonth and dayOfWeek |
| |
| The ? special char has the same behavior as in the Quartz Scheduler expression. The wikipedia page |
| http://en.wikipedia.org/wiki/CRON_expression |
| explains Quartz Scheduler expression, not simple cron expressions. You'll find there about the ? special |
| char and maybe that some other extensions you would like to use are missing in this project. |
| |
| To sum up, cron expressions used here have a precision of one second. The following special strings can be used: |
| |
| - @minutely |
| - @hourly |
| - @midnight or @daily |
| - @weekly |
| - @monthly |
| - @annualy or @yearly |
| |
| |
| == Durability == |
| Schedules can either be ethereal or durable, passed as an argument to the +Scheduler+. If it is a durable |
| schedule, then the Task must be an Entity Composite. |
| |
| When the |
| == Observing the Timeline == |
| |
| Timeline allow to browse in past and future Task runs. This feature is available only if you activate |
| the Timeline assembly in the SchedulerAssembler}, see above. |
| |
| Once activated, Task success and failures are recorded. Then, the Timeline |
| service allow to browse in past (recorded) and in anticipated (future) Task runs. |
| |
| Use the following in your code to get a Timeline Service injected: |
| |
| [snippet,java] |
| ----------- |
| source=libraries/scheduler/src/test/java/org/apache/zest/library/scheduler/docsupport/SchedulerDocs.java |
| tag=timeline |
| ----------- |
| |
| Here is the actual Timeline contract: |
| |
| [snippet,java] |
| ---- |
| source=libraries/scheduler/src/main/java/org/apache/zest/library/scheduler/timeline/Timeline.java |
| tag=timeline |
| ---- |
| |