The SLF4J Logger used by this library is named "org.qi4j.library.scheduler".

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:

new SchedulerAssembler().visibleIn( Visibility.application )
    .withConfig( configModuleAssembly, Visibility.layer )
    .withTimeline()
    .assemble( moduleAssembly );

SchedulerConfiguration defines configuration properties details:

/**
 * @return Number of worker threads, optional and defaults to the number of available cores.
 */
@Optional
Property<Integer> workersCount();

/**
 * @return Size of the queue to use for holding tasks before they are run, optional and defaults to 10.
 */
@Optional
Property<Integer> workQueueSize();

/**
 * @return If the scheduler must stop without waiting for running tasks, optional and defaults to false.
 */
@UseDefaults
Property<Boolean> stopViolently();

To write a schedulable Task, compose an Entity with the Task type to be able to schedule it.

The Task contract is quite simple:

public interface Task
    extends Runnable
{
    Property<String> name();

    @UseDefaults
    Property<List<String>> tags();
}

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:

interface MyTaskEntity extends Task
{
    Property<String> myTaskState();

    Association<AnotherEntity> anotherEntity();
}

class MyTaskMixin implements Runnable
{
    @This MyTaskEntity me;

    @Override
    public void run()
    {
        me.myTaskState().set(me.anotherEntity().get().doSomeStuff(me.myTaskState().get()));
    }
}

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.

@Service Scheduler scheduler;

public void method()
{
    MyTaskEntity myTask = todo();
    Schedule schedule = scheduler.scheduleOnce( myTask, 10, false );
    // myTask will be run in 10 seconds from now
}

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:

@Service Timeline timeline;

Here is the actual Timeline contract:

public interface Timeline
{
  [...snip...]

    Iterable<TimelineRecord> getLastRecords( int maxResults );
      [...snip...]

    Iterable<TimelineRecord> getNextRecords( int maxResults );
      [...snip...]

    Iterable<TimelineRecord> getRecords( DateTime from, DateTime to );
      [...snip...]

    Iterable<TimelineRecord> getRecords( long from, long to );
}