Quartz.Net – The ITrigger Interface

Jay Vilalta
Date : October 23, 2013
Categories : Quartz.net
Tags : Quartz.net ,V2 ,Documentation
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; }

}

}
Quartz.Net &ndash; The ITrigger Interface

Quartz.Net – The ITrigger Interface
