Showing items from Quartz.net

Quartz.Net – The ITrigger Interface

In this post we document the ITrigger interface for Quartz.net. This simple post is one of the documentation series of posts, so it only documents classes and interfaces that are not documented online. Here is the ITrigger interface in all its glory:

namespace Quartz
{
    /// <summary>
    /// The base interface with properties common to all <see cref="ITrigger" />s - 
    /// use <see cref="TriggerBuilder" /> to instantiate an actual Trigger.
    /// </summary>
    /// <remarks>
    /// <para>
    /// <see cref="ITrigger" />s have a <see cref="TriggerKey" /> associated with them, which
    /// should uniquely identify them within a single <see cref="IScheduler" />.
    /// </para>
    /// 
    /// <para>
    /// <see cref="ITrigger" />s are the 'mechanism' by which <see cref="IJob" /> s
    /// are scheduled. Many <see cref="ITrigger" /> s can point to the same <see cref="IJob" />,
    /// but a single <see cref="ITrigger" /> can only point to one <see cref="IJob" />.
    /// </para>
    /// 
    /// <para>
    /// Triggers can 'send' parameters/data to <see cref="IJob" />s by placing contents
    /// into the <see cref="JobDataMap" /> on the <see cref="ITrigger" />.
    /// </para>
    /// </remarks>
    /// <seealso cref="TriggerBuilder" />
    /// <seealso cref="ICalendarIntervalTrigger" />
    /// <seealso cref="ISimpleTrigger" />
    /// <seealso cref="ICronTrigger" />
    /// <seealso cref="IDailyTimeIntervalTrigger" />
    /// <seealso cref="JobDataMap" />
    /// <seealso cref="IJobExecutionContext" />
    /// <author>James House</author>
    /// <author>Sharada Jambula</author>
    /// <author>Marko Lahma (.NET)</author>
    public interface ITrigger : ICloneable, IComparable<ITrigger>
    {
        TriggerKey Key { get; }

    JobKey JobKey { get; }

    /// &lt;summary&gt;
    /// Get a &lt;see cref="TriggerBuilder" /&gt; that is configured to produce a 
    /// trigger identical to this one.
    /// &lt;/summary&gt;
    /// &lt;seealso cref="GetScheduleBuilder"/&gt;
    /// &lt;returns&gt;&lt;/returns&gt;
    TriggerBuilder GetTriggerBuilder();

    /// &lt;summary&gt;
    /// Get a &lt;see cref="IScheduleBuilder" /&gt; that is configured to produce a 
    /// schedule identical to this trigger's schedule.
    /// &lt;/summary&gt;
    /// &lt;returns&gt;&lt;/returns&gt;
    IScheduleBuilder GetScheduleBuilder();

    /// &lt;summary&gt;
    /// Get or set the description given to the &lt;see cref="ITrigger" /&gt; instance by
    /// its creator (if any).
    /// &lt;/summary&gt;
    string Description { get; }

    /// &lt;summary&gt;
    /// Get or set  the &lt;see cref="ICalendar" /&gt; with the given name with
    /// this Trigger. Use &lt;see langword="null" /&gt; when setting to dis-associate a Calendar.
    /// &lt;/summary&gt;
    string CalendarName { get; }

    /// &lt;summary&gt;
    /// Get or set the &lt;see cref="JobDataMap" /&gt; that is associated with the 
    /// &lt;see cref="ITrigger" /&gt;.
    /// &lt;para&gt;
    /// Changes made to this map during job execution are not re-persisted, and
    /// in fact typically result in an illegal state.
    /// &lt;/para&gt;
    /// &lt;/summary&gt;
    JobDataMap JobDataMap { get; }

    /// &lt;summary&gt;
    /// Returns the last UTC time at which the &lt;see cref="ITrigger" /&gt; will fire, if
    /// the Trigger will repeat indefinitely, null will be returned.
    /// &lt;para&gt;
    /// Note that the return time *may* be in the past.
    /// &lt;/para&gt;
    /// &lt;/summary&gt;
    DateTimeOffset? FinalFireTimeUtc { get; }

    /// &lt;summary&gt;
    /// Get or set the instruction the &lt;see cref="IScheduler" /&gt; should be given for
    /// handling misfire situations for this &lt;see cref="ITrigger" /&gt;- the
    /// concrete &lt;see cref="ITrigger" /&gt; type that you are using will have
    /// defined a set of additional MISFIRE_INSTRUCTION_XXX
    /// constants that may be set to this property.
    /// &lt;para&gt;
    /// If not explicitly set, the default value is &lt;see cref="Quartz.MisfireInstruction.InstructionNotSet" /&gt;.
    /// &lt;/para&gt;
    /// &lt;/summary&gt;
    /// &lt;seealso cref="Quartz.MisfireInstruction.InstructionNotSet" /&gt;
    /// &lt;seealso cref="ISimpleTrigger" /&gt;
    /// &lt;seealso cref="ICronTrigger" /&gt;
    int MisfireInstruction { get; }

    /// &lt;summary&gt;
    /// Gets and sets the date/time on which the trigger must stop firing. This 
    /// defines the final boundary for trigger firings &amp;#x8212; the trigger will
    /// not fire after to this date and time. If this value is null, no end time
    /// boundary is assumed, and the trigger can continue indefinitely.
    /// &lt;/summary&gt;
    DateTimeOffset? EndTimeUtc { get; }

    /// &lt;summary&gt;
    /// The time at which the trigger's scheduling should start.  May or may not
    /// be the first actual fire time of the trigger, depending upon the type of
    /// trigger and the settings of the other properties of the trigger.  However
    /// the first actual first time will not be before this date.
    /// &lt;/summary&gt;
    /// &lt;remarks&gt;
    /// Setting a value in the past may cause a new trigger to compute a first
    /// fire time that is in the past, which may cause an immediate misfire
    /// of the trigger.
    /// &lt;/remarks&gt;
    DateTimeOffset StartTimeUtc { get; }

    /// &lt;summary&gt;
    /// The priority of a &lt;see cref="ITrigger" /&gt; acts as a tie breaker such that if 
    /// two &lt;see cref="ITrigger" /&gt;s have the same scheduled fire time, then Quartz
    /// will do its best to give the one with the higher priority first access 
    /// to a worker thread.
    /// &lt;/summary&gt;
    /// &lt;remarks&gt;
    /// If not explicitly set, the default value is &lt;i&gt;5&lt;/i&gt;.
    /// &lt;/remarks&gt;
    /// &lt;returns&gt;&lt;/returns&gt;
    /// &lt;see cref="TriggerConstants.DefaultPriority" /&gt;
    int Priority { get; set; }

    /// &lt;summary&gt; 
    /// Used by the &lt;see cref="IScheduler" /&gt; to determine whether or not
    /// it is possible for this &lt;see cref="ITrigger" /&gt; to fire again.
    /// &lt;para&gt;
    /// If the returned value is &lt;see langword="false" /&gt; then the &lt;see cref="IScheduler" /&gt;
    /// may remove the &lt;see cref="ITrigger" /&gt; from the &lt;see cref="IJobStore" /&gt;.
    /// &lt;/para&gt;
    /// &lt;/summary&gt;
    bool GetMayFireAgain();

    /// &lt;summary&gt;
    /// Returns the next time at which the &lt;see cref="ITrigger" /&gt; is scheduled to fire. If
    /// the trigger will not fire again, &lt;see langword="null" /&gt; will be returned.  Note that
    /// the time returned can possibly be in the past, if the time that was computed
    /// for the trigger to next fire has already arrived, but the scheduler has not yet
    /// been able to fire the trigger (which would likely be due to lack of resources
    /// e.g. threads).
    /// &lt;/summary&gt;
    ///&lt;remarks&gt;
    /// The value returned is not guaranteed to be valid until after the &lt;see cref="ITrigger" /&gt;
    /// has been added to the scheduler.
    /// &lt;/remarks&gt;
    /// &lt;returns&gt;&lt;/returns&gt;
    DateTimeOffset? GetNextFireTimeUtc();

    /// &lt;summary&gt;
    /// Returns the previous time at which the &lt;see cref="ITrigger" /&gt; fired.
    /// If the trigger has not yet fired, &lt;see langword="null" /&gt; will be returned.
    /// &lt;/summary&gt;
    DateTimeOffset? GetPreviousFireTimeUtc();

    /// &lt;summary&gt;
    /// Returns the next time at which the &lt;see cref="ITrigger" /&gt; will fire,
    /// after the given time. If the trigger will not fire after the given time,
    /// &lt;see langword="null" /&gt; will be returned.
    /// &lt;/summary&gt;
    DateTimeOffset? GetFireTimeAfter(DateTimeOffset? afterTime);

    bool HasMillisecondPrecision { get; }

}

            Continue Reading

Quartz.Net &ndash; The IJobDetail Interface

This is another of the documentation series posts. This post will be documenting the IJobDetail interface. Here it is:

namespace Quartz
{
    /// <summary>
    /// Conveys the detail properties of a given job instance. 
    /// JobDetails are to be created/defined with <see cref="JobBuilder" />.
    /// </summary>
    /// <remarks>
    /// Quartz does not store an actual instance of a <see cref="IJob" /> type, but
    /// instead allows you to define an instance of one, through the use of a <see cref="IJobDetail" />.
    /// <para>
    /// <see cref="IJob" />s have a name and group associated with them, which
    /// should uniquely identify them within a single <see cref="IScheduler" />.
    /// </para>
    /// <para>
    /// <see cref="ITrigger" /> s are the 'mechanism' by which <see cref="IJob" /> s
    /// are scheduled. Many <see cref="ITrigger" /> s can point to the same <see cref="IJob" />,
    /// but a single <see cref="ITrigger" /> can only point to one <see cref="IJob" />.
    /// </para>
    /// </remarks>
    /// <seealso cref="IJob" />
    /// <seealso cref="DisallowConcurrentExecutionAttribute"/>
    /// <seealso cref="PersistJobDataAfterExecutionAttribute"/>
    /// <seealso cref="Quartz.JobDataMap"/>
    /// <seealso cref="ITrigger"/>
    /// <author>James House</author>
    /// <author>Marko Lahma (.NET)</author>
    public interface IJobDetail : ICloneable
    {
        /// <summary>
        /// The key that identifies this jobs uniquely.
        /// </summary>
        JobKey Key { get; }

    /// &lt;summary&gt;
    /// Get or set the description given to the &lt;see cref="IJob" /&gt; instance by its
    /// creator (if any).
    /// &lt;/summary&gt;
    string Description { get; }

    /// &lt;summary&gt;
    /// Get or sets the instance of &lt;see cref="IJob" /&gt; that will be executed.
    /// &lt;/summary&gt;
    Type JobType { get; }

    /// &lt;summary&gt;
    /// Get or set the &lt;see cref="JobDataMap" /&gt; that is associated with the &lt;see cref="IJob" /&gt;.
    /// &lt;/summary&gt;
    JobDataMap JobDataMap { get; }

    /// &lt;summary&gt;
    /// Whether or not the &lt;see cref="IJob" /&gt; should remain stored after it is
    /// orphaned (no &lt;see cref="ITrigger" /&gt;s point to it).
    /// &lt;/summary&gt;
    /// &lt;remarks&gt;
    /// If not explicitly set, the default value is &lt;see langword="false" /&gt;.
    /// &lt;/remarks&gt;
    /// &lt;returns&gt; 
    /// &lt;see langword="true" /&gt; if the Job should remain persisted after being orphaned.
    /// &lt;/returns&gt;
    bool Durable { get; }

    /// &lt;summary&gt;
    /// Whether the associated Job class carries the &lt;see cref="PersistJobDataAfterExecutionAttribute" /&gt;.
    /// &lt;/summary&gt;
    /// &lt;seealso cref="PersistJobDataAfterExecutionAttribute" /&gt;
    bool PersistJobDataAfterExecution { get; }

    /// &lt;summary&gt;
    /// Whether the associated Job class carries the &lt;see cref="DisallowConcurrentExecutionAttribute" /&gt;.
    /// &lt;/summary&gt;
    /// &lt;seealso cref="DisallowConcurrentExecutionAttribute"/&gt;
    bool ConcurrentExecutionDisallowed { get; }

    /// &lt;summary&gt;
    /// Set whether or not the the &lt;see cref="IScheduler" /&gt; should re-Execute
    /// the &lt;see cref="IJob" /&gt; if a 'recovery' or 'fail-over' situation is
    /// encountered.
    /// &lt;/summary&gt;
    /// &lt;remarks&gt;
    /// If not explicitly set, the default value is &lt;see langword="false" /&gt;.
    /// &lt;/remarks&gt;
    /// &lt;seealso cref="IJobExecutionContext.Recovering" /&gt;
    bool RequestsRecovery { get; }

    /// &lt;summary&gt;
    /// Get a &lt;see cref="JobBuilder" /&gt; that is configured to produce a 
    /// &lt;see cref="IJobDetail" /&gt; identical to this one.
    /// &lt;/summary&gt;
    JobBuilder GetJobBuilder();
}

            Continue Reading

Quartz.Net &ndash; The Quartz.IJob Interface

This post is part of the documenation series. It just provides a place to document some of the classes and interfaces that are not available in the API documentation.

In this post we are documenting the IJob interface. Without further ado, here it is:

namespace Quartz
{
	/// <summary> 
	/// The interface to be implemented by classes which represent a 'job' to be
	/// performed.
	/// </summary>
	/// <remarks>
	/// Instances of this interface must have a <see langword="public" />
	/// no-argument constructor. <see cref="JobDataMap" /> provides a mechanism for 'instance member data'
	/// that may be required by some implementations of this interface.
    /// </remarks>
	/// <seealso cref="IJobDetail" />
    /// <seealso cref="JobBuilder" />
    /// <seealso cref="DisallowConcurrentExecutionAttribute" />
    /// <seealso cref="PersistJobDataAfterExecutionAttribute" />
	/// <seealso cref="ITrigger" />
	/// <seealso cref="IScheduler" />
	/// <author>James House</author>
	/// <author>Marko Lahma (.NET)</author>
	public interface IJob
	{
		/// <summary>
		/// Called by the <see cref="IScheduler" /> when a <see cref="ITrigger" />
		/// fires that is associated with the <see cref="IJob" />.
        /// </summary>
		/// <remarks>
		/// The implementation may wish to set a  result object on the 
		/// JobExecutionContext before this method exits.  The result itself
		/// is meaningless to Quartz, but may be informative to 
		/// <see cref="IJobListener" />s or 
		/// <see cref="ITriggerListener" />s that are watching the job's 
		/// execution.
		/// </remarks>
		/// <param name="context">The execution context.</param>
        void Execute(IJobExecutionContext context);
	}
}
            Continue Reading

Quartz.NET 2 Tutorial - Lesson 1: Using Quartz

Lesson 1: Using Quartz

There are at least two ways to use Quartz.Net: embedded (hosted) in your application or as a standalone windows service.

Embedding Quartz.Net in Your Application

If you are going to host the Quartz.Net scheduler in your application, you’ll need to create a scheduler. This can be easily done through the scheduler factory provided in the distribution. The scheduler factory configures your scheduler for you.

Continue Reading