The SLF4J Logger used by this library is named "org.apache.zest.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 browsing of 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 @UseDefaults
Property<Integer> workersCount();

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

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

The Task contract is quite simple:

@Concerns( UnitOfWorkConcern.class )
public interface Task
    extends Runnable
{
    Property<String> name();

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

}

Tasks have a mandatory name property and an optional tags property. These 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. See UnitOfWork strategy below.

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.

All Schedules are durable. In other words, it will survive an Application restart, and your application should not schedule it again, as the Schedules are when the SchedulerService is activated after bootstrap.

There are three ways to schedule a Task using the Scheduler service: once or with a cron expression or providing your own Schedule instance.

@Service
Scheduler scheduler;

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

If the Schedule is running when it is time to be executed, then the execution will be skipped. This means that the Task must complete within its period, or executions will be skipped. The sideeffect of that is that this reduces thread exhaustion.

When the Task execution is skipped, the overrun() property on the Schedule is incremented by 1.

All Schedules are durable and the Task must be an Entity Composite. It also means that Tasks should be schedule once and not on each reboot. The SchedulerService will load all Schedules on activation.

While the Task is running, the Schedule will be held in the UnitOfWork of the TaskRunner. This means that IF the Schedule is updated, i.e. cancelled or directly manipulating Schedule properties, the UnitOfWork.complete() will fail. And if the Task is executing within the same UnitOfWork, any changes made will not take place.

The TaskRunner creates a UnitOfWork and the Task is excuted within that UnitOfWork. This may be very convenient, but as noted in Durability above, that UnitOfWork will fail if Schedule properties are updated while the Task is running. To avoid that the Task’s operations suffers from this, OR if the Task wants a Retry/DiscardOn strategy different from the default one, then the Task can simply declare its own. such as;

@Override
@UnitOfWorkRetry( retries = 3 )
@UnitOfWorkDiscardOn( IllegalArgumentException.class )
@UnitOfWorkPropagation( value = UnitOfWorkPropagation.Propagation.REQUIRES_NEW, usecase = "Load Data" )
public void run()
{

It is possible to implement Schedule directly. It must be declared as an EntityComposite in the assembly, and be visible from the SchedulerService. No other considerations should be necessary.

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( ZonedDateTime from, ZonedDateTime to );
      [...snip...]

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