The scheduler branch contains a scheduler component (org.osaf.cosmo.scheduler.*) that allows code to be run one some interval on the server, without any user interaction. The main use case for this is to provide notification reports to users that contain upcoming information gathered from the user's collections.

SchedulerImpl

The meat of the scheduler is in the SchedulerImpl class. The SchedulerImpl relies on 3 main components: a UserScheduleManager, a map of JobTypeScheduler implementations, and the Quartz scheduler engine. All components are configured in spring, making adding to or extending the framework easy.

Quartz Scheduler Engine

UserScheduleManager

UserPreferencesScheduleManager

• user schedules are enabled if the preference cosmo.scheduler.enabled=true is present
• a schedule is define by the set of properties that start with cosmo.scheduler.job.[jobName].
• a schedule is enabled if the preference cosmo.scheduler.job.[jobName].enabled=true is present
• a schedule must include a "type" property like cosmo.scheduler.job.[jobName].type=[typeKey] where [typeKey] maps to a JobTypeScheduler that is responsible for scheduling that job type (explained later)

What this means is that all schedules are stored as user preferences (key/value pairs associated to a user). For example the following set of user preferences defines a single schedule named "1" that is handled by the JobTypeScheduler mapped to the key "dummy" and contains extra properties "message" and "notifier.name" (explained later).

This translates into the following Schedule object:

• name = 1
• properties = { cronexp=>"5 * * * * ?" , message=> "Hello World!", notifier.name=>"log" }

Multiple schedules can be defined for a user by using a different jobName. Schedules can be enabled or disabled individually by setting the cosmo.scheduler.[jobName].enabled property. All schedules can be disabled by setting the cosmo.scheduler.enabled to false.

The server already provides atom protocol support for updating user preferences, so schedules can be added/removed/updated using this protocol.

JobTypeScheduler

It is important to note that a JobTypeScheduler is responsible for interfacing with the quartz scheduler engine in order to schedule the job. This means it needs to create a org.quartz.JobDetail, which represents a quartz job, and schedule it using a org.quartz.Trigger . This requires knowledge of how quartz works, but provides the most flexibility.

Implementing new types of Schedules

1. define properties for schedule type (reserved properties are enabled=? and type=?)
2. implement JobTypeScheduler for the schedule type and register with SchedulerImpl
3. have the client manage schedules using user preferences api's/protocols

ForwardLookingJobTypeScheduler

Assuming the use of the UserPreferencesScheduleManager this schedule would be represented as the following user preferences:

So in order to add/remove/update the schedule for a user, the service and protocol apis for user preferences can be used as long as the preferences conform to the above format.

ForwardLookingNotificationJob

   String username = context.getJobDetail().getJobDataMap().getString("username");

The job class can define a username setter like:

   public class MyJob extends Job {
      private String username;

      public void setUsername(String username) {
          this.username = username;
      }
  }

and the spring QuartzJobBean will automatcally populate username from the jobDataMap and scheduler context map.

The base Job class can be configured to execute a set of Filter objects, which allow code to be executed before/after a job. Just like servlet filters, job filters are executed in a filter chain. Most user jobs on the server are going to want at least 2 filters to execute before each job. The first filter is the HibernateSessionFilter, which sets up and tears down a hibernate session, which mimics the OpenSessionInView pattern used in the rest of cosmo. This allows for things like lazy loading in hibernate to work. The second filer is the SecurityContextFilter, which initializes the security context with the owner of the job. This allows the job to be executed as the user and allows security checks to be performed on that user while the job is executed. This prevents a user job from accessing a items the user does not have access to while at the same time leveraging existing auth code.

ServiceJob injects a ContentService into the job, allowing that api to be used during job execution. The ContentService is injected by being added to the quartz schedule context map, which makes it available to each job.

NotificationJob generates a report, represented by the Report interface and sends the results to a Notifier. NotificationJob has a set of Notifier implementations indexed by name. In the above schedule properties, the property notifier.name=email tells the NotificationJob to send the results along with a set of "notifier" properties to the Notifier implementation mapped by the key "email". In this example the notifier properties is the map {email.addresses=> "user1@foo.org,user2@foo.org"}. The set of Notifiers is present in the quartz schedule context map, this it is injected to each NotificationJob.

MutlipleCollectionJob adds a list of collection uids representing the collections that the job is working on.

Then there is ForwardLookingNotificationJob, the only non-abstract job type listed here, which simply implements generateReport(), returning a ForwardLookingReport based on the schedule parameters, to be passed to the specified Notifier instance.

Cosmo will initially provide a notifier that sends email, but it would be easy to plugin additional notifiers that for example use XMPP or SMS in the future.

The flow for a ForwardLookingNotificationJob execution is:

1. Job creates filter chain from list of Filters
2. HibernateSessionFilter sets up hibernate session
3. SecurityContextFilter sets up security context
4. ForwardLookingNotificationJob.generateReport() generates ForwardLookingReport
5. report is passed to notifier, user is notified of results (email)
6. SecurityContextFilter tears down security Context
7. HibernateSessionFilter tears down hibernate session

EmailNotifier

SchedulerImpl Notes

Configuration

Startup

Changes in User Schedules

-- RandyLetness - 07 May 2008