= Kraken Cron =
[[PageOutline]]
Kraken Cron provides job scheduling.

== Requirements ==
 * kraken api 1.0.0
 * slf4j api 1.5.6
 * hsqldb 1.8.0.7

== Commands ==
 * cron.usage
  {{{
kraken> cron.usage
SYNTAX:
* * * * * Runnable instance.name
- - - - -
| | | | |
| | | | +----- day of week (0 - 6) (Sunday=0)
| | | +------- month (1 - 12)
| | +--------- day of month (1 - 31)
| +----------- hour (0 - 23)
+------------- min (0 - 59)

EXAMPLES:
Run once a year                       |   0 0 1 1 *
Run once a week                       |   0 0 * * 0
Run every five minute                 | */5 * * * *
Run once a day from monday to friday  |   0 0 * * 1-5
Run once a day on saturday and sunday |   0 0 * * 0,6
}}}
 * cron.register [rule] [instance.name]
  {{{
kraken> cron.register * * * * * sample
new schedule [1] registered.
}}}
  * Run 'sample' service instance (must be Runnable) every minutes.
 * cron.unregister [schedule id]
  {{{
kraken> cron.unregister 1
schedule unregistered.
}}}
  * Unregister schedule.
 * cron.list
  * List all schedules.
 * cron.queue
  * View current state of scheduling queue.
 * cron.run [instance.name]
  * Run now
 * cron.runnables
  * List all active Runnable instances.

== Schedule Syntax ==
 * The comma (',') operator specifies a list of values. 
  * For example, "1,3,4,7,8" (space inside the list must not be used)
 * The dash ('-') operator specifies a range of values. 
  * For example, "1-6", which is equivalent to "1,2,3,4,5,6"
 * The asterisk ('*') operator specifies all possible values for a field. 
  * For example, an asterisk in the hour time field would be equivalent to 'every hour' .
 * The slash ('/') operator (called "step"), which can be used to skip a given number of values. 
  * For example, "*/3" in the hour time field is equivalent to "0,3,6,9,12,15,18,21".
 * http://en.wikipedia.org/wiki/Cron#crontab_syntax

== How to create Runnable OSGi service instance? ==
 * All iPOJO component instances have '''instance.name''' OSGi service property.
  * Create Runnable component using by '''ipojo.create''' command. (requires kraken ipojo bundle)
 * Check if OSGi service is registered as you want. 
  * Use '''osgi.services''' and '''osgi.properties [service.id]''' commands. (requires kraken core above 1.1.0)
  * '''instance.name''' property must be exist.

== Cron API ==
=== How to build Schedule object? ===
 * Run every minute.
 {{{ 
Schedule sample = new Schedule.Builder("sample").build();
}}}
 * Run every day.
 {{{
Schedule sample = new Schedule.Builder("sample").buildDaily();
}}}
 * Run every week.
 {{{
Schedule sample = new Schedule.Builder("sample").buildWeekly();
}}}
 * Run every month.
 {{{
Schedule sample = new Schedule.Builder("sample").buildMonthly();
}}}
 * Run every year.
 {{{
Schedule sample = new Schedule.Builder("sample").buildYearly();
}}}
 * 0 0 1 1 3-6 sample
 {{{
Schedule sample = new Schedule.Builder("sample").build("0 0 1 1 3-6"); 
}}}
  * If you have specified any field using .set(CronField.Type, expression) before calling .build(expression), the former specification will be ignored.
 * 0,3,5,9  4-10  */10  *  0  sample
 {{{
Schedule sample = new Schedule.Builder("sample")
                              .set(CronField.Type.DAY_OF_WEEK, "0")
                              .set(CronField.Type.DAY_OF_MONTH, "*/10")
                              .set(CronField.Type.HOUR, "4-10")
                              .set(CronField.Type.MINUTE,"0,3,5,9")
                              .build();
}}}
  * If there is no explicit specificaton of a field, default value will be *(wild).
=== How to get CronService reference? ===
 * OSGi standard way
 {{{
ServiceReference ref = bundleContext.getServiceReference(CronService.class.getName());
CronService cronService = (CronService) bundleContext.getService(ref);
}}}
 * iPOJO way
  * use @Requires annotation or metadata.xml configuration.
  * iPOJO will inject CronService for you.
=== Schedule Registration ===
{{{
Schedule schedule = new Schedule.Builder("sample").build();
int id = cronService.registerSchedule(schedule);
}}}
=== Schedule Unregistration ===
{{{
cronService.unregisterSchedule(id);
}}}
== Class Diagram ==
[[Image(cron.png)]]
== History ==
 * 1.0.0 release: initial release (2009-10-19)