A common requirement in many applications is to compare two dates, and to perform an action if the amount of time between them exceeds some threshold. For example "System will perform action X after 2 days".

As good programmers, we would never hard code the value "2", instead we would have some bean property ("actionXDays") that we would configure in our configuration file
(<property name=”actionXDays” value="2"/>).

But what if our requirement changes from 2 days to 2 hours? 2 months? 2 years? Suddenly it is not sufficient to change our configuration file alone, but also how we interpret the value (from days to whatever the new units are).

You could simply use a finer grain unit for your configuration property (i.e. hours instead of days), but I don’t like this solution for 2 reasons:

• It is not immediately clear from looking at the configuration file what the real value is (i.e. "actionXHours = 720" is actually "30 days")
• This fails completely for non-standard intervals (i.e. "actionXDays = 365" != "1 year" due to leap years).

The solution I developed for this problem is a very simple, but very handy, class called "TimeInterval".
A time interval is essentially a numerical value, along with the units that the value represents.

It also provides a static "date difference" method that properly finds the difference between two dates, with the results given in a specified unit.

For example: "Jan 2, 2006" – "Jan 1, 2006"

• If I request this difference in terms of days, I get 1.
• If I request this difference in terms of hours, I get 24.
• If I request this difference in terms of years, I get 0.

The TimeInterval also has a constructor that takes a String, where the string can take values such as "1 day", "30 days", "5 hours", "1 year", etc. Values like these go a long way in making a configuration file more readable.

So, to use this class, I would code by bean to have a
TimeInterval property:

MyClass {
    private TimeInterval actionXInterval;
    … getters/setters …
}

In my Spring configuration File, I would have

<bean id="myClass" class="MyClass">
     <property name="actionXInterval" value="2 days"/>
</bean>

Then the code would look something like:

Date actionXLastDate = //code to lookup last time action X occurred

long dateDiff =
    TimeInterval
       .dateDiff(new Date(),
                     actionXLastDate,
                     actionXInterval.getUnits());

if(dateDiff > actionXInterval.getInterval()) {
       // perform action X;
}

With this code, we can change not only the value, but
the units of the interval in the configuration file with out changing any code.

There is one caveat. There really is no clear definition for a difference between two dates in the unit of "months".

It’s easy to see that "Feb 1, 2006" – "Jan 1, 2006" = "1 month"
("month" difference is fairly well understood for the graph of all months to all days less than or equal to 28)

But what about "Feb 28, 2006" - "Jan 31, 2006"?

Is this one month, since it is "last day of January to the last day February", or is it less than one month since, in an ideal world, 1 month from "Jan 31" would be "Feb 31"?

I have come up with my own definition of "month difference", which I document in the Javadoc, but that definition is arbitrary. So if your requirements specify an interval in months, either make sure that your actions occur on a day less than the 29^th, or request the requirements be changed to multiples of 30 days.