Xron (Zope Scheduled Methods Product)

Provides a way to execute methods at specified times (similar to Unix cron). Use for: email reminders; periodic garbage collection; ageing of objects; updating syndicated content from other sites; running processes in the background (e.g. sending multiple emails, paging technical support) (just schedule with a time of now); load leveling (deferring tasks to a time of expected lighter load); an intelligent queue based email system that can retry later if your SMTP host is down; packing your ZODB regularly; rebuilding or reindexing Catalogs; removing old Sessions (from SQLSession or FSSession); building more general event products (with conditional events, dependencies, etc.).

The "X" in Xron represents the Greek letter "chi". Pronounce "Xron" as you would pronounce the "chron" of "chronometer" (or as you would "cron" of Unix).

Classes

You use Xron by creating an object of the class "Xron DTML Method". You can add an XronDTMLMethod to any folder. An XronDTMLMethod is a DTML method that has a time associated with it.

The time associated with an XronDTMLMethod is an object of the Zope DateTime class. See ../DateTime/DateTime.py for allowable input formats (explained in English within a Python comment). A disabled event has the null time which is defined as the special time value DateTime(0). For the purpose of entering a null time in the management forms, an empty time field is converted to DateTime(0).

Any output produced by a XronDTMLMethod is written to the log. A XronDTMLMethod does not have to produce output, but if it does produce output, it may need to set the response headers. For example:

Content-Type: text/plain

Bang!

Note the empty line after the response header.

An XronDTMLMethod also has an attribute called periodDays that specifies the "Reschedule Interval" i.e. the time interval between repetitions of the event. This attribute has type float and units of days. A value of 0.0 indicates a one-time event.

The management screen for XronDTMLMethods contains a tab labeled "Trigger" which helps with debugging by test-firing the event, without regard to the scheduled firing time.

You can provide added value to events by subclassing the XronDTMLMethod class. In particular, "reschedule", which is called only when the event is triggered, can be overridden to provide more complex event scheduling. Its interface is compatible with DTMLMethods:

    input:  REQUEST.XronEventOldTime a DateTime object
    output: REQUEST.XronEventTime a DateTime object

For example, define a ZClass (let's call it "Nag" just for example) that derives from XronDTMLMethod. Give it a DTML method called "reschedule". The name must be "reschedule" so that it overrides the "reschedule" method of XronDTMLMethod. The new "reschedule" method consists of the following DTML statement:

   <dtml-call "REQUEST.set('XronEventTime', REQUEST.XronEventOldTime + 1.0/24)">

...which reschedules the event to execute one hour after it was last scheduled to execute. Then create one or more instances of Nag, each with DTML code to do what you want. Each Nag (instance of the Nag class) will do its thing hour after hour after hour.... Note the use of floating point arithmetic in DateTime calculations. Writing 1.0/24 instead of 1/24 forces the type of the result to be floating point.

Permissions

The following permissions are defined by this product:

    AddXronDTMLMethods

People who have this permission have the power to execute Zope methods on your webserver repeatedly and rapidly; so, don't give this permission to just anyone. Think of scheduled events as time bombs. Whom do you trust to play with time bombs near your server?

XronDTMLMethods by default have the role "Anonymous". If you want a XronDTMLMethod to perform some management function in Zope that requires other roles, you must assign proxy roles to the XronDTMLMethod or to the methods it invokes.

Installation

Unlike some Zope products, Xron 0.0.10 does not assume location of Products directory. Store release package in your Zope Products directory (possibly /<Zope>/lib/python/Products). Gunzip and untar, which creates the Xron subdirectory and places files there.

Set the environment variable STUPID_LOG_FILE to the name of a file for collecting log entries about each event; for example, on MS Windows:

   set STUPID_LOG_FILE=C:\Zope\var\zopeapp.log

If you use a Zope hosting service that let's you manage products thru FTP but does not give you the telnet access needed to set environment variables, investigate the FrozenLogger product.

For Zope version 2.2.0b1 and earlier, you need to install this patch to Client.py (in two places) if your Zope listens for HTTP on a port other than 80:

      #headers['Host']=split(urlparse(url)[1],':')[0]
      headers['Host']=urlparse(url)[1]

For Zope version 2.2.0, you need to install this patch to Client.py:

      #h.connect((self.host, self.port))
      h.connect(self.host, self.port)

Restart Zope after installing.

Infrastructure

Creates an object "Schedule" in the root folder. Schedule is a ZCatalog which indexes XronDTMLMethods. The catalog is created (if it doesn't already exist) when Zope loads the product. You cannot directly modify Schedule or delete it as long as this product is installed.

Creates a thread "Dispatcher" which converts the passage of time into an ordered series of calls to the methods identified in the Schedule.

Contact

For more information or to get the latest version, visit Xron's home base http://www.zope.org/Members/lstaffor/

Usage Examples

Weekly Email Reminder

Add a new XronDTMLMethod with the id "Garbage" (for example). Set Reschedule Interval to 7.0 days. Set Execute At to the first time you want the reminder to appear, for example "2000/08/10 16:10:00 US/Pacific". Paste the following into the DTML textbox (but please substitute your email address for mine):

        <dtml-with "PARENTS[-1]"><dtml-sendmail mailhost=MailHost>
        To: [email protected]
        From: Loren's Reminder Service <[email protected]>
        Reply-To: Loren Stafford <[email protected]>
        Subject: REMINDER: Take out the garbage tonight!

        Tomorrow is garbage day!
        </dtml-sendmail></dtml-with "PARENTS[-1]">

Programmatically Creating an Event

The following DTML Method creates a scheduled method:

        <dtml-with "manage_addProduct['Xron']">
        <dtml-call expr="manage_addXronDTMLMethod(
                   'SchedMethodId1',
                    title='Scheduled Method 1 Title',
                    executeAt = _.DateTime()+14.0,
                    periodDays = 0.0,
                    file = 'Content-Type: text/plain\n\nBANG!!!',
                    )">
        </dtml-with>

Finding Expired Events for Deletion

The following DTML Method makes a list of all unscheduled (expired) Xron DTML Methods in the current folder:

        <dtml-call "REQUEST.set('nullEvents',[])">
        <dtml-in "objectValues(['Xron DTML Method'])">
          <dtml-if "nextEventTime()==_.DateTime(0)">
            <dtml-call "nullEvents.append(id())">
          </dtml-if>
        </dtml-in>

The following DTML Method lists all unscheduled Xron Methods in the Schedule catalog:

        <dtml-in "Schedule(
          nextEventTime=_.DateTime(1),
          nextEventTime_usage='range:max'
        )">
          <dtml-with "Schedule.getobject(data_record_id_)">
            <dtml-var id>
          </dtml-with>
        </dtml-in>

Known problem with product initialization on Linux

Search the [email protected] and zope-dev.org archives for more information about a problem that causes Zope to fail to respond after start-up when Xron is newly installed.

Use the Google "search lists.zope.org" option at http://www.zope.org/SiteIndex/searchForm with search text of "xron linux".