WakeupCaller Project
The WakeupCaller project is part of the
Services Working Group.
The WakeupCaller runs as a Chandler Service. Items of kind WakeupCall are registered with the
WakeupCaller and can be called at a specific interval. The WakeupCaller
can be leveraged for background tasks such as downloading mail from an IMAP Server
or polling a WebDav server.
People
Overview
The WakeupCaller utilizes the Twisted Asynchronous Reactor for time management. The WakeupCaller
exposes three methods
startup,
shutdown, and
refresh. The WakeupCaller is
initialized and started during Chandler startup in Application.py. It is shutdown by Application.py
during Chandler exit. The refresh method can be called anytime during the Chandler lifecycle and
instructs the WakeupCaller to refetch all items of kind WakeupCall. Refetching will pickup any changes
made to WakeupCalls (addition, deletion, update) while Chandler was running. A reference to
the running WakeupCaller is present as a Global. The following code demonstrates how to do a refresh:
import application.Globals as Globals
def refreshWakeupCaller():
Globals.wakeupCaller.refresh()
Tutorial
The WakeupCall Kind
The WakeupCall Kind is defined in osaf/framework/wakeup/parcel.xml. There are five attributes to the kind.
- callOnStartup (defaults to False) indicates whether the WakeupCall would like to be called on Chandler Startup.
- repeat (defaults to False) indicates whether the WakeupCall would like to be called repeatly or just once.
- enabled (defaults to True) indicates whether the WakeupCall is enabled. If the WakeupCall is not enabled it will be ignored by the WakeupCaller.
- delay (defaults to 0) indicates the amount of time to wait between WakeupCalls. Some example delays are "00:10:0:00" (10 Hours), "00:00:10:00" (Ten Minutes), and "00:00:00:10" (Ten Seconds).
- wakeupCallClass (defaults to "osaf.framework.wakeup.WakeupCaller.WakeupCall") provides the name of a WakeupCall sub-class that will have its receiveWakeupCall method executed at the interval specified in delay.
The WakeupCall Class
To receive a WakeupCall one subclasses from osaf.framework.wakeup.WakeupCaller.WakeupCall. This class defines one method called
receiveWakeupCall. The method takes one argument, the WakeupCall item associated with the class. This method will be called by the WakeupCaller in a dedicated thread (with its own Repository View). The WakeupCaller runs in the Twisted Reactor thread but leverages a thread pool of RepositoryThreads for WakeupCalls to prevent blocking.
Putting It All Together
- Create a subclass of osaf.framework.wakeup.WakeupCaller.WakeupCall and define the receiveWakeupCall method.
import osaf.framework.wakeup.WakeupCaller as WakeupCaller
class WakeupCallTest(WakeupCaller.WakeupCall):
def receiveWakeupCall(self, wakeupCallItem):
print "I Got a Wakeup Call. This class is associated with the WakeupCall Item (%s)", wakeupCallItem.itsUUID
- Edit your parcel.xml and add a WakeupCall Kind instance. For the wakeupCallClass put the path to your osaf.framework.wakeup.WakeupCaller.WakeupCall subclass. This binds the WakeupCall Python sub-class to the Repository WakeupCall Kind instance. Also make sure to add the namespace for the WakeupCall kind (xmlns:wakeup="http://osafoundation.org/parcels/osaf/framework/wakeup") to your parcel.xml. The example parcel.xml below will call the WakeupCallTest classes receiveWakeupCall method on Chandler startup and again at two minutes intervals until Chandler is shutdown.
<?xml version="1.0" encoding="iso-8859-1"?>
<Parcel itsName="test"
xmlns:wakeup="http://osafoundation.org/parcels/osaf/framework/wakeup">
<wakeup:WakeupCall itsName="Test">
<wakeupCallClass>osaf.test.WakeupCallTest.WakeupCallTest</wakeupCallClass>
<callOnStartup>True</callOnStartup>
<enabled>True</enabled>
<repeat>True</repeat>
<delay>00:00:02:00</delay>
</wakeup:WakeupCall>
</Parcel>
- For a real world example take a look at the Chandler Zaobao parcel (osaf.examples.zaobao) which defines a WakeupCall to poll for RSS feeds.
Completed Feature work
A second version of the WakeupCaller has been checked in to CVS. It was discoved that the Twisted Thread Pool was causing an issue with PyLucene in the Repository Layer
which resulted in a core dump. A rewrite of some key WakeupCaller functionality was required but now everything is working.
The first version of the WakeupCaller has been checked in to CVS. The Zaobao parcel (osaf.examples.zaobao) has been updated to work with
the WakeupCaller and can be used as an example for creating a WakeupCall.
-- BrianKirsch - 29 Nov 2004