com.atlassian.scheduler.caesium.cron.rule

Class DateTimeTemplate

java.lang.Object

com.atlassian.scheduler.caesium.cron.rule.DateTimeTemplate

All Implemented Interfaces:

Cloneable

public class DateTimeTemplate
extends Object
implements Cloneable

A holder for the various numbers that comprise a date and time for the purpose of cron calculations.

This is kind of like a Joda-time Partial, but it is less whimsical and vastly more efficient. The Joda-time library is excellent at ensuring correctness at reasonable efficiency, but that is not what we are looking for. Cron expressions operate by producing a stream of numeric possibilities that may or may not be absurd, including things like February 30th and times that do not exist because they fall within daylight savings transition gaps, like 2014-10-05 02:30:00 for Australia/Sydney.

We do not want to be forbidden to set a value at all when it breaks the rules. This is what DateTime does, so we can't use that. Neither do we want the implementation to be so forgiving that when we ask for February 30th it decides that we really mean March 1st or 2nd, and that means that LocalDateTime is also a problem. What we really want is to be able to say "this will match on February 30th if that exists; if it doesn't, then I want to move on to the next thing to try, which is probably either March 1st or March 30th depending on what the other rules are, but let me worry about exactly how that works."

Now, this is something that Joda-time can deal with using Partial, but that interface is expensive and clunky. It is an immutable object, so the kind of manipulation we need to do while searching for the next run time would be more expensive than it makes sense for it to be. Really what I want here is MutablePartial, but no such animal exists.

Well, fine. Think about this as the MutablePartial that should have been but never was, and with a better name to boot.

Since:

v0.0.1

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	DateTimeTemplate.Field Represent one of the base fields of date information.

Constructor Summary

Constructors

Constructor and Description
DateTimeTemplate(Date date, org.joda.time.DateTimeZone zone)
DateTimeTemplate(org.joda.time.ReadableDateTime dateTime)

Method Summary

Modifier and Type	Method and Description
int	getDay()
int	getHour()
int	getMinute()
int	getMonth()
int	getSecond()
int	getYear()
org.joda.time.DateTimeZone	getZone()
void	setDay(int day)
void	setHour(int hour)
void	setMinute(int minute)
void	setMonth(int month)
void	setSecond(int second)
void	setYear(int year)
org.joda.time.DateTime	toDateTime() Converts this template into an immutable DateTime representation, if possible.
org.joda.time.LocalDate	toFirstOfMonth() Returns the first day of the month for the current year and month values, which must be valid.
String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

DateTimeTemplate

public DateTimeTemplate(org.joda.time.ReadableDateTime dateTime)

DateTimeTemplate

public DateTimeTemplate(Date date,
                        org.joda.time.DateTimeZone zone)

Method Detail

getYear

public int getYear()

setYear

public void setYear(int year)

getMonth

public int getMonth()

setMonth

public void setMonth(int month)

getDay

public int getDay()

setDay

public void setDay(int day)

getHour

public int getHour()

setHour

public void setHour(int hour)

getMinute

public int getMinute()

setMinute

public void setMinute(int minute)

getSecond

public int getSecond()

setSecond

public void setSecond(int second)

getZone

public org.joda.time.DateTimeZone getZone()

toFirstOfMonth

public org.joda.time.LocalDate toFirstOfMonth()

Returns the first day of the month for the current year and month values, which must be valid.

Returns:

the first day of the month for the current year and month values

Throws:

IllegalArgumentException - if the year or month is invalid

toDateTime

@Nullable
public org.joda.time.DateTime toDateTime()

Converts this template into an immutable DateTime representation, if possible.

As this object holds a set of numbers describing a hypothetical date and time that may or may not actually exist (due to differing days per month and existence of specific times at daylight savings transition gaps), it may not be possible to satisfy this request. If the combination of values is invalid, then null is returned.

For consistency with Quartz's arbitrary choice, if the numbers given fall within a daylight savings overlap, then the later instant is selected. For example, in the Australia/Sydney time zone, the clock moved from 2 A.M. back to 1 A.M. on 2014/04/06. The date-time values for 2014-04-06 01:30:00 return the moment corresponding to the 1:30 A.M. that occurs after the daylight savings transition, not the one before it.

toString

public String toString()

Overrides:

toString in class Object