///////////////////////////////////////////////////////////////
 * 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.qi4j.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/qi4j/library/scheduler/SchedulerTest.java
tag=assembly
----

== Configuration ==

SchedulerConfiguration defines configuration properties details:

[snippet,java]
----
source=libraries/scheduler/src/main/java/org/qi4j/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/qi4j/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/qi4j/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/qi4j/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/qi4j/library/scheduler/docsupport/SchedulerDocs.java
tag=timeline
-----------

Here is the actual Timeline contract:

[snippet,java]
----
source=libraries/scheduler/src/main/java/org/qi4j/library/scheduler/timeline/Timeline.java
tag=timeline
----