MMBase Crontab

Author: Michiel Meeuwissen
Date: 2004-09-23

This software is OSI Certified Open Source Software. OSI Certified is a certification mark of the Open Source Initiative.

The license (Mozilla version 1.0) can be read at the MMBase site. See http://www.mmbase.org/license

Table of Contents

1. Introduction
2. Installation
3. Configuration

1. Introduction

The crontab functionality is of course heavily inspired by UNIX' crontab. This means that you can schedule jobs with it. You specify when it must run by a string like: "*/3 5-23 * * *" which means every three minutes, but not during the night, or "0 7 * * *" which means every day at 7 am.

2. Installation

To install the MMBase crondaemon, you have to place mmbase-crontab.jar, which will activate the crontab module (crontab.xml). You can then optionally also deploy the MMBaseCronTab application (with the cronjobs builder). If you want to only use the builder and not the module, you can place a crontab.xml in config/modules containing <status>inactive</status>. You can also simply not use the module, because it doesn't harm.

3. Configuration

You specify what must be run by the class-name of a class implementing 'Runnable', or optionally, implementing the specialized interface CronJob. The CronJob interface extends Runnable but also alows for code to be run when the con-daemon stops or when it starts (a String can be provided for configuration). You must implement such a class and put the class-file e.g. in WEB-INF/classes.

In combination with the 'ClassSecurity' feature you can easily implement CronJobs using the bridge interfaces, so you might want to privilege your class in <mmbase-config>security/classauthentication.xml.

You can schedule it in two ways now. Make either a cronjobs object or edit <mmbase-config>modules/crontab.xml, or <mmbase-config>utils/crontab.xml. For the module the format is as follows:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE module PUBLIC "-//MMBase//DTD module config 1.0//EN" "http://www.mmbase.org/dtd/module_1_0.dtd">
<module maintainer="mmbase.org" version="0">
  <status>active</status>
  <class>org.mmbase.applications.crontab.modules.CrontabModule</class>
  <properties>
    <property name="memorystats">* * * * *|org.mmbase.applications.crontab.MMBaseStatsJob||Memory|short</property>
  </properties>
</module>

The format for 'crontab.xml' in the utils directory is very similar (find the example). Every property in these files consists of 5 fields, seperated by the pipe (|) symbol. They have the following use:

Timeformat. This is the standard 'crontab' format used in unix, so therefore we refer to the UNIX crontab manual page for more information.
The class that will be executed. This class should implement the 'org.mmbase.applications.crontab.CronJob' interface, of which the 'run()' method will be called whenever it is time to run the cronjob.
Description of the job (optional).
A configuration string (optional). This string is available to the job class instance, so you can make generic cronjob implementations that can be used for multiple jobs.
The type of the job (optional). This can be one of the following:
- short. This means that the job is short, and that the current thread can execute it. No new thread will be spawned, but it is only suitable for jobs that are quickly done. Otherwise, other jobs will have to wait until this job is completed.
- canbemore. This means that a new Thread will be spawned to run the job. It doesn't check if there already was a thread from a previous execution that is still running, so it can in theory blow up your application server. If the job execution time exceeds the interval in which new jobs are spawned, this will result in a thread bomb.
- mustbeone. This is the default, and means that a new Thread will be spanwed to run the job, but only if the job wasn't still running from the previous invocation. This means that a job might be skipped when the previous one is still running.
On which server to run.
This is a regular expression (defaults to ".*") to which the current value of MMBase.getMMBase().getMachineName() must match. This makes it possible to have the same config-files on different servers, without having the same jobs running on them too.