<document>
<header>
<product>resin</product>
<title>CronResource</title>
<description>
<p>CronResource executes application Work tasks at configured intervals.</p>
</description>
</header>

<body>

<summary/>

<p>Often, applications need to run a task at specific times.  The
<code>CronResource</code> provides a standard way of doing that.
Applications need only create a standard
<code>java.lang.Runnable</code> task and configure the CronResource.
Resin configure's the work task with 
<a href="doc|config|init">bean-style configuration</a>.
</p>

<example title="Task running every 15 minutes">
&lt;web-app xmlns="http://caucho.com/ns/resin">
  &lt;resource type="com.caucho.resources.CronResource">
    &lt;init>
      &lt;cron>*/15&lt;/cron>
      &lt;work resin:type="example.PeriodicWork">
        &lt;foo>Custom Config&lt;/foo>
      &lt;/work>
    &lt;/init>
  &lt;/resource>
&lt;/web-app>
</example>

<section title="com.caucho.resources.CronResource">
<deftable-parameters>
<tr><td>cron<td>Specifies the times the task should be run<td>required
<tr><td>work<td>Specifies application's work bean<td>required
</deftable-parameters>

<p>The cron specification follows the Unix crontab format.  The cron
is composed of 5 fields: minutes, hours, day of month, month, and day
of week.</p>

<p>Each field specifies a range of times to be executed.  The patterns
allowed are:

<deftable title="example ranges">
<tr><th>range<th>explanation (using minutes as example)
<tr><td>*<td>run every minute
<tr><td>*/5<td>run every 5 minutes
<tr><td>0,5,50<td>run at :00, :05, :50 every hour
<tr><td>0-4<td>run at :00, :01, :02, :03, :04
<tr><td>0-30/2<td>run every 2 minutes for the first half hour
</deftable>

<p>The minutes field is always required, and the hours, days, and
months fields are optional.</p>

<deftable title="example times">
<tr><th>range<th>explanation
<tr><td>0 */3<td>run every 3 hours
<tr><td>15 2 *<td>run every day at 0215 local time
<tr><td>0 0 */3<td>run every third day at midnight
<tr><td>15 0 * * 6<td>run every Saturday at 0015
</deftable>
</section>

<section title="Hello, World example">

<example title="WEB-INF/web.xml">

&lt;web-app xmlns="http://caucho.com/ns/resin"&gt;
  &lt;resource type="com.caucho.resources.CronResource"&gt;
    &lt;init&gt;
      &lt;!-- every minute --&gt;
      &lt;cron&gt;*&lt;/cron&gt;
      &lt;work resin:type="example.PeriodicWork"/&gt;
    &lt;/init&gt;
  &lt;/resource&gt;
&lt;/web-app&gt;
</example>

<example title="WEB-INF/classes/example/PeriodicWork.java">

package example;

import java.util.logging.Level;
import java.util.logging.Logger;

public class PeriodicWork implements Runnable {
  static protected final Logger log = 
    Logger.getLogger(PeriodicWork.class.getName());

  public PeriodicWork()
  {
    log.info("PeriodicWork: constructor");
  }

  /**
   * Required implementation of java.lang.Runnable.run()
   */
  public void run()
  {
    log.info("PeriodicWork: run() Hello, World");
  }
}
</example>

<results>
[13:04:27.429] PeriodicWork: constructor
[13:05:00.095] PeriodicWork: run() Hello, World
[13:06:00.182] PeriodicWork: run() Hello, World
</results>
</section>

<section title="bean-style configuration example">

<example title="WEB-INF/web.xml">

&lt;web-app xmlns="http://caucho.com/ns/resin"&gt;
  &lt;resource type="com.caucho.resources.CronResource"&gt;
    &lt;init&gt;
      &lt;!-- every minute --&gt;
      &lt;cron&gt;*&lt;/cron&gt;
      &lt;work resin:type="example.PeriodicWork"&gt;
        &lt;message&gt;Goodybye, World&lt;/message&gt;
      &lt;/work&gt;
    &lt;/init&gt;
  &lt;/resource&gt;
&lt;/web-app&gt;
</example>

<example title="WEB-INF/classes/example/PeriodicWork.java">

package example;

import java.util.logging.Level;
import java.util.logging.Logger;
import javax.resource.spi.work.Work;

public class PeriodicWork implements Work {
  static protected final Logger log = 
    Logger.getLogger(PeriodicWork.class.getName());

  String _message;

  public PeriodicWork()
  {
    log.info("PeriodicWork: constructor");
  }

  /**
   * Optional, called in response to presence of &lt;message&gt;
   * configuration tag. 
   */
  public void setMessage(String message)
  {
    log.info("PeriodicWork: setMessage");
    _message = message;
  }

  /**
   * Optional, called after bean is created and any setters
   * from configuration are called.
   */
  public void init()
    throws Exception
  {
    log.info("PeriodicWork: init()");

    if (_message == null)
      throw new Exception("`message' is required");
  }

  /**
   * Required implementation of java.lang.Runnable.run()
   */
  public void run()
  {
    log.info("PeriodicWork: run() " + _message);
  }

  /**
   * Implementation of javax.resource.spi.work.Work.release()
   */
  public void release()
  {
    log.info("PeriodicWork: release()");
  }
}
</example>

<results>
[13:04:27.429] PeriodicWork: constructor
[13:04:27.429] PeriodicWork: setMessage
[13:04:27.429] PeriodicWork: init()
[13:05:00.095] PeriodicWork: run() Goodbye, World
[13:06:00.182] PeriodicWork: run() Goodbye, World
(close Resin)
[13:06:00.345] PeriodicWork: release()
</results>
</section>

</body>
</document>
